Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
no edit summary
=Conventions=
All functions in this module are assigned to the <code>{{Code|http://basex.org/modules/db</code> }} namespace, which is statically bound to the <code>{{Code|db</code> }} prefix.<br/>All errors are assigned to the <code>{{Code|http://basex.org/errors</code> }} namespace, which is statically bound to the <code>{{Code|bxerr</code> }} prefix.
==Database Nodes==
Many function signatures in this and other modules share {{Code|$db}} as argument to reference an existing database. The argument may either be a string, denoting the name of the addressed database, or a single node from an already opened database. The following errors may be raised by these functions:
* '''[[{{Error|BXDB0001|#Errors|BXDB0001]]''' is raised if }} {{Code|$db}} references an XML node that is not stored in a database, or is no database fragment.* '''[[{{Error|BXDB0002|#Errors|BXDB0002]]''' is raised if }} the addressed database cannot be opened.
Last not but least, the argument may also reference a BaseX-specific ''database fragment''. All XML fragments can be converted to database fragments by applying the [[XQuery_Update#transform|transform]] expression on an XML fragment:
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:info'''(|$db as item()) as |element(Database)}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:list'''() as ||xs:string*}}<br/>{{CodeFunc|'''db:list'''(|$db as item()) as |xs:string*}}<br/>{{CodeFunc|'''db:list'''(|$db as item(), $path as xs:string) as |xs:string*}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:list-details'''() as ||element(database)*}}<br/>{{CodeFunc|'''db:list-details'''(|$db as item()) as |element(resource)*}}<br/>{{CodeFunc|'''db:list-details'''(|$db as item(), $path as xs:string) as |element(resource)*}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:open'''(|$db as item()) as |document-node()*}}<br />{{CodeFunc|'''db:open'''(|$db as item(), $path as xs:string) as |document-node()*}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:open-id'''(|$db as item(), $id as xs:integer) as |node()}}
|-
| '''Summary'''
|-
| '''Errors'''
|'''[[{{Error|BXDB0009|XQuery Errors#BaseX Errors|BXDB0009]]''' is raised if }} the specified id value does not exist in the database.
|}
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:open-pre'''(|$db as item(), $pre as xs:integer) as |node()}}
|-
| '''Summary'''
|-
| '''Errors'''
|'''[[{{Error|BXDB0009|XQuery Errors#BaseX Errors|BXDB0009]]''' is raised if }} the specified pre value does not exist in the database.
|-
| '''Examples'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:system'''() as ||element(system)}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:attribute'''(|$db as item(), $string as item()) as |attribute()*}}<br/>{{CodeFunc|'''db:attribute'''(|$db as item(), $string as item(), $attname as xs:string) as |attribute()*}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:attribute-range'''(|$db as item(), $min as xs:string, $max as xs:string) as |text()*}}<br/>{{CodeFunc|'''db:attribute-range'''(|$db as item(), $min as xs:string, $max as xs:string, $attname as xs:string) as |attribute()*}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:fulltext'''(|$db as item(), $terms as xs:string) as |text()*}}
|-
| '''Summary'''
|-
| '''Errors'''
|'''[[{{Error|BXDB0004|#Errors|BXDB0004]]''' is raised if }} the full-text index is not available.
|-
| '''Examples'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:node-id'''(|$nodes as node()*) as |xs:integer*}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:node-pre'''(|$nodes as node()*) as |xs:integer*}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:retrieve'''(|$db as item(), $path as xs:string) as |xs:base64Binary}}
|-
| '''Summary'''
|-
| '''Errors'''
|'''[[{{Error|BXDB0003|#Errors|BXDB0003]]''' is raised if }} the databse is not ''persistent'' (stored on disk).<br/>'''[[{{Error|FODC0002|XQuery Errors#Functions Errors|FODC0002]]''' is raised if }} the addressed resource cannot be retrieved.<br/>'''[[{{Error|FODC0007|XQuery Errors#Functions Errors|FODC0007]]''' is raised if }} the specified path is invalid.
|-
| '''Examples'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:text'''(|$db as item(), $string as item()) as |text()*}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:text-range'''(|$db as item(), $min as xs:string, $max as xs:string) as |text()*}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:add'''(|$db as item(), $input as item()) as |empty-sequence()}}<br/>{{CodeFunc|'''db:add'''(|$db as item(), $input as item(), $path as xs:string) as |empty-sequence()}}
|-
| '''Summary'''
|-
| '''Errors'''
|'''[[{{Error|FODC0002|XQuery Errors#Functions Errors|FODC0002]]''' is raised if }} {{Code|$input}} is a string representing a path, which cannot be read.<br/>'''[[{{Error|FOUP0001|XQuery Errors#Update Errors|FOUP0001]]''' is raised if }} {{Code|$input}} is neither string nor a document node.
|-
| '''Examples'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:delete'''(|$db as item(), $path as xs:string) as |empty-sequence()}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:optimize'''(|$db as item()) as |empty-sequence()}}<br/>{{CodeFunc|'''db:optimize'''(|$db as item(), $all as xs:boolean) as |empty-sequence()}}
|-
| '''Summary'''
|-
| '''Errors'''
|'''[[{{Error|BASX0014|XQuery Errors#BaseX Errors|BASX0014]]''' is raised if }} an error occurs during optimizing the data structures.<br/>'''[[{{Error|BASX0015|XQuery Errors#BaseX Errors|BASX0015]]''' is raised if }} the {{Code|$all}} flag is set to {{Code|true()}}, but the database is an in-memory database.<br/>'''[[{{Error|BASX0016|XQuery Errors#BaseX Errors|BASX0016]]''' is raised if }} the database {{Code|$db}} is in use by other user(s).
|-
| '''Examples'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:rename'''(|$db as item(), $path as xs:string, $newpath as xs:string) as |empty-sequence()}}
|-
| '''Summary'''
|-
| '''Errors'''
|'''[[{{Error|BXDB0008|#Errors|BXDB0008]]''' is raised if }} new document names would be empty.
|-
| '''Examples'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:replace'''(|$db as item(), $path as xs:string, $input as item()) as |empty-sequence()}}
|-
| '''Summary'''
|-
| '''Errors'''
|'''[[{{Error|BXDB0006|#Errors|BXDB0006]]''' is raised if }} {{Code|$path}} is not a single document path.<br/>'''[[{{Error|FODC0002|XQuery Errors#Functions Errors|FODC0002]]''' is raised if }} {{Code|$input}} is a string representing a path, which cannot be read.<br/>'''[[{{Error|FOUP0001|XQuery Errors#Update Errors|FOUP0001]]''' is raised if }} {{Code|$input}} is neither a string nor a document node.
|-
| '''Examples'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:store'''(|$db as item(), $path as xs:string, $data as item()) as |empty-sequence()}}
|-
| '''Summary'''
|-
| '''Errors'''
|'''[[{{Error|BXDB0003|#Errors|BXDB0003]]''' is raised if }} the databse is not ''persistent'' (stored on disk).<br/>'''[[{{Error|FODC0007|XQuery Errors#Functions Errors|FODC0007]]''' is raised if }} the specified path is invalid.<br/>'''[[{{Error|FOUP0002|XQuery Errors#Update Errors|FOUP0002]]''' is raised if }} the resource cannot be stored at the specified location.
|-
| '''Examples'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:output'''(|$data as item()*) as |empty-sequence()}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:exists'''(|$db as item()) as |xs:boolean}}<br/>{{CodeFunc|'''db:exists'''(|$db as item(), $path as xs:string) as |xs:boolean}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:is-raw'''(|$db as item(), $path as xs:string) as |xs:boolean}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:is-xml'''(|$db as item(), $path as xs:string) as |xs:boolean}}
|-
| '''Summary'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:content-type'''(|$db as item(), $path as xs:string) as |xs:string}}
|-
| '''Summary'''
|-
| '''Errors'''
|'''[[{{Error|FODC0002|XQuery Errors#Functions Errors|FODC0002]]''' is raised if }} the addressed resource is not found or cannot be retrieved.
|-
| '''Examples'''
|-
| width='90' | '''Signatures'''
|{{CodeFunc|'''db:event'''(|$name as xs:string, $query as item()) as |empty-sequence()}}
|-
| '''Summary'''
|-
| '''Errors'''
|'''[[{{Error|BXDB0010|XQuery Errors#BaseX Errors|BXDB0010]]''' is raised if }} the specified event is unknown.<br/>'''[[{{Error|SEPM0016|XQuery_Errors#Serialization_Errors|SEPM0016]]''' is raised if }} serialization errors occurred while sending the value.<br/>
|}
! width="95%"|Description
|-
|<code>{{Code|BXDB0001</code>}}
|A referenced XML node is no [[#Database Nodes|database node]], i.e. is neither stored in a database nor a database fragment.
|-
|<code>{{Code|BXDB0002</code>}}
|An I/O error occurred while opening a database.
|-
|<code>{{Code|BXDB0003</code>}}
|The addressed database is not ''persistent'' (stored on disk).
|-
|<code>{{Code|BXDB0004</code>}}
|The database lacks an index structure required by the called function.
|-
|<code>{{Code|BXDB0005</code>}}
|A query is expected to exclusively return [[#Database Nodes|database nodes]] of a single database.
|-
|<code>{{Code|BXDB0006</code>}}
|A database path addressed with {{Code|doc()}} contains more than one document.
|-
|<code>{{Code|BXDB0007</code>}}
|A database cannot be updated because it is opened by another process.
|-
|<code>{{Code|BXDB0008</code>}}
|Database paths cannot be renamed to empty strings.
|-
|<code>{{Code|BXDB0009</code>}}
|The addressed database id or pre value is out of range.
|-
|<code>{{Code|BXDB0010</code>}}
|The specified event is unknown.
|}
