Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
|}
==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]].
→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==
|-
| '''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 [[Commands#INFO DB{{Command|INFO DB]] }} command.
|-
| '''Errors'''
|{{Error|BXDB0002open|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|BXDB0017property|XQuery Errors#BaseX Errors}} the specified property is unknown.
|-
| '''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.
|-
| '''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'''
|-
| '''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'''
|-
| '''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'''
|-
| '''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'''
|-
| '''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'''
|-
| '''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|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'''
|-
| '''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'''
|-
| '''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'''
return db:store($db, $trg, db:retrieve($db, $src))
</pre>
|}
|-
| '''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 directory.|-|{{Code|BXDB0015}}|No backup is found.|-|{{Code|BXDB0016}}|Name of the source and an invalid target database is equal.|-|{{Code|BXDB0017}}|The specified property is unknown..
|}
=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)
