Difference between revisions of "Database Module"
Jump to navigation
Jump to search
Line 1: | Line 1: | ||
− | This module contains [[Querying#Functions|XQuery functions]] | + | This module contains [[Querying#Functions|XQuery functions]] for handling databases from within XQuery. Existing databases can be opened and listed, index structures can be directly accessed, documents can be added to and removed from collections, etc. All functions are introduced with the <code>db:</code> prefix, which is linked to the <code>http://www.basex.org/db</code> namespace. |
− | |||
− | |||
==db:system== | ==db:system== | ||
Line 45: | Line 43: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:open-pre</b>($ | + | |<code><b>db:open-pre</b>($db as item(), $pre as xs:integer) as node()</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
Line 62: | Line 60: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:open-id</b>($ | + | |<code><b>db:open-id</b>($db as item(), $id as xs:integer) as node()</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
Line 99: | Line 97: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:text</b>($ | + | |<code><b>db:text</b>($db as item(), $string as item()) as text()*</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
Line 113: | Line 111: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:attribute</b>($ | + | |<code><b>db:attribute</b>($db as item(), $string as item()) as attribute()*</code><br/><code><b>db:attribute</b>($db as item(), $string as item(), $attname as xs:string) as attribute()*</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
Line 127: | Line 125: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:fulltext</b>($ | + | |<code><b>db:fulltext</b>($db as item(), $text as item()) as text()*</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
Line 144: | Line 142: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>db:info</b>($ | + | |<code><b>db:info</b>($db as item()) as xs:string</code><br/><code><b>db:info</b>($db as item(), $type as xs:string) as xs:string</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
Line 151: | Line 149: | ||
| valign='top' | '''Errors''' | | valign='top' | '''Errors''' | ||
|<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0001]]</b> is raised if the specified index is not available. | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0001]]</b> is raised if the specified index is not available. | ||
+ | |- | ||
+ | | valign='top' | '''Examples''' | ||
+ | | | ||
+ | * <code>db:info("DB", "FULLTEXT")</code> returns information about the full-text index in the database <code>DB</code>. | ||
+ | |} | ||
+ | |||
+ | ==db:add== | ||
+ | {| | ||
+ | |- | ||
+ | | valign='top' width='90' | '''Signatures''' | ||
+ | |<code><b>db:add</b>($db as item(), $input as item()*) as empty-sequence()</code><br/><code><b>db:add</b>($db as item(), $input as item()*, $name as xs:string) as empty-sequence()</code><br/><code><b>db:add</b>($db as item(), $input as item()*, $name as xs:string, $path as xs:string) as empty-sequence()</code> | ||
+ | |- | ||
+ | | valign='top' | '''Summary''' | ||
+ | |Add documents specified by <code>$input</code> to the database <code>$db</code>, using an optional document name <code>$name</code> and an optional path <code>$path</code>. | ||
+ | |- | ||
+ | | valign='top' | '''Errors''' | ||
+ | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0002]]</b> is raised if <code>$db</code> is not a database node.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0003]]</b> is raised if <code>$db</code> is a string and a database with that name cannot be open.<br/><b>[[XQuery Errors#Functions Errors (FOAR, FOCA, FOCH, FODC, FODF, FODT, FOER, FOFD, FONS, FORG, FORX)|FODC0002]]</b> is raised if <code>$input</code> is a string representing a path, which cannot be read.<br/><b>[[XQuery Errors#Update Errors (FOUP, XUDY, XUST, XUTY)|FOUP0001]]</b> is raised if <code>$input</code> is not a string and not a document node. | ||
+ | |- | ||
+ | | valign='top' | '''Examples''' | ||
+ | | | ||
+ | * <code>db:add("DB", "/home/dir/doc.xml")</code> adds the file <code>/home/dir/doc.xml</code> to the database <code>DB</code>. | ||
+ | * <code>db:add("DB", "<a/>", "doc.xml")</code> adds a document with content <code><a/></code> to the database <code>DB</code> under the name <code>doc.xml</code>. | ||
+ | * <code>db:add("DB", document { <a/> }, "doc.xml")</code> adds the document node to the database <code>DB</code> under the name <code>doc.xml</code>. | ||
+ | * <code>db:add("DB", "/home/dir", "", "docs/dir")</code> adds all documents in <code>/home/dir</code> to the database <code>DB</code> under the path <code>docs/dir</code>. | ||
+ | |} | ||
+ | |||
+ | ==db:replace== | ||
+ | {| | ||
+ | |- | ||
+ | | valign='top' width='90' | '''Signatures''' | ||
+ | |<code><b>db:replace</b>($db as item(), $path as xs:string, $input as item()) as empty-sequence()</code> | ||
+ | |- | ||
+ | | valign='top' | '''Summary''' | ||
+ | |Replace a document, specified by <code>$path</code> in the database <code>$db</code> with the content of <code>$input</code>. | ||
+ | |- | ||
+ | | valign='top' | '''Errors''' | ||
+ | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0002]]</b> is raised if <code>$db</code> is not a database node.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0003]]</b> is raised if <code>$db</code> is a string and a database with that name cannot be open.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0012]]</b> is raised if <code>$path</code> is not a single document path.<br/><b>[[XQuery Errors#Functions Errors (FOAR, FOCA, FOCH, FODC, FODF, FODT, FOER, FOFD, FONS, FORG, FORX)|FODC0002]]</b> is raised if <code>$input</code> is a string representing a path, which cannot be read.<br/><b>[[XQuery Errors#Update Errors (FOUP, XUDY, XUST, XUTY)|FOUP0001]]</b> is raised if <code>$input</code> is not a string and not a document node. | ||
+ | |- | ||
+ | | valign='top' | '''Examples''' | ||
+ | | | ||
+ | * <code>db:replace("DB", "docs/dir/doc.xml", "/home/dir/doc.xml")</code> replaces the content of the document <code>docs/dir/doc.xml</code> in the database <code>DB</code> with the content of the file <code>/home/dir/doc.xml</code>. | ||
+ | * <code>db:replace("DB", "docs/dir/doc.xml", "<a/>")</code> replaces the content of the document <code>docs/dir/doc.xml</code> in the database <code>DB</code> with <code><a/></code>. | ||
+ | * <code>db:replace("DB", "docs/dir/doc.xml", document { <a/> })</code> replaces the content of the document <code>docs/dir/doc.xml</code> in the database <code>DB</code> with the specified document node. | ||
+ | |} | ||
+ | |||
+ | ==db:delete== | ||
+ | {| | ||
+ | |- | ||
+ | | valign='top' width='90' | '''Signatures''' | ||
+ | |<code><b>db:delete</b>($db as item(), $path as xs:string) as empty-sequence()</code> | ||
+ | |- | ||
+ | | valign='top' | '''Summary''' | ||
+ | |Delete document(s), specified by <code>$path</code> in the database <code>$db</code>. | ||
+ | |- | ||
+ | | valign='top' | '''Errors''' | ||
+ | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0002]]</b> is raised if <code>$db</code> is not a database node.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0003]]</b> is raised if <code>$db</code> is a string and a database with that name cannot be open. | ||
+ | |- | ||
+ | | valign='top' | '''Examples''' | ||
+ | | | ||
+ | * <code>db:delete("DB", "docs/dir/doc.xml")</code> deletes the document <code>docs/dir/doc.xml</code> in the database <code>DB</code>. | ||
+ | * <code>db:delete("DB", "docs/dir", "<a/>")</code> deletes all documents with paths beginning with <code>docs/dir</code> in the database <code>DB</code>. | ||
+ | |} | ||
+ | |||
+ | ==db:rename== | ||
+ | {| | ||
+ | |- | ||
+ | | valign='top' width='90' | '''Signatures''' | ||
+ | |<code><b>db:rename</b>($db as item(), $path as xs:string, $newpath as xs:string) as empty-sequence()</code> | ||
+ | |- | ||
+ | | valign='top' | '''Summary''' | ||
+ | |Rename document(s), specified by <code>$path</code> to <code>$newpath</code> in the database <code>$db</code>. | ||
+ | |- | ||
+ | | valign='top' | '''Errors''' | ||
+ | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0002]]</b> is raised if <code>$db</code> is not a database node.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0003]]</b> is raised if <code>$db</code> is a string and a database with that name cannot be open.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0013]]</b> is raised if new document name(s) will be empty. | ||
+ | |- | ||
+ | | valign='top' | '''Examples''' | ||
+ | | | ||
+ | * <code>db:rename("DB", "docs/dir/doc.xml", "docs/dir/newdoc.xml")</code> renames the document <code>docs/dir/doc.xml</code> to <code>docs/dir/newdoc.xml</code> in the database <code>DB</code>. | ||
+ | * <code>db:rename("DB", "docs/dir", "docs/newdir")</code> renames all documents with paths beginning with <code>docs/dir</code> to paths beginning with <code>docs/newdir</code> in the database <code>DB</code>. | ||
+ | |} | ||
+ | |||
+ | ==db:optimize== | ||
+ | {| | ||
+ | |- | ||
+ | | valign='top' width='90' | '''Signatures''' | ||
+ | |<code><b>db:optimize</b>($db as xs:string) as empty-sequence()</code><br/><code><b>db:optimize</b>($db as xs:string, $all as xs:boolean) as empty-sequence()</code> | ||
+ | |- | ||
+ | | valign='top' | '''Summary''' | ||
+ | |Optimize the data structures of the database <code>$db</code>. If <code>$all</code> is set to <code>true()</code>, then the whole database will be rebuilt. | ||
+ | |- | ||
+ | | valign='top' | '''Errors''' | ||
+ | |<b>[[XQuery Errors#BaseX Errors (BASX)|BASX0002]]</b> is raised if <code>$db</code> is not a database node.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0003]]</b> is raised if <code>$db</code> is a string and a database with that name cannot be open.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0014]]</b> is raised if an error occurs during optimizing the data structures.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0015]]</b> is raised if the <code>$all</code> flag is set to <code>true()</code>, but the database is an in-memory database.<br/><b>[[XQuery Errors#BaseX Errors (BASX)|BASX0016]]</b> is raised if the database <code>$db</code> is in use by other user(s). | ||
+ | |- | ||
+ | | valign='top' | '''Examples''' | ||
+ | | | ||
+ | * <code>db:optimize("DB")</code> optimizes the database structures of the database <code>DB</code>. | ||
+ | * <code>db:optimize("DB", true())</code> optimizes all database structures of the database <code>DB</code>. | ||
|} | |} | ||
[[Category:XQuery]] | [[Category:XQuery]] |
Revision as of 22:20, 28 July 2011
This module contains XQuery functions for handling databases from within XQuery. Existing databases can be opened and listed, index structures can be directly accessed, documents can be added to and removed from collections, etc. 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 | Prints information about the database system, including the database path and current database settings. |
db:list
Signatures | db:list() as xs:string* db:list($path as xs:string) as xs:string*
|
Summary | Returns an xs:string sequence with the names of all databases. If an argument is specified, all documents of the specified database or database path are returned.
|
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($db as item(), $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($db as item(), $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($db as item(), $string as item()) as text()*
|
Summary | Returns all text nodes that have $string as their string value.
|
Examples |
|
db:attribute
Signatures | db:attribute($db as item(), $string as item()) as attribute()* db:attribute($db as item(), $string as item(), $attname as xs:string) as attribute()*
|
Summary | Returns all attribute nodes that have $string as their string value.If $attname is specified, the resulting attribute nodes are filtered by their attribute name.
|
Examples |
|
db:fulltext
Signatures | db:fulltext($db as item(), $text as item()) 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 have been stemmed, the search string will be stemmed as well.
|
Errors | BASX0001 is raised if the index is not available. |
Examples |
|
db:info
Signatures | db:info($db as item()) as xs:string db:info($db as item(), $type as xs:string) as xs:string
|
Summary | Returns information for a database. 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. |
Examples |
|
db:add
Signatures | db:add($db as item(), $input as item()*) as empty-sequence() db:add($db as item(), $input as item()*, $name as xs:string) as empty-sequence() db:add($db as item(), $input as item()*, $name as xs:string, $path as xs:string) as empty-sequence()
|
Summary | Add documents specified by $input to the database $db , using an optional document name $name and an optional path $path .
|
Errors | BASX0002 is raised if $db is not a database node.BASX0003 is raised if $db is a string and a database with that name cannot be open.FODC0002 is raised if $input is a string representing a path, which cannot be read.FOUP0001 is raised if $input is not a string and not a document node.
|
Examples |
|
db:replace
Signatures | db:replace($db as item(), $path as xs:string, $input as item()) as empty-sequence()
|
Summary | Replace a document, specified by $path in the database $db with the content of $input .
|
Errors | BASX0002 is raised if $db is not a database node.BASX0003 is raised if $db is a string and a database with that name cannot be open.BASX0012 is raised if $path is not a single document path.FODC0002 is raised if $input is a string representing a path, which cannot be read.FOUP0001 is raised if $input is not a string and not a document node.
|
Examples |
|
db:delete
Signatures | db:delete($db as item(), $path as xs:string) as empty-sequence()
|
Summary | Delete document(s), specified by $path in the database $db .
|
Errors | BASX0002 is raised if $db is not a database node.BASX0003 is raised if $db is a string and a database with that name cannot be open.
|
Examples |
|
db:rename
Signatures | db:rename($db as item(), $path as xs:string, $newpath as xs:string) as empty-sequence()
|
Summary | Rename document(s), specified by $path to $newpath in the database $db .
|
Errors | BASX0002 is raised if $db is not a database node.BASX0003 is raised if $db is a string and a database with that name cannot be open.BASX0013 is raised if new document name(s) will be empty. |
Examples |
|
db:optimize
Signatures | db:optimize($db as xs:string) as empty-sequence() db:optimize($db as xs:string, $all as xs:boolean) as empty-sequence()
|
Summary | Optimize the data structures of the database $db . If $all is set to true() , then the whole database will be rebuilt.
|
Errors | BASX0002 is raised if $db is not a database node.BASX0003 is raised if $db is a string and a database with that name cannot be open.BASX0014 is raised if an error occurs during optimizing the data structures. BASX0015 is raised if the $all flag is set to true() , but the database is an in-memory database.BASX0016 is raised if the database $db is in use by other user(s).
|
Examples |
|