Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
[[Category:XQuery]]
→Database Nodes
==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">
| '''Errors'''
|{{Error|BXDB0002|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.
|}
==db:property==
{{Mark|Introduced with Version 8.6}}:
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:property|$db as xs:string, $property as xs:string|xs:anyAtomicType}}
|-
| '''Summary'''
|Returns the specified {{Code|$property}} of the database {{Code|$db}}. The available properties are the ones returned by [[#db:info|db:info]].
|-
| '''Errors'''
|{{Error|BXDB0017|XQuery Errors#BaseX 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.
|}
|-
| '''Summary'''
|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.
* 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 further restricted by the {{Code|$path}} argument.
|-
| '''Errors'''
| '''Examples'''
|
* {{Code|db:list("docs")}} returns the names of all documents from the of a database named {{Code|docs}}.
|}
|-
| '''Summary'''
|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).
* Returned databases resources can be further restricted by the {{Code|$path}} argument.
|-
| '''Examples'''
|
* {{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}}.
|}
|-
| '''Summary'''
|Opens the database {{Code|$db}} and returns the node with the specified {{Code|$id}} value.<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 [[Options#UPDINDEX{{Option|UPDINDEX]] }} option.
|-
| '''Errors'''
|-
| '''Summary'''
|Returns the ''id'' values of the nodes supplied by {{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 [[Options#UPDINDEX{{Option|UPDINDEX]] }} option.
|-
| '''Errors'''
* {{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.
|}
|-
| width='120' | '''Signatures'''
|{{Func|db:attribute|$db as xs:string, $string as item()|attribute()*}}<br/>{{Func|db:attribute|$db as xs:string, $string as item(), $attname name as xs:string|attribute()*}}
|-
| '''Summary'''
|Returns all attribute nodes of the database {{Code|$db}} that have {{Code|$string}} as string value and that are stored in the attribute index.<br />If {{Code|$attnamename}} is specified, the resulting attribute nodes are filtered by their attribute name.
|-
| '''Errors'''
|-
| width='120' | '''Signatures'''
|{{Func|db:attribute-range|$db as xs:string, $min as xs:string, $max as xs:string|attribute()*}}<br/>{{Func|db:attribute-range|$db as xs:string, $min as xs:string, $max as xs:string, $attname name as xs:string|attribute()*}}
|-
| '''Summary'''
|
* {{Code|db:attribute-range("DB", "id456", "id473", 'id')}} returns all {{Code|@id}} attributes of the database {{Code|DB}} that have a string value in between {{Code|id456}} and {{Code|id473}}.
|}
==db:token==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:token|$db as xs:string, $token as item()|attribute()*}}<br/>{{Func|db:token|$db as xs:string, $token as item(), $name as xs:string|attribute()*}}
|-
| '''Summary'''
|Returns all attribute nodes of the database {{Code|$db}}, the value of which contains the specified {{Code|$token}}.<br />If {{Code|$name}} is specified, the resulting attribute nodes are filtered by their attribute name.
|-
| '''Errors'''
|{{Error|BXDB0002|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0004|Database Module#Errors}} the index is not available.<br/>
|-
| '''Examples'''
|
* {{Code|db:token("DB", "row", "class")/parent::div}} returns all {{Code|div}} nodes of database {{Code|DB}} with a {{Code|class}} attribute that contains the token {{Code|row}}.
|}
* {{Code|$inputs}} may be strings or nodes:
** nodes may be of any type except for attributes
** 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><</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:** allowed options are all {{Option|ADDCACHE}} and the [[Options#Indexing|indexing]] and , [[Options#Full-TextIndexing|full-textindexing]], [[Options#Parsing|parsing]] and [[Options#XML Parsing|XML parsing]] options , all in lower case** parsing options are will only applied to impact string inputs 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}} {{Code|$inputs}} an input points to an unknown resource.<br/>{{Error|FOUP0001|XQuery Errors#Update Errors}} {{Code|$inputs}} is neither string nor a document nodean attribute was specified as input.<br/>{{Error|BXDB0007|#Errors}} {{Code|$db}} a database is opened by another process.<br/>{{Error|BXDB0011|#Errors}} {{Code|$db}} the specified name is not a [[Commands#Valid_Names|valid database name]].<br/>{{Error|BXDB0012|#Errors}} two {{Code|db:create}} statements with the same database name were specified.<br/>{{Error|BXDB0013|#Errors}} the number of specified inputs and paths differs.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|BXDB0002|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0007|#Errors}} {{Code|$db}} a database is opened by another process.
|-
| '''Examples'''
|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 must not 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|BXDB0002|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}} the an attribute was specified as input is neither string nor a document node.
|-
| '''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.
|}
|-
| '''Summary'''
|Deletes documentresource(s), specified by {{Code|$path}}, from the database {{Code|$db}}.
|-
| '''Errors'''
|{{Error|BXDB0002|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0008|#Errors}} the specified path is invalid.
|-
| '''Examples'''
|
* {{Code|db:delete("DB", "docs/dir/doc.xml")}} deletes the document resource {{Code|docs/dir/doc.xml}} in the database from {{Code|DB}}.* {{Code|db:delete("DB", "docs/dir")}} deletes all documents with paths beginning with resources from {{Code|docs/dirDB}} in the database specified path {{Code|DBdocs/dir}}.
|}
|-
| 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'''
|-
| 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'''
|-
| '''Summary'''
|Optimizes the meta data and indexes of the database {{Code|$db}}.<br/>If {{Code|$all}} is {{Code|true}}, the complete database will be rebuilt.<br/>The {{Code|$options}} argument can be used to control indexing. The syntax is identical to the [[#db:create|db:create]] function: Allowed options are all [[Options#Indexing|indexing]] and [[Options#Full-Text|full-text]] options. [[Options#UPDINDEX{{Option|UPDINDEX]] }} is only allowed supported if {{Code|$all}} is {{Code|true}}.
|-
| '''Errors'''
|-
| width='120' | '''Signatures'''
|{{Func|db:rename|$db as xs:string, $path source as xs:string, $newpath target as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Renames documentMoves all resources(s), specified by of database {{Code|$pathdb}} to , which are found in the supplied {{Code|$newpathsource}} in path, to the database supplied {{Code|$dbtarget}}path. The paths may point to single resources or directories. No updates will take place if a non-existing source path is supplied.
|-
| '''Errors'''
|{{Error|BXDB0002|XQuery Errors#BaseX Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|BXDB0008|#Errors}} new document names would be emptythe specified source or target path, or one of its descendants, is invalid.
|-
| '''Examples'''
|
* {{Code|db:rename("DB", "docs/dir/doc.xml", "docs/dir/newdoc.xml")}} renames the document resource {{Code|docs/dir/doc.xml}} to {{Code|docs/dir/newdoc.xml}} in the database {{Code|DB}}.* {{Code|db:rename("DB", "docs/dir", "docs/newdir")}} renames moves all documents with paths beginning with resources in the database {{Code|docs/dirDB}} to paths beginning with from {{Code|docs/newdirdir}} in the database {to {Code|DBdocs/newdir}}.
|}
|-
| '''Summary'''
|Replaces a documentresource, specified by {{Code|$path}}, in the database {{Code|$db}} with the contents of {{Code|$input}}, or adds it as a new documentresource:* 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'''
|-
| '''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'''
|
* {{Code|db:store("DB", "video/sample.mov", file:read-binary('video.mov'))}} stores the addressed video file at the specified location.
* With the following query, you can copy full directories:
<pre class="brush:xquery">
let $db := 'db'
let $src-path := 'src/'
let $trg-path := 'trg/'
for $src in db:list($db, $src-path)
where db:is-raw($db, $src)
let $trg := $trg-path || substring-after($src, $src-path)
return db:store($db, $trg, db:retrieve($db, $src))
</pre>
|}
|-
| '''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'': Its It will return different results before and after items have been cached. It is e. g. useful when writing [[Unit Module|unit tests]].
|}
|-
| '''Summary'''
|Explicitly flushes the buffers of the database {{Code|$db}}. This command is only useful if [[Options#AUTOFLUSH{{Option|AUTOFLUSH]] }} has been set to {{Code|false}}.
|-
| '''Errors'''
|-
|{{Code|BXDB0008}}
|Database paths cannot be renamed to empty stringsThe specified database path is invalid.
|-
|{{Code|BXDB0009}}
|{{Code|BXDB0014}}
|Path points to a directory.
|-
|{{Code|BXDB0015}}
|No backup is found.
|-
|{{Code|BXDB0016}}
|Name of the source and target database is equal.
|-
|{{Code|BXDB0017}}
|The specified property is unknown..
|}
=Changelog=
;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
;Version 7.9
* Updated: parsing options added to [[#db:create|db:create]], [[#db:add|db:add]] and [[#db:replace|db:replace]].
* Updated: allow [[Options#UPDINDEX{{Option|UPDINDEX]] }} if {{Code|$all}} is {{Code|true}}.
;Version 7.8.2
* Added: [[#db:retrieve|db:retrieve]], [[#db:store|db:store]], [[#db:exists|db:exists]], [[#db:is-raw|db:is-raw]], [[#db:is-xml|db:is-xml]]
* Updated: [[#db:list|db:list]], [[#db:open|db:open]], [[#db:add|db:add]]
