Difference between revisions of "Database Module"
Jump to navigation
Jump to search
Line 5: | Line 5: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:system</b>() as xs:string</code | + | |<code><b>db:system</b>() as xs:string</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
− | |Lists information on the database system, including the database path and current database settings. | + | |Lists information on the database system, including the database path and current database settings. |
|} | |} | ||
Line 15: | Line 15: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:list</b>() as xs:string*</code | + | |<code><b>db:list</b>() as xs:string*</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
− | |Returns an <code>xs:string</code> sequence with the names of all databases. | + | |Returns an <code>xs:string</code> sequence with the names of all databases. |
|} | |} | ||
Line 25: | Line 25: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:open</b>($name as xs:string) as document-node()*</code | + | |<code><b>db:open</b>($name as xs:string) as document-node()*</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
− | |Returns a sequence with all document nodes contained in the database specified by <code>$name</code>. The name of the database may be extended by a collection path.< | + | |Returns a sequence with all document nodes contained in the database specified by <code>$name</code>. The name of the database may be extended by a collection path. |
+ | |- | ||
+ | | valign='top' | '''Errors''' | ||
+ | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0003]]</b> is raised if the database is not found. | ||
|- | |- | ||
| valign='top' | '''Examples''' | | valign='top' | '''Examples''' | ||
− | | | + | | |
− | + | * <code>db:open("docs")</code> returns all documents from the database named <code>docs</code>. | |
− | + | * <code>db:open("docs/one")</code> returns all documents from the database named <code>docs</code> in the subpath <code>one</code>. | |
− | |||
|} | |} | ||
Line 41: | Line 43: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:open-pre</b>($name as xs:string, $pre as xs:integer) as node()</code | + | |<code><b>db:open-pre</b>($name as xs:string, $pre as xs:integer) as node()</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
− | |Opens the database specified by <code>$name</code> and returns the node with the specified <code>$pre</code> value.< | + | |Opens the database specified by <code>$name</code> and returns the node with the specified <code>$pre</code> value. |
+ | |- | ||
+ | | valign='top' | '''Errors''' | ||
+ | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0004]]</b> is raised if the specified <code>$pre</code> value does not exist in the database. | ||
|- | |- | ||
| valign='top' | '''Examples''' | | valign='top' | '''Examples''' | ||
− | | | + | | |
− | + | * <code>db:open-pre("docs", 0)</code> returns the first database node from the database named <code>docs</code>. | |
− | |||
− | |||
|} | |} | ||
Line 57: | Line 60: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:open-id</b>($name as xs:string, $id as xs:integer) as node()</code | + | |<code><b>db:open-id</b>($name as xs:string, $id as xs:integer) as node()</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
− | |Opens the database specified by <code>$name</code> and returns the node with the specified <code>$id</code> value.<br />In contrast to the <i>pre</i> value, the <i>id</i> will remain valid after update operations. | + | |Opens the database specified by <code>$name</code> and returns the node with the specified <code>$id</code> value.<br />In contrast to the <i>pre</i> value, the <i>id</i> will remain valid after update operations. |
|- | |- | ||
| valign='top' | '''Errors''' | | valign='top' | '''Errors''' | ||
− | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0004]]</b> is raised if the specified <code>$id</code> does not exist in the database. | + | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0004]]</b> is raised if the specified <code>$id</code> does not exist in the database. |
|} | |} | ||
Line 70: | Line 73: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:node-pre</b>($nodes as node()*) as xs:integer*</code | + | |<code><b>db:node-pre</b>($nodes as node()*) as xs:integer*</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
− | |Returns the <i>pre</i> values of all database nodes specified by <code>$nodes</code>. <i>pre</i> values are direct, internal pointers to database nodes, which might be changed by updates. | + | |Returns the <i>pre</i> values of all database nodes specified by <code>$nodes</code>. <i>pre</i> values are direct, internal pointers to database nodes, which might be changed by updates. |
|- | |- | ||
| valign='top' | '''Examples''' | | valign='top' | '''Examples''' | ||
− | | | + | | |
+ | * <code>db:node-pre(doc("input"))</code> returns <code>0</code> if the database <code>input</code> contains a single document. | ||
|} | |} | ||
Line 83: | Line 87: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:node-id</b>($nodes as node()*) as xs:integer*</code | + | |<code><b>db:node-id</b>($nodes as node()*) as xs:integer*</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
− | |Returns the <i>id</i> values of all database nodes specified by <code>$nodes</code>. <i>id</i> values are pointers to database nodes, which are not changed by updates. | + | |Returns the <i>id</i> values of all database nodes specified by <code>$nodes</code>. <i>id</i> values are pointers to database nodes, which are not changed by updates. |
|} | |} | ||
Line 93: | Line 97: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:text</b>($string as item()) as text()*</code | + | |<code><b>db:text</b>($string as item()) as text()*</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
− | |Returns all text nodes from the text index that have <code>$string</code> as their string value.<br /> | + | |Returns all text nodes from the text index that have <code>$string</code> as their string value. |
+ | |- | ||
+ | | valign='top' | '''Errors''' | ||
+ | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0001]]</b> is raised if the index is not available.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0002]]</b> is raised if the context item does not represent a database node. | ||
|- | |- | ||
| valign='top' | '''Examples''' | | valign='top' | '''Examples''' | ||
− | | | + | | |
− | + | * <code>db:text("QUERY")</code> returns all text nodes of the currently opened database that match the string <code>QUERY</code>. | |
− | + | * <code>db:open("DB")/db:text("QUERY")/..</code> returns the parents of all text nodes of the database <code>DB</code> that match the string <code>QUERY</code>. | |
− | |||
|} | |} | ||
Line 109: | Line 115: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:attribute</b>($string as item()) as attribute()*</code><br /><code><b>db:attribute</b>($string as item(), $name as xs:string) as attribute()*</code | + | |<code><b>db:attribute</b>($string as item()) as attribute()*</code><br/><code><b>db:attribute</b>($string as item(), $name as xs:string) as attribute()*</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
− | |Returns all attribute nodes from the attribute index that have <code>$string</code> as their string value.<br />If <code>$name</code> is specified, the resulting attribute nodes are filtered by their attribute name.<br /> | + | |Returns all attribute nodes from the attribute index that have <code>$string</code> as their string value.<br />If <code>$name</code> is specified, the resulting attribute nodes are filtered by their attribute name. |
+ | |- | ||
+ | | valign='top' | '''Errors''' | ||
+ | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0001]]</b> is raised if the index is not available.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0002]]</b> is raised if the context item does not represent a database node. | ||
|- | |- | ||
| valign='top' | '''Examples''' | | valign='top' | '''Examples''' | ||
− | | | + | | |
− | + | * <code>db:open("DB")/db:attribute("QUERY", "id")/..</code> returns the parents of all attribute nodes of the database <code>DB</code> that have <code>QUERY</code> as string value. | |
− | |||
− | |||
|} | |} | ||
Line 125: | Line 132: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:fulltext</b>($text as xs:string) as text()</code | + | |<code><b>db:fulltext</b>($text as xs:string) as text()</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
− | |Returns all text nodes from the full-text index that contain the string <code>$text</code>. The index full-text options are used for searching, i.e., if the index terms were stemmed, the search string will be stemmed as well.<br /> | + | |Returns all text nodes from the full-text index that contain the string <code>$text</code>. The index full-text options are used for searching, i.e., if the index terms were stemmed, the search string will be stemmed as well. |
+ | |- | ||
+ | | valign='top' | '''Errors''' | ||
+ | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0001]]</b> is raised if the index is not available.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0002]]</b> is raised if the context item does not represent a database node. | ||
|- | |- | ||
| valign='top' | '''Examples''' | | valign='top' | '''Examples''' | ||
− | | | + | | |
− | + | * <code>db:fulltext("QUERY")</code> returns all text nodes of the currently opened database that contain the string <code>QUERY</code>. | |
− | |||
− | |||
|} | |} | ||
Line 141: | Line 149: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:info</b>() as xs:string</code><br /><code><b>db:info</b>($type as xs:string) as xs:string</code | + | |<code><b>db:info</b>() as xs:string</code><br/><code><b>db:info</b>($type as xs:string) as xs:string</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
− | |Returns information on the database that is referenced by the current context item.<br />If <code>$type</code> is specified, the function returns information on a database index. It 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>. | + | |Returns information on the database that is referenced by the current context item.<br />If <code>$type</code> is specified, the function returns information on a database index. It 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>. |
|- | |- | ||
| valign='top' | '''Errors''' | | valign='top' | '''Errors''' | ||
− | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0001]]</b> is raised if the specified index is not available.<br /><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0002]]</b> is raised if the context item does not represent a database node. | + | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0001]]</b> is raised if the specified index is not available.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0002]]</b> is raised if the context item does not represent a database node. |
|} | |} | ||
[[Category:XQuery]] | [[Category:XQuery]] |
Revision as of 16:13, 23 April 2011
This module contains XQuery Functions to list and open databases, explicitly apply available index structures, or get information on the database structure. All functions are introduced with the db:
prefix, which is linked to the http://www.basex.org/db
namespace.
Contents
db:system
Signatures | db:system() as xs:string
|
Summary | Lists information on the database system, including the database path and current database settings. |
db:list
Signatures | db:list() as xs:string*
|
Summary | Returns an xs:string sequence with the names of all databases.
|
db:open
Signatures | db:open($name as xs:string) as document-node()*
|
Summary | Returns a sequence with all document nodes contained in the database specified by $name . The name of the database may be extended by a collection path.
|
Errors | BASX0003 is raised if the database is not found. |
Examples |
|
db:open-pre
Signatures | db:open-pre($name as xs:string, $pre as xs:integer) as node()
|
Summary | Opens the database specified by $name and returns the node with the specified $pre value.
|
Errors | BASX0004 is raised if the specified $pre value does not exist in the database.
|
Examples |
|
db:open-id
Signatures | db:open-id($name as xs:string, $id as xs:integer) as node()
|
Summary | Opens the database specified by $name and returns the node with the specified $id value.In contrast to the pre value, the id will remain valid after update operations. |
Errors | BASX0004 is raised if the specified $id does not exist in the database.
|
db:node-pre
Signatures | db:node-pre($nodes as node()*) as xs:integer*
|
Summary | Returns the pre values of all database nodes specified by $nodes . pre values are direct, internal pointers to database nodes, which might be changed by updates.
|
Examples |
|
db:node-id
Signatures | db:node-id($nodes as node()*) as xs:integer*
|
Summary | Returns the id values of all database nodes specified by $nodes . id values are pointers to database nodes, which are not changed by updates.
|
db:text
Signatures | db:text($string as item()) as text()*
|
Summary | Returns all text nodes from the text index that have $string as their string value.
|
Errors | BASX0001 is raised if the index is not available. BASX0002 is raised if the context item does not represent a database node. |
Examples |
|
db:attribute
Signatures | db:attribute($string as item()) as attribute()* db:attribute($string as item(), $name as xs:string) as attribute()*
|
Summary | Returns all attribute nodes from the attribute index that have $string as their string value.If $name is specified, the resulting attribute nodes are filtered by their attribute name.
|
Errors | BASX0001 is raised if the index is not available. BASX0002 is raised if the context item does not represent a database node. |
Examples |
|
db:fulltext
Signatures | db:fulltext($text as xs:string) as text()
|
Summary | Returns all text nodes from the full-text index that contain the string $text . The index full-text options are used for searching, i.e., if the index terms were stemmed, the search string will be stemmed as well.
|
Errors | BASX0001 is raised if the index is not available. BASX0002 is raised if the context item does not represent a database node. |
Examples |
|
db:info
Signatures | db:info() as xs:string db:info($type as xs:string) as xs:string
|
Summary | Returns information on the database that is referenced by the current context item. If $type is specified, the function returns information on a database index. It must be one of the values TEXT , ATTRIBUTE , FULLTEXT , PATH , TAG , or ATTNAME .
|
Errors | BASX0001 is raised if the specified index is not available. BASX0002 is raised if the context item does not represent a database node. |