Changes

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/>All errors are assigned to the <code><nowiki>http://basex.org/errors</nowiki></code> namespace, which is statically bound to the {{Code|bxerr}} prefix.

Database nodes are XML nodes which are either stored in a persistent database , or part of which contained in a so-called ''database fragment''. All XML fragments can be converted to database fragments by e. g. applying the [[XQuery_Update#transform|transform]] expression on an XML fragment:

|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.|-| '''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).

|Returns meta information on the database {{Code|$db}}. The output is similar to the [[Commands#INFO DB{{Command|INFO DB]] }} command.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.|} ==db:property== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|db:property|$db as xs:string, $name as xs:string|xs:anyAtomicType}}|-| '''Summary'''|Returns the value (string, boolean, integer) of a property with the specified {{Code|$name}} in the database {{Code|$db}}. The available properties are the ones returned by [[#db:info|db:info]].|-| '''Errors'''|{{Error|property|#Errors}} the specified property is unknown.|-| '''Examples'''|* <code>db:property('db', 'size')</code> returns the number of bytes occupied by the database <code>db</code>.* <code>db:property('xmark', 'textindex')</code> indicates if the <code>xmark</code> database has a text index.* <code>db:property('discogs', 'uptodate')</code> indicates if the database statistics and index structures of the <code>discogs</code> database are up-to-date.

|Returns a string sequence with The result of this function is dependent on the number of arguments:* Without arguments, the names of all databases:are returned that are accessible to the current user.

* The list of returned resources can be further restricted by the {{Code|$path}} argument.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.

* {{Code|db:list("docs")}} returns the names of all documents from the of a database named {{Code|docs}}.

|Without arguments, an element is returned for each database that is accessible to the current user:* If no argument is specifiedAn element has a value, a sequence of elements which is returned. A single element contains the name of a the database, and several attributes, which contain the number of stored resources, the modification date of modification, the database size on disk (measured in bytes), and a path to the original database pathinput.* If a database {{Code|$db}} is specified, a sequence an element for each documents and raw file of elements the specified database is returned, comprising information on all resources of the addressed database. :* An element contains has a value, which is the name of the resource, and several attributes, which contain the content type, the modified modification date, the raw flag (which indicates if the resource is binary or XML), and the size of a resource.* For binary resources, The value of the size is attribute depends on the resource type: for documents, it represents the number of bytesnodes; for document resourcesbinary data, it represents the file size is the number of nodes(measured in bytes).

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.

* {{Code|db:list-details("docsshop")}} returns the names plus additional data info on all resources of all documents from the a database named {{Code|docsshop}}.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0009range|XQuery Errors#BaseX Errors}} the specified pre value does not exist in the database.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0009range|XQuery Errors#BaseX Errors}} the specified id value does not exist in the database.

|{{Error|BXDB0001node|#Errors}} {{Code|$nodes}} contains a node which is not stored in a database.

|{{Error|BXDB0001node|#Errors}} {{Code|$nodes}} contains a node which is not stored in a database.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0003mainmem|#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.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.

|{{Func|db:text|$db as xs:string, $strings as xs:string as item()*|text()*}}

|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.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0004no-index|Database Module#Errors}} the index is not available.<br/>

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0004no-index|Database Module#Errors}} the index is not available.<br/>

|{{Func|db:attribute|$db as xs:string, $strings as as xs:string as item()*|attribute()*}}<br/>{{Func|db:attribute|$db as xs:string, $string strings as item()xs:strings*, $name as xs:string|attribute()*}}

|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.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0004no-index|Database Module#Errors}} the index is not available.<br/>

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0004no-index|Database Module#Errors}} the index is not available.<br/>

|{{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()*}}

|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.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0004no-index|Database Module#Errors}} the index is not available.<br/>

|{{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()}}

** strings may can be a URI pointing to a file/directory references, or an XML strings string (which are is detected by the leading <code>&lt;</code> character)

* The parsing and indexing behavior can be controlled via {{Code|$options}} argument can be used to change the indexing behavior:** the allowed options are {{Option|ADDCACHE}} and the [[Options#Indexing|indexing]], [[Options#Full-TextIndexing|full-textindexing]], [[Options#Parsing|parsing]] and [[Options#XML Parsing|XML parsing]] options, all in lower case.** the parsing options are will only applied to impact string input (URIs, XML strings or file/directory references), because nodes have already been parsed.* An existing database will be overwritten. Next, {{Code|db:create}} will be placed last on the * Database creation takes place after most other update operations (see [[XQuery Update#Pending Update List|Pending Update List]]). As a consequence, a newly created database cannot be addressed in the same query.

|{{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|BXDB0007lock|#Errors}} a database is opened by another process.<br/>{{Error|BXDB0011name|#Errors}} the specified name is not a [[Commands#Valid_Names|valid database name]].<br/>{{Error|BXDB0012conflict|#Errors}} two {{Code|db:create}} statements with the same database name were specifiedwas addressed more than once.<br/>{{Error|BXDB0013args|#Errors}} the number of specified inputs and paths differs.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0007lock|#Errors}} a database is opened by another process.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.

|{{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()}}

* For more information on the arguments, see See [[#db:create|db:create]] (note that for more details on the specified input argument.* The parsing behavior can be controlled via {{Code|$options}}:** allowed options cannot be are {{Option|ADDCACHE}} and the [[Options#IndexingParsing|indexingparsing]] and [[Options#Full-TextXML Parsing|full-textXML parsing]] options, all in lower case** parsing options will only impact string input (URIs, XML strings)., because nodes have already been parsed

|{{Error|BXDB0002open|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.

* {{Code|<code>db:add("DB", "/home/dir/doc.xml")}} </code> adds the file {{Code|/home/dir/doc.xml}} to the database {{Code|DB}}.* {{Code|<code>db:add("DB", <a/>, "doc.xml")}} </code> adds a document node to the database {{Code|DB}} under the name {{Code|doc.xml}}.* {{Code|<code>db:add("DB", "/home/dir", "docs/dir", map { 'addcache': true()}} )</code> adds all documents in {{Code|/home/dir}} to the database {{Code|DB}} under the path {{Code|docs/dir}}. In order to reduce memory consumption, the files will be cached before being added to the database.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0008path|#Errors}} the specified path is invalid.

|{{Func|db:copy|$db as xs:string, $newname name as xs:string|empty-sequence()}}

|Creates a copy of the database specified by {{Code|$db}} to , which will be called {{Code|$newnamename}}.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0011lock|XQuery #Errors}} a database is opened by another process.<br/>{{Error|name|#BaseX Errors}} invalid database name.<br/>{{Error|BXDB0016conflict|XQuery Errors#BaseX Errors}} name of source and target the same database is equalwas addressed more than once.

|{{Func|db:alter|$db as xs:string, $newname name as xs:string|empty-sequence()}}

|Renames the database specified by {{Code|$db}} to {{Code|$newnamename}}.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0011lock|XQuery #Errors}} a database is opened by another process.<br/>{{Error|name|#BaseX Errors}} invalid database name.<br/>{{Error|BXDB0016conflict|XQuery Errors#BaseX Errors}} name of source and target the same database is equalwas addressed more than once.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0011name|XQuery Errors#BaseX Errors}} invalid database name.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.

|{{Error|BXDB0002backup|XQuery Errors#BaseX Errors}} No backup file found.<br/>{{Error|BXDB0011name|XQuery Errors#BaseX Errors}} invalid database name.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.

|{{Error|BXDB0011lock|XQuery #Errors}} a database is opened by another process.<br/>{{Error|name|#BaseX Errors}} invalid database name.<br/>{{Error|BXDB0015no-backup|XQuery Errors#BaseX Errors}} No backup found.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.

|{{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()}}

|{{Error|BXDB0002open|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.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0008path|#Errors}} the specified source or target path, or one of its descendants, is invalid.

|{{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()}}

* See [[#db:addcreate|db:addcreate]] for more details on the arguments input argument.* 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** parsing options will only impact string input (for URIs, XML strings), because nodes have already been parsed* For historical reasons, the order of the 2nd and 3rd argument differs!).is different to [[#db:add|db:add]] and [[#db:create|db:create]]

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0014target|#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.

|Stores Replaces a binary resource specified by {{Code|$input}} in the database {{Code|$db}} and the location specified by {{Code|$path}}, or adds it as new resource.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0003mainmem|#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.

|}* With the following query, you can copy full directories:<pre class="brush:xquery">==let $db:output== {| width='100%db'|let $src-| widthpath :='120' | '''Signatures''src/'|{{Func|db:output|let $result as item()*|emptytrg-sequence()}}|-| '''Summary'path := 'trg/'|This function can be used to both perform updates and return results for $src 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 db:list'' have been processed. As nodes may be updated($db, 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.|$src-path)| '''Examples'''|* {{Code|where db:outputis-raw("Prices have been deleted."$db, $src), delete node //price}} deletes all {{Code|price}} elements in a database and returns an info message.|} ==dblet $trg :output-cache== {| width='100%'|$trg-| width='120' | '''Signatures'''path |{{Func|db:outputsubstring-cache||itemafter($src, $src-path)*}}|-| '''Summary'''|Returns the items that have been cached by [[#return db:output|store($db, $trg, db:output]]. It can be used to check which items will eventually be returned as result of an updating function.retrieve($db, $src))<br/pre>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]].

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.

|{{Error|BXDB0001node|#Errors}} {{Code|$nodes}} contains a node which is not stored in a database.

|{{Error|BXDB0001node|#Errors}} {{Code|$nodes}} contains a node which is not stored in a database.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.

|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.

|{{Error|BXDB0002open|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.

|{{Code|BXDB0001args}}|The referenced XML node is no [[#Database Nodesnumber of specified inputs and paths differs.|-|database node]], i.e. it is neither stored in a database nor represented as database fragment{{Code|conflict}}|Multiple update operations point to the same target.

|{{Code|BXDB0002lock}}|The addressed A database does not exist or could not cannot be updated because it is openedby another process.

|{{Code|BXDB0003mainmem}}

|{{Code|BXDB0004name}}|The name of the specified database lacks an index structure required by the called functionis invalid.

|{{Code|BXDB0005no-backup}}|A query is expected to exclusively return [[#Database Nodes|database nodes]] of No backup exists for a single database.

|{{Code|BXDB0006node}}|A The referenced XML node is no [[#Database Nodes|database node]], i.e. it is neither stored in a database nor represented as database path addressed with {{Code|doc()}} contains more than one documentfragment.

|{{Code|BXDB0007no-index}}|A The database cannot lacks an index structure required by the called function.|-|{{Code|open}}|The addressed database does not exist or could not be updated because it is opened by another process.

|{{Code|BXDB0008path}}

|{{Code|BXDB0009property}}|A database property is unknown.|-|{{Code|range}}

|{{Code|BXDB0011}}|The name of the specified database is invalid.|-|{{Code|BXDB0012}}|A database can only be created once.|-|{{Code|BXDB0013}}|The number of specified inputs and paths differs.|-|{{Code|BXDB0014target}}|Path points to a directoryan invalid target.