Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
|}* 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]].
→db:property
=Conventions=
{{Mark|Updated with Version 9.0:}} 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==
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:
<pre class="brush:xquery">
|-
| '''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== {{Mark|Introduced with Version 9.0:}} {| 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).
|}
|-
| '''Summary'''
|Returns meta information on the database {{Code|$db}}. The output is similar to the {{Command|INFO DB}} command.|-| '''Errors'''|{{Error|open|#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 [[Commands#INFO DBdb:info|INFO DBdb:info]] command.
|-
| '''Errors'''
|{{Error|BXDB0002property|XQuery Errors#BaseX Errors}} the addressed 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 does not exist or could not be openedare up-to-date.
|}
| '''Summary'''
|The result of this function is dependent on the number of arguments:
* Without arguments, the names of all databases are returnedthat are accessible to the current user.
* If a database {{Code|$db}} is specified, all documents and raw files of the specified database are returned.
* The list of returned resources can be restricted by the {{Code|$path}} argument.
|-
| '''Errors'''
|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|-
| '''Examples'''
|-
| '''Summary'''
|Without arguments, an element is returned for each databasethat is accessible to the current user:
* An element has a value, which is the name of the database, and several attributes, which contain the number of stored resources, the modification date, the database size on disk (measured in bytes), and a path to the original database input.
If a database {{Code|$db}} is specified, an element for each documents and raw file of the specified database is returned:
|-
| '''Errors'''
|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|-
| '''Examples'''
|-
| '''Errors'''
|{{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.
|-
| '''Examples'''
|-
| '''Errors'''
|{{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.
|}
|-
| '''Errors'''
|{{Error|BXDB0001node|#Errors}} {{Code|$nodes}} contains a node which is not stored in a database.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|BXDB0001node|#Errors}} {{Code|$nodes}} contains a node which is not stored in a database.
|}
|-
| '''Errors'''
|{{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.
|-
| '''Examples'''
* {{Code|db:retrieve("DB", "music/01.mp3")}} returns the specified audio file as raw data.
* <code><nowiki>stream:materialize(db:retrieve("DB", "music/01.mp3"))</nowiki></code> materializes the streamable result in main-memory before returning it.
* <code><nowiki>convert:binary-to-string(db:retrieve("DB", "info.txt"), 'UTF-8')</nowiki></code> converts a binary database resource as UTF-8 text and returns a string.
|}
|-
| '''Errors'''
|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|-
| '''Examples'''
|-
| '''Errors'''
|{{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/>
|-
| '''Examples'''
|-
| '''Errors'''
|{{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/>
|-
| '''Examples'''
|-
| '''Errors'''
|{{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/>
|-
| '''Examples'''
|-
| '''Errors'''
|{{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/>
|-
| '''Examples'''
|-
| '''Errors'''
|{{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/>
|-
| '''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'''
** strings can be a URI pointing to a file/directory or an XML string (which is detected by the leading <code><</code> character)
** a path must be specified if the input is not a file or directory reference
* 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.
|-
| '''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|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.
|-
| '''Examples'''
|-
| '''Errors'''
|{{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.
|-
| '''Examples'''
|-
| 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.
* 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
|-
| '''Errors'''
|{{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.
|-
| '''Examples'''
|
* {{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.
|}
|-
| '''Errors'''
|{{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.
|-
| '''Examples'''
|-
| width='120' | '''Signatures'''
|{{Func|db:copy|$db as xs:string, $newname name as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Creates a copy of the database specified by {{Code|$db}} to , which will be called {{Code|$newnamename}}.
|-
| '''Errors'''
|{{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.
|}
|-
| width='120' | '''Signatures'''
|{{Func|db:alter|$db as xs:string, $newname name as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Renames the database specified by {{Code|$db}} to {{Code|$newnamename}}.
|-
| '''Errors'''
|{{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.
|}
|-
| '''Errors'''
|{{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.
|-
| '''Examples'''
|-
| '''Errors'''
|{{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.
|-
| '''Examples'''
|-
| '''Errors'''
|{{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.
|-
| '''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|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.
|-
| '''Examples'''
|-
| '''Errors'''
|{{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.
|-
| '''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'''
|Replaces a resource, specified by {{Code|$path}}, in the database {{Code|$db}} with the contents of {{Code|$input}}, or adds it as a new resource:
* 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]]
|-
| '''Errors'''
|{{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.
|-
| '''Examples'''
|-
| '''Summary'''
|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.
|-
| '''Errors'''
|{{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.
|-
| '''Examples'''
|
* {{Code|db:store("DB", "video/sample.mov", file:read-binary('video.mov'))}} stores the addressed video file at the specified location.
|}
|-
| '''Errors'''
|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|}
|-
| '''Errors'''
|{{Error|BXDB0001node|#Errors}} {{Code|$nodes}} contains a node which is not stored in a database.
|}
|-
| '''Errors'''
|{{Error|BXDB0001node|#Errors}} {{Code|$nodes}} contains a node which is not stored in a database.
|}
|-
| '''Errors'''
|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|BXDB0002open|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|-
| '''Summary'''
|-
| '''Errors'''
|{{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.
|-
| '''Examples'''
=Errors=
{{Mark|Updated with Version 9.0:}}
{| class="wikitable" width="100%"
|Description
|-
|{{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}}
|The addressed database is not ''persistent'' (stored on disk).
|-
|{{Code|BXDB0004name}}|The name of the specified database is invalid.|-|{{Code|no-backup}}|No backup exists for a database lacks an index structure required by the called function.
|-
|{{Code|BXDB0005node}}|A query The referenced XML node is expected to exclusively return no [[#Database Nodes|database nodesnode]] of , i.e. it is neither stored in a single databasenor represented as database fragment.
|-
|{{Code|BXDB0006no-index}}|A The database path addressed with {{Code|doc()}} contains more than one documentlacks an index structure required by the called function.
|-
|{{Code|BXDB0007open}}|A The addressed database cannot does not exist or could not be updated because it is opened by another process.
|-
|{{Code|BXDB0008path}}
|The specified database path is invalid.
|-
|{{Code|BXDB0009property}}|A database property is unknown.|-|{{Code|range}}
|The addressed database id or pre value is out of 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.
|}
=Changelog=
;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:output-cache}}
* Updated: error codes updated; errors now use the module namespace
;Version 8.6
* Added: [[#db:property|db:property]]
;Version 8.4
* Updated: [[#db:create|db:create]], [[#db:add|db:add]], [[#db:replace|db:replace]]: support for {{Code|ADDCACHE}} option.
* Added: [[#db:token|db:token]]
;Version 8.3
* Updated: [[#db:list-details|db:list-details]]: attributes with name of database and date of backup added to results.
* Updated: [[#db:backups|db:backups]] now include attributes with name of database and date of backup.
;Version 8.2
* Added: [[#db:output-cache|db:output-cache]]
* Removed: db:event
;Version 7.9
* Updated: parsing options added to [[#db:create|db:create]], [[#db:add|db:add]] and [[#db:replace|db:replace]].
* Updated: allow {{Option|UPDINDEX}} if {{Code|$all}} is {{Code|true}}.
;Version 7.8.2
* Added: [[#db:alter|db:alter]], [[#db:copy|db:copy]], [[#db:create-backup|db:create-backup]], [[#db:drop-backup|db:drop-backup]], [[#db:restore|db:restore]]
;Version 7.8
* Removed: db:fulltext (use [[Full-Text Module#ft:search|ft:search]] instead)
