Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
A [[Database Module (Snapshot)|This preview page]] contains all functions commands offered by the [http://files.basex.org/releases/latest/ latest stable snapshot].There is also [[Database Module|another page]], which lists the functions of the current release. =Commonalities= Many functions share {{Mono|$db}} as argument, which may either reference a string, denoting the name of the addressed database, or a node from an already opened database. The following errors may be raised by these functions: * '''[[XQuery Errors#BaseX Errors|BASX0002]]''' is raised if {{Mono|$db}} references a node that is not stored in a database (i.e., references a main-memory XML fragment).* '''[[XQuery Errors#BaseX Errors|BASX0003]]''' is raised if the addressed database cannot be opened.
{{Mark|Introduced with Version 7.0:}}
{{Mark|Signatures modified in Version 7.0:}}
{{Mark|Introduced with Version 7.0:}}
no edit summary
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 {{Mono|db:}} prefix, which is linked to the statically declared {{Mono|http://basex.org/modules/db}} namespace.
=General Functions=
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:info</b>'''($db as item()) as xs:string}}<br/>{{Mono|<b>db:info</b>($db as itemelement(Database), $type as xs:string) as xs:string}}
|-
| valign='top' | '''Summary'''
|Returns meta information on a database. {{Mono|$db}} may either be a string or a node stored in a database.<br/>If {{Mono|$type}} is the specified, the function returns information on a database index. It must be one of the values {{Mono|TEXT}}, {{Mono|ATTRIBUTE}}, {{Mono|FULLTEXT}}, {{Mono|PATH}}, {{Mono|TAG}}, or {{Mono|ATTNAME}}.|-| valign='top' | '''Errors'''|<b>[[XQuery Errors#BaseX Errors|BASX0001]]</b> is raised if the index {{Mono|$type}} is not available.<br/><b>[[XQuery Errors#BaseX Errors|BASX0002]]</b> is raised if {{Mono|$db}} is a node that is not stored in a database.<br/><b>[[XQuery Errors#BaseX Errors|BASX0003]]</b> is raised if the addressed database {{Mono|$db}} cannot be opened.<br/>|-| valign='top' | '''Examples'''|* {{Mono|db:info("DB", "FULLTEXT")}} returns information about the full-text index in the database {{Mono|DB}}.
|}
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:list</b>'''() as xs:string*}}<br/>{{Mono|<b>'''db:list</b>'''($db as xs:stringitem()) as xs:string*}}<br/>{{Mono|<b>'''db:list</b>'''($db as xs:stringitem(), $path as xs:string) as xs:string*}}
|-
| valign='top' | '''Summary'''
|Returns an {{Mono|xs:string}} sequence with the names of all databases. <br/>If {{Mono|$db}} is specified, all documents and raw files of the specified database are returned. <br/>The list of resources can be further restricted by the {{Mono|$path}} argument.<br/>{{Mark|Modified in Version 7.0}}: database and resource path are now specified as two separate arguments.|-| valign='top' | '''Errors'''|<b>[[XQuery Errors#BaseX Errors|BASX0002]]</b> is raised if {{Mono|$db}} is a node that is not stored in a database.<br/><b>[[XQuery Errors#BaseX Errors|BASX0003]]</b> is raised if the addressed database {{Mono|$db}} cannot be opened.<br/>
|}
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:open</b>'''($db as xs:stringitem()) as document-node()*}}<br />{{Mono|<b>'''db:open</b>'''($db as xs:stringitem(), $path as xs:string) as document-node()*}}
|-
| valign='top' | '''Summary'''
|Returns a sequence with all document nodes contained in the database specified by {{Mono|$db}}. <br/>The document nodes to be returned documents may can be filtered restricted by the {{Mono|$path}} argument.<br/>{{Mark|Modified in Version 7.0}}: database and resource path are now specified as two separate arguments.|-| valign='top' | '''Errors'''|<b>[[XQuery Errors#BaseX Errors|BASX0003]]</b> is raised if the database addressed by {{Mono|$db}} cannot be opened.<br/>
|-
| valign='top' | '''Examples'''
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:open-id</b>'''($db as item(), $id as xs:integer) as node()}}
|-
| valign='top' | '''Summary'''
|Opens the database specified by {{Mono|$db}} and returns the node with the specified {{Mono|$id}} value.<br />In contrast to the <i>pre</i> valueEach database node has a persistent ''id'', the <i>id</i> will remain which remains valid after update operations.|-| valign=If no updates are performed, the 'top' | pre'''Errors'''|<b>[[XQuery Errors#BaseX Errors|BASX0004]]</b> is raised if the specified {{Mono|$id}} does not exist value can be requested, which provides access to database nodes in the databaseconstant time.
|}
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:open-pre</b>'''($db as item(), $pre as xs:integer) as node()}}
|-
| valign='top' | '''Summary'''
|Opens the database specified by {{Mono|$db}} and returns the node with the specified {{Mono|$pre}} value.<br />The ''pre'' value provides access to a database node in constant time, but it is ''transient'', i.e., it may change when database updates are performed.
|-
| valign='top' | '''Errors'''
|<b>'''[[XQuery Errors#BaseX Errors|BASX0004]]</b> ''' is raised if the specified {{Mono|$pre}} value does not exist in the database.
|-
| valign='top' | '''Examples'''
|
* {{Mono|db:open-pre("docs", 0)}} returns the first XML database node stored in from the database named {{Mono|docs}} database.
|}
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:system</b>'''() as xs:stringelement(System)}}
|-
| valign='top' | '''Summary'''
|Prints Returns information about on the database system, including such as the database path and current database settings.
|}
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:attribute</b>'''($db as item(), $string as item()) as attribute()*}}<br/>{{Mono|<b>'''db:attribute</b>'''($db as item(), $string as item(), $attname as xs:string) as attribute()*}}
|-
| valign='top' | '''Summary'''
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:fulltext</b>'''($db as item(), $text as item()) as text()*}}
|-
| valign='top' | '''Summary'''
|Returns all text nodes from the full-text index that contain the string {{Mono|$text}}. <br/>The index full-text options are used for searching, i.e., will be applied here: if the index terms have been stemmed, the search string will be stemmed as well.
|-
| valign='top' | '''Errors'''
|<b>'''[[XQuery Errors#BaseX Errors|BASX0001]]</b> ''' is raised if the index is not available.
|-
| valign='top' | '''Examples'''
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:node-id</b>'''($nodes as node()*) as xs:integer*}}
|-
| valign='top' | '''Summary'''
|Returns the <i>''id</i> '' values of all database nodes specified by {{Mono|$nodes}}. <ibr/>Each database node has a persistent ''id</i> values '', which remains valid after update operations. If no updates are pointers performed, the ''pre'' value can be requested, which provides access to database nodes, which are not changed by updatesin constant time.
|}
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:node-pre</b>'''($nodes as node()*) as xs:integer*}}
|-
| valign='top' | '''Summary'''
|Returns the <i>''pre</i> '' values of all database nodes specified by {{Mono|$nodes}}. <ibr/>The ''pre</'' value provides access to a database node in constant time, but it is ''transient'', i> values are direct.e., internal pointers to it may change when database nodes, which might be changed by updatesare performed.
|-
| valign='top' | '''Examples'''
==db:retrieve==
{|
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:retrieve</b>'''($db as xs:stringitem(), $path as xs:string) as basexxs:rawbase64Binary}}
|-
| valign='top' | '''Summary'''
|Retrieves the Returns a binary database resource specified addressed by {{Mono|$pathdb}} in the (implementation specific) and {{Mono|basex:raw$path}} format.
|-
| valign='top' | '''Errors'''
|<b>'''[[XQuery Errors#Functions Errors|FODC0002]]</b> ''' is raised if the addressed resource is not found or cannot be retrieved.
|-
| valign='top' | '''Examples'''
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:text</b>'''($db as item(), $string as item()) as text()*}}
|-
| valign='top' | '''Summary'''
==db:add==
{|
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:add</b>'''($db as item(), $input as item()) as empty-sequence()}}<br/>{{Mono|<b>'''db:add</b>'''($db as item(), $input as item(), $path as xs:string) as empty-sequence()}}
|-
| valign='top' | '''Summary'''
|Add Adds documents specified by {{Mono|$input}} to the database {{Mono|$db}} and the specified {{Mono|$path}}.
|-
| valign='top' | '''Errors'''
|<b>[[XQuery Errors#BaseX Errors|BASX0002]]</b> is raised if {{Mono|$db}} is a node that is not stored in a database.<br/><b>[[XQuery Errors#BaseX Errors|BASX0003]]</b> is raised if the database addressed by {{Mono|$db}} cannot be opened.<br/><b>'''[[XQuery Errors#Functions Errors|FODC0002]]</b> ''' is raised if {{Mono|$input}} is a string representing a path, which cannot be read.<br/><b>'''[[XQuery Errors#Update Errors|FOUP0001]]</b> ''' is raised if {{Mono|$input}} is not a string and not a document node.
|-
| valign='top' | '''Examples'''
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:delete</b>'''($db as item(), $path as xs:string) as empty-sequence()}}
|-
| valign='top' | '''Summary'''
|Delete Deletes document(s), specified by {{Mono|$path}} in , from the database {{Mono|$db}}.|-| valign='top' | '''Errors'''|<b>[[XQuery Errors#BaseX Errors|BASX0002]]</b> is raised if {{Mono|$db}} is a node that is not stored in a database.<br/><b>[[XQuery Errors#BaseX Errors|BASX0003]]</b> is raised if the database addressed by {{Mono|$db}} cannot be opened.<br/>
|-
| valign='top' | '''Examples'''
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:optimize</b>'''($db as xs:stringitem()) as empty-sequence()}}<br/>{{Mono|<b>'''db:optimize</b>'''($db as xs:stringitem(), $all as xs:boolean) as empty-sequence()}}
|-
| valign='top' | '''Summary'''
|Optimize Optimizes the meta data structures and indexes of the database {{Mono|$db}}. <br/>If {{Mono|$all}} is set to {{Mono|true()}}, then the whole complete database will be rebuilt.
|-
| valign='top' | '''Errors'''
|<b>[[XQuery Errors#BaseX Errors|BASX0002]]</b> is raised if {{Mono|$db}} is a node that is not stored in a database.<br/><b>[[XQuery Errors#BaseX Errors|BASX0003]]</b> is raised if the database addressed by {{Mono|$db}} cannot be opened.<br/><b>'''[[XQuery Errors#BaseX Errors|BASX0014]]</b> ''' is raised if an error occurs during optimizing the data structures.<br/><b>'''[[XQuery Errors#BaseX Errors|BASX0015]]</b> ''' is raised if the {{Mono|$all}} flag is set to {{Mono|true()}}, but the database is an in-memory database.<br/><b>'''[[XQuery Errors#BaseX Errors|BASX0016]]</b> ''' is raised if the database {{Mono|$db}} is in use by other user(s).
|-
| valign='top' | '''Examples'''
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:rename</b>'''($db as item(), $path as xs:string, $newpath as xs:string) as empty-sequence()}}
|-
| valign='top' | '''Summary'''
|Rename Renames document(s), specified by {{Mono|$path}} to {{Mono|$newpath}} in the database {{Mono|$db}}.
|-
| valign='top' | '''Errors'''
|<b>[[XQuery Errors#BaseX Errors|BASX0002]]</b> is raised if {{Mono|$db}} is a node that is not stored in a database.<br/><b>[[XQuery Errors#BaseX Errors|BASX0003]]</b> is raised if the database addressed by {{Mono|$db}} cannot be opened.<br/><b>'''[[XQuery Errors#BaseX Errors|BASX0013]]</b> ''' is raised if new document name(s) will be empty.
|-
| valign='top' | '''Examples'''
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:replace</b>'''($db as item(), $path as xs:string, $input as item()) as empty-sequence()}}
|-
| valign='top' | '''Summary'''
|Replace Replaces a document, specified by {{Mono|$path}} , in the database {{Mono|$db}} with the content of {{Mono|$input}}.
|-
| valign='top' | '''Errors'''
|<b>[[XQuery Errors#BaseX Errors|BASX0002]]</b> is raised if {{Mono|$db}} is a node that is not stored in a database.<br/><b>[[XQuery Errors#BaseX Errors|BASX0003]]</b> is raised if the database addressed by {{Mono|$db}} cannot be opened.<br/><b>'''[[XQuery Errors#BaseX Errors|BASX0012]]</b> ''' is raised if {{Mono|$path}} is not a single document path.<br/><b>'''[[XQuery Errors#Functions Errors|FODC0002]]</b> ''' is raised if {{Mono|$input}} is a string representing a path, which cannot be read.<br/><b>'''[[XQuery Errors#Update Errors|FOUP0001]]</b> ''' is raised if {{Mono|$input}} is not a string and not a document node.
|-
| valign='top' | '''Examples'''
==db:store==
{|
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:store</b>'''($db as xs:stringitem(), $path as xs:string, $data as item()) as empty-sequence()}}
|-
| valign='top' | '''Summary'''
|-
| valign='top' | '''Errors'''
|<b>'''[[XQuery Errors#Update Errors|FOUP0002]]</b> ''' is raised if the resource cannot be stored at the specified location.
|-
| valign='top' | '''Examples'''
=Helper Functions=
==db:content-typeexists== {{Mark|Introduced with Version 7.0:}}
{|
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:exists'''($dbas item()) as xs:content-typeboolean}}<br/b>{{Mono|'''db:exists'''($db as xs:stringitem(), $path as xs:string) as xs:stringboolean}}
|-
| valign='top' | '''Summary'''
|Retrieves Checks if the content type of the resource specified by {{Mono|$path}}. Currently, the implementation uses the file extension to recognize the content-type of a database or resource stored in the database (this mechanism is provided by Java)exists. Content-type {{Mono|application/xmlfalse}} will be is returned for any XML document stored in the if a database, regardless of its file name extension.|-| valign='top' | '''Errors'''|<b>[[XQuery Errors#Functions Errors|FODC0002]]</b> directory is raised if the addressed resource is not found or cannot be retrievedspecified.
|-
| valign='top' | '''Examples'''
|
* {{Mono|db:content-typeexists("DB", "docs/doc01.pdf")}} returns {{Mono|application/pdftrue}}.* if the database {{Mono|db:content-type("DB", "docs/doc01.xml")}} returns {{Mono|application/xml}}exists.* {{Mono|db:content-typeexists("DB", "docs/doc01resource")}} returns {{Mono|application/xmltrue}}, if {{Mono|db:is-xml("DB", "docs/doc01")}} returns {{Mono|trueresource}}is an XML document or a raw file.
|}
==db:eventis-raw==
{|
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:event</b>is-raw'''($db as item(), $name path as xs:string, $query as item()) as empty-sequence()xs:boolean}}
|-
| valign='top' | '''Summary'''
|Executes a {{Mono|$query}} and sends the resulting value to all clients watching the [[Events|Event]] with Checks if the specified {{Mono|$name}}. No event will be sent to the client that fired the eventresource exists and if it is a raw file.
|-
| valign='top' | '''ErrorsExamples'''|<b>[[XQuery Errors#BaseX Errors* {{Mono|BASX0009]]<db:is-raw("DB", "music/b> is raised if the specified event is unknown01.<br/><b>[[XQuery_Errors#Serialization_Errorsmp3")}} returns {{Mono|SEPM0016]]</b> is raised if serialization errors occurred while sending the valuetrue}}.<br/>
|}
==db:existsis-xml== {{Mark|Introduced with Version 7.0:}}
{|
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:exists</b>is-xml'''($db as xs:stringitem() as xs:boolean}}<br/>{{Mono|<b>db:exists</b>($db as xs:string, $path as xs:string) as xs:boolean}}
|-
| valign='top' | '''Summary'''
|Checks if the specified database or resource exists. Returns {{Mono|false}} and if a database directory it is specifiedan XML document.
|-
| valign='top' | '''Examples'''
|
* {{Mono|db:exists("DB")}} returns {{Mono|true}} if the database {{Mono|DB}} exists.* {{Mono|db:existsis-xml("DB", "resourcedir/doc.xml")}} returns {{Mono|true}} if {{Mono|resource}} is an XML document or a raw file.
|}
==db:iscontent-rawtype== {{Mark|Introduced with Version 7.0:}}
{|
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:iscontent-raw</b>type'''($db as xs:stringitem(), $path as xs:string) as xs:booleanstring}}
|-
| valign='top' | '''Summary'''
|Checks if Retrieves the content type of the resource specified by {{Mono|$path}}.<br/>The file extension is used to recognize the content-type of a resource exists and stored in the database. Content-type {{Mono|application/xml}} will be returned for any XML document stored in the database, regardless of its file name extension.|-| valign='top' | '''Errors'''|'''[[XQuery Errors#Functions Errors|FODC0002]]''' is raised if it the addressed resource is a raw filenot found or cannot be retrieved.
|-
| valign='top' | '''Examples'''
|
* {{Mono|db:content-type("DB", "docs/doc01.pdf")}} returns {{Mono|application/pdf}}.* {{Mono|db:content-type("DB", "docs/doc01.xml")}} returns {{Mono|application/xml}}.* {{Mono|db:content-type("DB", "docs/doc01")}} returns {{Mono|application/xml}}, if {{Mono|db:is-rawxml("DB", "musicdocs/01.mp3doc01")}} returns {{Mono|true}}.
|}
==db:is-xmlevent== {{Mark|Introduced with Version 7.0:}}
{|
|-
| valign='top' width='90' | '''Signatures'''
|{{Mono|<b>'''db:is-xml</b>event'''($db name as xs:string, $path query as xs:stringitem()) as xs:booleanempty-sequence()}}
|-
| valign='top' | '''Summary'''
|Checks if Executes a {{Mono|$query}} and sends the resulting value to all clients watching the [[Events|Event]] with the specified resource exists and if it is an XML document{{Mono|$name}}. The query may also perform updates; no event will be sent to the client that fired the event.
|-
| valign='top' | '''ExamplesErrors'''|* {{Mono'''[[XQuery Errors#BaseX Errors|db:BASX0009]]''' is raised if the specified event is-xml("DB", "dirunknown.<br/doc.xml")}} returns {{Mono>'''[[XQuery_Errors#Serialization_Errors|true}}SEPM0016]]''' is raised if serialization errors occurred while sending the value.<br/>
|}
=Recent Changes=
==Version 7.1==
* Added: {{Mono|db:list-details()}}, {{Mono|db:content-type()}}
* Modified: {{Mono|db:info()}}, {{Mono|db:system()}}, {{Mono|db:retrieve()}}
==Version 7.0==
* Added: {{Mono|db:retrieve()}}, {{Mono|db:store()}}, {{Mono|db:exists()}}, {{Mono|db:is-raw()}}, {{Mono|db:is-xml()}}
* Modified: {{Mono|db:list()}}, {{Mono|db:open()}}, {{Mono|db:add()}}
[[Category:XQuery]]
