Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
no edit summary
This module contains [[Querying#Functions|XQuery functions]] to list for handling databases from within XQuery. Existing databases can be opened and open databaseslisted, explicitly apply available index structurescan be directly accessed, documents can be added to and removed from collections, or get information on the database structureetc. All functions are introduced with the <code>db:</code> prefix, which is linked to the <code><nowiki>http://www.basex.org/db</nowiki></code> namespace. Please checkout the [[Database Functions (Snapshot)|preview page]] to find all functions offered by the [http://files.basex.org/releases/latest/ latest stable snapshot].
==db:system==
|-
| valign='top' width='90' | '''Signatures'''
|<code><b>db:open-pre</b>($name db as xs:stringitem(), $pre as xs:integer) as node()</code>
|-
| valign='top' | '''Summary'''
|-
| valign='top' width='90' | '''Signatures'''
|<code><b>db:open-id</b>($name db as xs:stringitem(), $id as xs:integer) as node()</code>
|-
| valign='top' | '''Summary'''
|-
| valign='top' width='90' | '''Signatures'''
|<code><b>db:text</b>($name db as xs:stringitem(), $string as item()) as text()*</code>
|-
| valign='top' | '''Summary'''
|-
| valign='top' width='90' | '''Signatures'''
|<code><b>db:attribute</b>($name db as xs:stringitem(), $string as item()) as attribute()*</code><br/><code><b>db:attribute</b>($name db as xs:stringitem(), $string as item(), $attname as xs:string) as attribute()*</code>
|-
| valign='top' | '''Summary'''
|-
| valign='top' width='90' | '''Signatures'''
|<code><b>db:fulltext</b>($name db as xs:stringitem(), $text as xs:stringitem()) as text()*</code>
|-
| valign='top' | '''Summary'''
|-
| valign='top' width='90' | '''Signatures'''
|<code><b>db:info</b>($name db as xs:stringitem()) as xs:string</code><br/><code><b>db:info</b>($name db as xs:stringitem(), $type as xs:string) as xs:string</code>
|-
| valign='top' | '''Summary'''
| valign='top' | '''Errors'''
|<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]]
