Difference between revisions of "Database Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 1: Line 1:
−
<p>This module contains methods to list and open databases, explicitly apply available index structures, or get information on the database structure. All functions are introduced with the <code>db:</code> prefix.</p>  
+
<p>This module offers utility methods, which can be used for testing and profiling the code. All functions are preceded by the <code>util:</code> prefix. </p>
−
==db:system==
 
  
−
{|
+
==util:eval==
−
|-
 
−
| width="90" | <b>Signatures</b>
 
−
|<code><b>db:system</b>() as xs:string*</code>
 
−
 
 
−
|-
 
−
| <b>Summary</b>
 
−
| Lists information on the database system.
 
−
|-
 
−
| <b>Rules</b>
 
−
| This function returns general information on the database system, such as the database path and current database settings.<br />
 
−
|}
 
  
−
==db:list==
 
 
{|
 
{|
 
|-
 
|-
 
| width="90" | <b>Signatures</b>
 
| width="90" | <b>Signatures</b>
−
|<code><b>db:list</b>() as xs:string*</code>  
+
|<code><b>util:eval</b>($expr as xs:string) as item()*</code>
 
|-
 
|-
 
| <b>Summary</b>
 
| <b>Summary</b>
−
| Lists all databases.
+
| Evaluates the argument at runtime.
 
|-
 
|-
 
| <b>Rules</b>
 
| <b>Rules</b>
−
| This function returns a <code>xs:string</code> sequence with the names of all databases.<br />
+
| This function dynamically evaluates <code>$expr</code> as XQuery expression and returns the resulting items.<br />
−
|}
 
−
 
 
−
==db:open==
 
−
{|
 
−
|-
 
−
| width="90" | <b>Signatures</b>
 
−
|<code><b>db:open</b>($name as xs:string) as document-node()</code>
 
−
|-
 
−
| <b>Summary</b>
 
−
| Returns documents from a database.
 
−
|-
 
−
| <b>Rules</b>
 
−
| This function opens the documents of the database specified by <code>$name</code>. The name of the database may be extended by a collection path.<br />
 
 
|-
 
|-
 
| <b>Examples</b>
 
| <b>Examples</b>
−
| The expression <code>db:open("docs")</code> returns all documents from the database named <code>docs</code>.<br />The expression <code>db:open("docs/one")</code> returns all documents from the database named <code>docs</code> in the subpath <code>one</code>.<br />
+
| The expression <code>util:eval("1+3")</code> returns <code>4</code>.<br />
−
|-
 
−
| <b>Errors</b>
 
−
| <b>[BASX0003]</b> is raised if the database is not found.<br />
 
 
|}
 
|}
  
−
==db:open-pre==  
+
==util:run==  
−
{|
 
−
|-
 
−
| width="90" | <b>Signatures</b>
 
−
|<code> <b>db:open-pre</b>($name as xs:string, $pre as xs:integer) as node()</code>
 
−
|-
 
−
| <b>Summary</b>
 
−
| Returns a specific database node.
 
−
|-
 
−
| <b>Rules</b>
 
−
| This function opens the database specified by <code>$name</code> and returns the node with the <i>pre</i> value specified by <code>$pre</code>.<br />
 
−
|-
 
−
| <b>Examples</b>
 
−
| The expression <code>db:open-pre("docs", 0)</code> returns the first database node from the database named <code>docs</code>.<br />
 
−
|-
 
−
| <b>Errors</b>
 
−
| <b>[BASX0004]</b> is raised if the specified <code>$pre</code> value does not exist in the database.<br />
 
−
|}
 
  
−
==db:open-id==
 
 
{|
 
{|
 
|-
 
|-
 
| width="90" | <b>Signatures</b>
 
| width="90" | <b>Signatures</b>
−
|<code><b>db:open-id</b>($name as xs:string, $id as xs:integer) as node()</code>  
+
|<code><b>util:run</b>($input as xs:string) as item()*</code>
 
|-
 
|-
 
| <b>Summary</b>
 
| <b>Summary</b>
−
| Returns a specific database node.
+
| Opens the argument as file and evaluates it as at runtime.
 
|-
 
|-
 
| <b>Rules</b>
 
| <b>Rules</b>
−
| This function opens the database specified by <code>$name</code> and returns the node with the <i>id</i> value specified by <code>$id</code>.<br />In contrast to the <i>pre</i> value, the <i>id</i> will remain valid after update operations.<br />
+
| This function opens <code>$input</code> as file, evaluates it as XQuery expression, and returns the resulting items.<br />
−
|-
 
−
| <b>Errors</b>
 
−
| <b>[BASX0004]</b> is raised if the specified <code>$id</code> does not exist in the database.<br />
 
 
|}
 
|}
  
−
==db:text-index==  
+
==util:mb==  
−
{|
 
−
|-
 
−
| width="90" | <b>Signatures</b>
 
−
|<code><b>db:text-index</b>($string as item()) as text()*</code>
 
−
|-
 
−
| <b>Summary</b>
 
−
| Returns results from a text index request.
 
−
|-
 
−
| <b>Rules</b>
 
−
| This function accesses the text index and returns all text nodes that have <code>$string</code> as string value.<br />
 
−
|-
 
−
| <b>Errors</b>
 
−
|<b>[BASX0001]</b> is raised if the index is not available.<br /> <b>[BASX0002]</b> is raised if the context item does not represent a database node.<br />
 
−
|}
 
  
−
==db:attribute-index==
 
 
{|
 
{|
 
|-
 
|-
 
| width="90" | <b>Signatures</b>
 
| width="90" | <b>Signatures</b>
−
|<code><b>db:attribute-index</b>($string as item()) as attribute()*</code> <br /> <code> <b>db:attribute-index</b>($string as item(), $name as xs:string) as attribute()*</code>  
+
|<code><b>util:mb</b>($expr as item()) as xs:double</code>
 +
|<code><b>util:mb</b>($expr as item(), $cache as xs:boolean) as xs:double</code>
 
|-
 
|-
 
| <b>Summary</b>
 
| <b>Summary</b>
−
| Returns results from a attribute index request.
+
| Measures the memory consumption for evaluating the argument.
 
|-
 
|-
 
| <b>Rules</b>
 
| <b>Rules</b>
−
| This function accesses the attribute index and returns all attribute nodes that have <code>$string</code> as string value.<br />If <code>$name</code> is specified, the resulting attribute nodes are filtered by their attribute name.<br />
+
| This function measures the amount of memory that is needed to evaluate <code>$expr</code>. If the value of <code>$cache</code> is <code>true()</code>, the result will be cached. The returned <code>xs:double</code> value represents the amount of memory in megabytes.<br />
 
|-
 
|-
−
| <b>Errors</b>
+
| <b>Examples</b>
−
|<b>[BASX0001]</b> is raised if the index is not available.<br /><b>[BASX0002]</b> is raised if the context item does not represent a database node.
+
| The expression <code>util:mb("1 to 100000")</code> might return <code>0</code>.<br />The expression <code>util:mb("1 to 100000", true())</code> might return <code>26.678</code>.<br />
 
|}
 
|}
 +
 +
==util:ms==
  
−
==db:fulltext-index==
 
 
{|
 
{|
 
|-
 
|-
 
| width="90" | <b>Signatures</b>
 
| width="90" | <b>Signatures</b>
−
|<code><b>db:fulltext-index</b>($text as xs:string) as text()</code>  
+
|<code><b>util:ms</b>($expr as item()) as xs:double</code>
 +
|<code><b>util:ms</b>($expr as item(), $cache as xs:boolean) as xs:double</code>
 
|-
 
|-
 
| <b>Summary</b>
 
| <b>Summary</b>
−
| Returns results from a full-text index request.
+
| Measures the time needed for evaluating the argument.
 
|-
 
|-
 
| <b>Rules</b>
 
| <b>Rules</b>
−
| This function accesses the full-text index and returns all text nodes that contain <code>$text</code>.<br />
+
| This function measures the time needed to evaluate <code>$expr</code>. If the value of <code>$cache</code> is <code>true()</code>, the result will be cached. The returned <code>xs:double</code> value represents the needed time in milliseconds.<br />
 
|-
 
|-
−
| <b>Errors</b>
+
| <b>Examples</b>
−
|<b>[BASX0001]</b> is raised if the index is not available.<br /> <b>[BASX0002]</b> is raised if the context item does not represent a database node.<br />
+
| The expression <code>util:ms("1 to 100000")</code> might return <code>25.69</code>.<br />The expression <code>util:ms("1 to 100000", true())</code> might return <code>208.12</code>.<br />  
−
|}
 
−
 
 
−
==db:info==
 
−
{|
 
−
|-
 
−
| width="90" | <b>Signatures</b>
 
−
|<code> <b>db:info</b>() as xs:string</code>  
 
−
|-
 
−
| <b>Summary</b>
 
−
| Returns database information.
 
−
|-
 
−
| <b>Rules</b>
 
−
| This function returns information on the database that is referenced by the current context item.<br />
 
−
|-
 
−
| <b>Errors</b>
 
−
|<b>[[BASX0002]]</b> is raised if the context item does not represent a database node.<br />
 
 
|}
 
|}
  
−
==db:index-info==
+
[[Category:XQuery]]
−
{|
 
−
|-
 
−
| width="90" | <b>Signatures</b>
 
−
| <code> <b>db:index-info</b>($type as xs:string) as xs:string</code>
 
−
|-
 
−
| <b>Summary</b>
 
−
| Returns database index information.
 
−
|-
 
−
| <b>Rules</b>
 
−
| This function returns information on an index of the database that is referenced by the current context item.<br /> <code>$type</code> must be one of the values <code>TEXT</code>, <code>ATTRIBUTE</code>, <code>FULLTEXT</code>, <code>PATH</code>, <code>TAG</code>, or <code>ATTNAME</code>.<br />
 
−
|-
 
−
| <b>Errors</b>
 
−
| <b>[BASX0001]</b> is raised if the specified index is not available.<br /> <b>[BASX0002]</b> is raised if the context item does not represent a database node.<br />
 
−
|}
 
−
[[Category:Commands]]
 
−
[[Category:Wikify]]
 

Revision as of 16:35, 12 December 2010

This module offers utility methods, which can be used for testing and profiling the code. All functions are preceded by the util: prefix.

util:eval

Signatures util:eval($expr as xs:string) as item()*
Summary Evaluates the argument at runtime.
Rules This function dynamically evaluates $expr as XQuery expression and returns the resulting items.
Examples The expression util:eval("1+3") returns 4.

util:run

Signatures util:run($input as xs:string) as item()*
Summary Opens the argument as file and evaluates it as at runtime.
Rules This function opens $input as file, evaluates it as XQuery expression, and returns the resulting items.

util:mb

Signatures util:mb($expr as item()) as xs:double util:mb($expr as item(), $cache as xs:boolean) as xs:double
Summary Measures the memory consumption for evaluating the argument.
Rules This function measures the amount of memory that is needed to evaluate $expr. If the value of $cache is true(), the result will be cached. The returned xs:double value represents the amount of memory in megabytes.
Examples The expression util:mb("1 to 100000") might return 0.
The expression util:mb("1 to 100000", true()) might return 26.678.

util:ms

Signatures util:ms($expr as item()) as xs:double util:ms($expr as item(), $cache as xs:boolean) as xs:double
Summary Measures the time needed for evaluating the argument.
Rules This function measures the time needed to evaluate $expr. If the value of $cache is true(), the result will be cached. The returned xs:double value represents the needed time in milliseconds.
Examples The expression util:ms("1 to 100000") might return 25.69.
The expression util:ms("1 to 100000", true()) might return 208.12.
Retrieved from "http://docs.basex.org/index.php?title=Database_Module&oldid=438"