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.
A preview page contains all functions offered by the latest stable snapshot.
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("docs") returns all documents from the database named docs.db:open("docs/one") returns all documents from the database named docs in the subpath one.
|
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-pre("docs", 0) returns the first database node from the database named docs.
|
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-pre(doc("input")) returns 0 if the database input contains a single document.
|
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:text("DB", "QUERY")/.. returns the parents of all text nodes of the database DB that match the string QUERY.
|
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:attribute("DB", "QUERY", "id")/.. returns the parents of all id attribute nodes of the database DB that have QUERY as string value.
|
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:fulltext("DB", "QUERY") returns all text nodes of the database DB that contain the string QUERY.
|
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:info("DB", "FULLTEXT") returns information about the full-text index in the database DB.
|
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:add("DB", "/home/dir/doc.xml") adds the file /home/dir/doc.xml to the database DB.db:add("DB", "<a/>", "doc.xml") adds a document with content <a/> to the database DB under the name doc.xml.db:add("DB", document { <a/> }, "doc.xml") adds the document node to the database DB under the name doc.xml.db:add("DB", "/home/dir", "", "docs/dir") adds all documents in /home/dir to the database DB under the path docs/dir.
|
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:replace("DB", "docs/dir/doc.xml", "/home/dir/doc.xml") replaces the content of the document docs/dir/doc.xml in the database DB with the content of the file /home/dir/doc.xml.db:replace("DB", "docs/dir/doc.xml", "<a/>") replaces the content of the document docs/dir/doc.xml in the database DB with <a/>.db:replace("DB", "docs/dir/doc.xml", document { <a/> }) replaces the content of the document docs/dir/doc.xml in the database DB with the specified document node.
|
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:delete("DB", "docs/dir/doc.xml") deletes the document docs/dir/doc.xml in the database DB.db:delete("DB", "docs/dir", "<a/>") deletes all documents with paths beginning with docs/dir in the database DB.
|
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:rename("DB", "docs/dir/doc.xml", "docs/dir/newdoc.xml") renames the document docs/dir/doc.xml to docs/dir/newdoc.xml in the database DB.db:rename("DB", "docs/dir", "docs/newdir") renames all documents with paths beginning with docs/dir to paths beginning with docs/newdir in the database DB.
|
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
|
db:optimize("DB") optimizes the database structures of the database DB.db:optimize("DB", true()) optimizes all database structures of the database DB.
|
