Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
{{Mark|Updated with Version 9.0}}:
copy $c db:= node-id(element hello { 'world' } modify (update {}) return $c
|}
==db:output==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:output|$result as item()*|empty-sequence()}}
|-
| '''Summary'''
|This function can be used to both perform updates and return results in a single query. The argument of the function will be evaluated, and the resulting items will be cached and returned after the updates on the ''pending update list'' have been processed. As nodes may be updated, they will be copied before being cached.<br/>The function can only be used together with [[XQuery Update#Updating Expressions|updating expressions]]; if the function is called within a transform expression, its results will be discarded.
|-
| '''Examples'''
|
* {{Code|db:output("Prices have been deleted."), delete node //price}} deletes all {{Code|price}} elements in a database and returns an info message.
|}
==db:output-cache==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:output-cache||item()*}}
|-
| '''Summary'''
|Returns the items that have been cached by [[#db:output|db:output]]. It can be used to check which items will eventually be returned as result of an updating function.<br/>This function is ''non-deterministic'': It will return different results before and after items have been cached. It is e. g. useful when writing [[Unit Module|unit tests]].
{{Mark|Updated with Version 9.0}}:
no edit summary
=Conventions=
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/db</nowiki></code> namespace, which is statically bound to the {{Code|db}} prefix.<br/>
==Database Nodes==
Database nodes are XML nodes which are either stored in a persistent database, or which contained in are a sonode of a main-called ''memory database fragment''representation. All XML fragments can be converted to a main-memory database fragments by e. g. applying the [[XQuery_Update#update|update]] or [[XQuery_Update#transform|transform]] expression on an XML fragmenta node:
<pre class="brush:xquery">
</pre>
|-
| '''Summary'''
|Returns general information on the database system, such as the database path current values of all global and current database settingslocal [[Options]]. The {{Command|INFO}} command returns similar output is similar to .|} ==db:option== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|db:option|$name as xs:string|xs:string}}|-| '''Summary'''|Returns the current value (string, integer, boolean, map) of a global or local [[Commands#INFOOptions|INFOOption]] with the specified {{Code|$name}}. The {{Command|GET}} commandworks similar.|-| '''Errors'''|{{Error|option|#Errors}} the specified option is unknown.|-| '''Examples'''|* <code>db:option('dbpath')</code> returns the database path string.* <code>db:option('serializer')</code> returns a map with the current serialization parameters.* <code>declare option db:chop 'true'; db:option('chop')</code> returns {{Code|true}} (irrespective of the global value).
|}
|-
| '''Summary'''
|Returns meta information on the database {{Code|$db}}. The output is similar to the [[Commands#INFO DB{{Command|INFO DB]] }} command.
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|}
|-
| width='120' | '''Signatures'''
|{{Func|db:property|$db as xs:string, $property name as xs:string|xs:anyAtomicType}}
|-
| '''Summary'''
|Returns the value (string, boolean, integer) of a property with the specified {{Code|$propertyname}} of in the database {{Code|$db}}. The available properties are the ones returned by [[#db:info|db:info]].
|-
| '''Errors'''
|{{Error|property|XQuery Errors#BaseX Errors}} the specified property is unknown.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|-
| '''Examples'''
|
* {{Code|db:list-details("shop")}} returns the names plus additional info on all resources of a database named {{Code|shop}}.
|}
==db:dir==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:dir|$db as xs:string, $path as xs:string|element()*}}
|-
| '''Summary'''
|Returns meta data on all directories and resources of the database {{Code|$db}} in the specified directory {{Code|$path}}. Two types of elements are returned:
* {{Code|resource}} represents a resource. The element value is the directory path; content type, modification date, raw flag (which indicates if the resource is binary or XML), and size of the resource are returned as attributes.
* {{Code|dir}} represents a directory. The element value is the directory path; the modification date is returned as attribute.
Please note that directories are not stored in BaseX. Instead, they result implicitly from the paths of stored resources.
|-
| '''Errors'''
|{{Error|open|#Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|path|#Errors}} the specified path is invalid.
|-
| '''Examples'''
|
* {{Code|db:dir('shop', 'books')}} returns all entries of the {{Code|books}} directory of a {{Code|shop}} database.
|}
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|-
| '''Examples'''
==db:open-pre==
{{Mark|Updated with Version 9.3}}: Support for multiple integers.
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:open-pre|$db as xs:string, $pre pres as xs:integer*|node()*}}
|-
| '''Summary'''
|Opens the database {{Code|$db}} and returns the node all distinct nodes with the specified pre values {{Code|$prepres}} valuein document order.<br/>The [[Node Storage#PRE Value|PRE value]] provides very fast access to an existing database node, but it will change whenever a node with a smaller ''pre'' values is added to or deleted from a database.
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|range|XQuery Errors#BaseX Errors}} the specified pre value does not exist in the database.
|-
| '''Examples'''
==db:open-id==
{{Mark|Updated with Version 9.3}}: Support for multiple integers.
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:open-id|$db as xs:string, $id ids as xs:integer*|node()*}}
|-
| '''Summary'''
|Opens the database {{Code|$db}} and returns the node all distinct nodes with the specified {{Code|$idids}} valuein document order.<br />Each database node has a ''persistent'' [[Node Storage#ID Value|ID value]]. Access to the node id can be sped up by turning on the {{Option|UPDINDEX}} option.
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|range|XQuery Errors#BaseX Errors}} the specified id value does not exist in the database.
|}
|-
| '''Summary'''
|Returns the ''pre'' values of the nodes supplied by specified {{Code|$nodes}}, which must all be [[#Database Nodes|database nodes]].<br/>The [[Node Storage#PRE Value|PRE value]] provides very fast access to an existing database node, but it will change whenever a node with a smaller ''pre'' values is added to or deleted from a database.
|-
| '''Errors'''
|-
| '''Summary'''
|Returns the ''id'' values of the nodes supplied by specified {{Code|$nodes}}, which must all be [[#Database Nodes|database nodes]].<br/>Each database node has a ''persistent'' [[Node Storage#ID Value|ID value]]. Access to the node id can be sped up by turning on the {{Option|UPDINDEX}} option.
|-
| '''Errors'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|mainmem|#Errors}} the database is not ''persistent'' (stored on disk).<br/>{{Error|FODC0002|XQuery Errors#Functions Errors}} the addressed resource cannot be retrieved.<br/>{{Error|FODC0007|XQuery Errors#Functions Errors}} the specified path is invalid.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|-
| '''Examples'''
|-
| width='120' | '''Signatures'''
|{{Func|db:text|$db as xs:string, $strings as xs:string as item()*|text()*}}
|-
| '''Summary'''
|Returns all text nodes of the database {{Code|$db}} that have one of the specified {{Code|$stringstrings}} as their string value values and that are stored in the text index.
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|no-index|Database Module#Errors}} the index is not available.<br/>
|-
| '''Examples'''
|-
| '''Summary'''
|Returns all text nodes of the database {{Code|$db}} that whose values are located in between the {{Code|$min}} and {{Code|$max}} strings and that are stored in the text index.
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|no-index|Database Module#Errors}} the index is not available.<br/>
|-
| '''Examples'''
|-
| width='120' | '''Signatures'''
|{{Func|db:attribute|$db as xs:string, $strings as xs:string as item()*|attribute()*}}<br/>{{Func|db:attribute|$db as xs:string, $strings as xs:string as item()*, $name as xs:string|attribute()*}}
|-
| '''Summary'''
|Returns all attribute nodes of the database {{Code|$db}} that have one of the specified {{Code|$stringstrings}} as string value values and that are stored in the attribute index.<br />If {{Code|$name}} is specified, the resulting attribute nodes are filtered by their attribute name.
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|no-index|Database Module#Errors}} the index is not available.<br/>
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|no-index|Database Module#Errors}} the index is not available.<br/>
|-
| '''Examples'''
|-
| width='120' | '''Signatures'''
|{{Func|db:token|$db as xs:string, $token tokens as item()xs:string*|attribute()*}}<br/>{{Func|db:token|$db as xs:string, $token tokens as item()xs:string*, $name as xs:string|attribute()*}}
|-
| '''Summary'''
|Returns all attribute nodes of the database {{Code|$db}}, the value values of which contains contain one of the specified {{Code|$tokentokens}}.<br />If {{Code|$name}} is specified, the resulting attribute nodes are filtered by their attribute name.
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|no-index|Database Module#Errors}} the index is not available.<br/>
|-
| '''Examples'''
|-
| width='120' | '''Signatures'''
|{{Func|db:create|$db as xs:string|empty-sequence()}}<br/>{{Func|db:create|$db as xs:string, $inputs as item()*|empty-sequence()}}<br/>{{Func|db:create|$db as xs:string, $inputs as item()*, $paths as xs:string*|empty-sequence()}}<br/>{{Func|db:create|$db as xs:string, $inputs as item()*, $paths as xs:string*, $options as map(*)?|empty-sequence()}}
|-
| '''Summary'''
|-
| '''Errors'''
|{{Error|FODC0002|XQuery Errors#Functions Errors}} an input points to an unknown resource.<br/>{{Error|FOUP0001|XQuery Errors#Update Errors}} an attribute was specified as input.<br/>{{Error|lock|#Errors}} a database is opened by another process.<br/>{{Error|name|#Errors}} the specified name is not a [[Commands#Valid_Names|valid database name]].<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.<br/>{{Error|args|#Errors}} the number of specified inputs and paths differs.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|lock|#Errors}} a database is opened by another process.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.
|-
| '''Examples'''
==db:add==
{{Mark|Updated with Version 9.3:}} Allow empty {{Code|$path}} argument.
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:add|$db as xs:string, $input as item()|empty-sequence()}}<br/>{{Func|db:add|$db as xs:string, $input as item(), $path as xs:string?|empty-sequence()}}<br/>{{Func|db:add|$db as xs:string, $input as item(), $path as xs:string?, $options as map(*)?|empty-sequence()|empty-sequence()}}
|-
| '''Summary'''
|Adds documents specified by {{Code|$input}} to the database {{Code|$db}} with the specified {{Code|$path}}:
* A document with the same path may occur more than once in a database. If you want to enforce single instances, use [[#db:replace|db:replace]] instead.
* See [[#db:create|db:create]] for more details on the input argumentand path arguments.
* The parsing behavior can be controlled via {{Code|$options}}:
** allowed options are {{Option|ADDCACHE}} and the [[Options#Parsing|parsing]] and [[Options#XML Parsing|XML parsing]] options, all in lower case
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|FODC0002|XQuery Errors#Functions Errors}} the input points to an unknown resource.<br/>{{Error|FOUP0001|XQuery Errors#Update Errors}} an attribute was specified as input.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|path|#Errors}} the specified path is invalid.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|lock|#Errors}} a database is opened by another process.<br/>{{Error|name|XQuery Errors#BaseX Errors}} invalid database name.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.
|}
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|lock|#Errors}} a database is opened by another process.<br/>{{Error|name|XQuery Errors#BaseX Errors}} invalid database name.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.
|}
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|name|XQuery Errors#BaseX Errors}} invalid database name.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|backup|XQuery Errors#BaseX Errors}} No backup file found.<br/>{{Error|name|XQuery Errors#BaseX Errors}} invalid database name.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.
|-
| '''Examples'''
* {{Code|db:drop-backup("DB")}} drops all backups of the database {{Code|DB}}.
* {{Code|db:drop-backup("DB-2014-03-13-17-36-44")}} drops the specific backup file {{Code|DB-2014-03-13-17-36-44.zip}} of the database {{Code|DB}}.
|}
==db:alter-backup==
{{Mark|Introduced with Version 9.3:}}
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:alter-backup|$name as xs:string, $new-name as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Renames all backups of the database with the specified {{Code|$name}} to {{Code|$new-name}}. The directory inside the archive will be renamed as well. If the given {{Code|$name}} points to a specific backup file, only this specific backup file will be renamed.
|-
| '''Errors'''
|{{Error|backup|#Errors}} No backup file found.<br/>{{Error|name|#Errors}} invalid database name.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.
|-
| '''Examples'''
|
* {{Code|db:alter-backup("DB", "DB2)}} renames all backups of the database {{Code|DB}} to {{Code|DB2}}.
|}
|-
| '''Errors'''
|{{Error|lock|#Errors}} a database is opened by another process.<br/>{{Error|name|XQuery Errors#BaseX Errors}} invalid database name.<br/>{{Error|no-backup|XQuery Errors#BaseX Errors}} No backup found.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.
|-
| '''Examples'''
|-
| width='120' | '''Signatures'''
|{{Func|db:optimize|$db as xs:string|empty-sequence()}}<br/>{{Func|db:optimize|$db as xs:string, $all as xs:boolean|empty-sequence()}}<br/>{{Func|db:optimize|$db as xs:string, $all as xs:boolean, $options as map(*)?|empty-sequence()}}
|-
| '''Summary'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|FOUP0002|XQuery Errors#Update Errors}} an error occurred while optimizing the database.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|path|#Errors}} the specified source or target path, or one of its descendants, is invalid.
|-
| '''Examples'''
|-
| width='120' | '''Signatures'''
|{{Func|db:replace|$db as xs:string, $path as xs:string, $input as item()|empty-sequence()}}<br/>{{Func|db:replace|$db as xs:string, $path as xs:string, $input as item(), $options as map(*)?|empty-sequence()|empty-sequence()}}
|-
| '''Summary'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|target|#Errors}} the path points to a directory.<br/>{{Error|FODC0002|XQuery Errors#Functions Errors}} the input points to an unknown resource.<br/>{{Error|FOUP0001|XQuery Errors#Update Errors}} an attribute was specified as input.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|mainmem|#Errors}} the database is not ''persistent'' (stored on disk).<br/>{{Error|FODC0007|XQuery Errors#Functions Errors}} the specified path is invalid.<br/>{{Error|FOUP0002|XQuery Errors#Update Errors}} the resource cannot be stored at the specified location.
|-
| '''Examples'''
return db:store($db, $trg, db:retrieve($db, $src))
</pre>
|}
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|}
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|-
| '''Summary'''
|-
| '''Errors'''
|{{Error|open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|FODC0002|XQuery Errors#Functions Errors}} the addressed resource is not found or cannot be retrieved.
|-
| '''Examples'''
=Errors=
{| class="wikitable" width="100%"
|{{Code|open}}
|The addressed database does not exist or could not be opened.
|-
|{{Code|option}}
|The specified option is unknown.
|-
|{{Code|path}}
|-
|{{Code|property}}
|A The specified database property is unknown.
|-
|{{Code|range}}
=Changelog=
;Version 9.3
* Added: [[#db:alter-backup|db:alter-backup]]
* Updated: [[#db:open-id|db:open-id]], [[#db:open-pre|db:open-pre]]: support for multiple integers
;Version 9.2
* Added: [[#db:dir|db:dir]]
* Updated: [[#db:add|db:add]]: {{Code|$path}} allow empty path argument
;Version 9.0
* Added: [[#db:option|db:option]]* Updated: db:output renamed to {{Function|Update|update:output}}, db:output-cache renamed to {{Function|Update|update:cache}}* Updated: error codes updatesupdated; errors now use the module namespace
;Version 8.6
