Changes

|Returns the current value (string, integer, boolean, map) of a global or local [[Options|Option]] with the specified {{Code|$name}}. The {{Command|GETSHOW OPTIONS}} command works returns similaroutput.

{{Announce|Updated with Version 10:}} Renamed (before: {{Code|db:open}}). Due to its popularity, the old function name will be supported for some more time. ==db:openget==

|{{Func|db:openget|$db as xs:string|document-node()*}}<br />{{Func|db:openget|$db as xs:string, $path as xs:string|document-node()*}}

* {{Code|db:openget("'docs"')}} returns all documents from the database named {{Code|docs}}.* {{Code|db:openget("'db"', "'one"')}} returns all documents from the database named {{Code|db}} located in the path {{Code|one}}.* <code>for $i in 1 to 3 return db:openget("'db" ' || $i)//item</code> returns all item elements from the databases {{Code|db1}}, {{Code|db2}} and {{Code|db3}}.

==db:openget-pre== {{Announce|Updated with Version 10:}} Renamed (before: {{Code|db:open-pre}}).

|{{Func|db:openget-pre|$db as xs:string, $pres as xs:integer*|node()*}}

* {{Code|db:openget-pre("docs", 0)}} returns the first database node from the database named {{Code|docs}}.

==db:openget-id== {{Announce|Updated with Version 10:}} Renamed (before: {{Code|db:get-id}}).

|{{Func|db:openget-id|$db as xs:string, $ids as xs:integer*|node()*}}

==db:nodeget-prebinary== {{Announce|Updated with Version 10}}: renamed (before: {{Code|db:retrieve}}).

|{{Func|db:nodeget-prebinary|$nodes db as node()*xs:string, $path as xs:string|xs:integer*base64Binary}}

|Returns a [[Binary Data|binary resource]] addressed by the ''pre'' values of the specified database {{Code|$db}} and {{Code|$nodespath}}, which must all be as [[#Database NodesStreaming Module|database nodesstreamable]].<br/>The [[Node Storage#PRE Value{{Code|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 databasexs:base64Binary}}.

|{{Error|nodeopen|#Errors}} the addressed database does not exist or could not be opened.<br/>{{CodeError|mainmem|$nodes#Errors}} contains a node which the database is not ''persistent'' (stored in a databaseon disk).

* {{Code|db:nodeget-pre(docbinary("inputDB", "music/01.mp3"))}} returns {{Code|0}} if the specified audio file as raw data.* <code><nowiki>stream:materialize(db:get-binary("DB", "music/01.mp3"))</nowiki></code> materializes the streamable result in main-memory before returning it.* <code><nowiki>convert:binary-to-string(db:get-binary("DB", "info.txt"), 'UTF-8')</nowiki></code> converts a binary database {{Code|input}} contains resource as UTF-8 text and returns a single documentstring.

==db:nodeget-idvalue== {{Announce|Introduced with Version 10.}}

|{{Func|db:nodeget-idvalue|$nodes db as nodexs:string, $path as xs:string|item()*|xs:integer*}}

|Returns an XQuery value stored in the ''id'' values of the specified database {{Code|$nodesdb}}, 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 at the specified {{OptionCode|UPDINDEX$path}} option.

|{{Error|nodeopen|#Errors}} the addressed database does not exist or could not be opened.<br/>{{CodeError|mainmem|$nodes#Errors}} contains a node which the database is not ''persistent'' (stored in a databaseon disk).|-| '''Examples'''|* {{Code|db:get-value('DB', 'sequence')}} returns the specified sequence.

==db:getnode-pre== {{Announce|Introduced with Version 10.}}

|{{Func|db:getnode-pre|$db as xs:string, $path nodes as node()*|xs:string|item()integer*}}

|Returns an XQuery value stored in the database {{Code|$db}} at ''pre'' values of the specified {{Code|$pathnodes}}, 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.

|{{Error|opennode|#Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|mainmemCode|#Errors$nodes}} the database contains a node which is not ''persistent'' (stored on disk)in a database.

* {{Code|db:getnode-pre('DB', 'sequence'doc("input"))}} returns {{Code|0}} if the specified sequencedatabase {{Code|input}} contains a single document.

==db:getnode-binaryid== {{Announce|Updated with Version 10}}: renamed (before: {{Code|db:retrieve}}).

|{{Func|db:getnode-binaryid|$db nodes as xs:string, $path as xs:stringnode()*|xs:base64Binaryinteger*}}

|Returns a [[Binary Data|binary resource]] addressed by the database ''id'' values of the specified {{Code|$dbnodes}} and {{Code, which must all be [[#Database Nodes|$path}} as database nodes]].<br/>Each database node has a ''persistent'' [[Streaming ModuleNode Storage#ID Value|streamableID value]] . Access to the node id can be sped up by turning on the {{CodeOption|xs:base64BinaryUPDINDEX}}option.

|{{Error|opennode|#Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|mainmemCode|#Errors$nodes}} the database contains a node which is not ''persistent'' (stored on disk).|-| '''Examples'''|* {{Code|db:get-binary("DB", "music/01.mp3")}} returns the specified audio file as raw data.* <code><nowiki>stream:materialize(db:get-binary("DB", "music/01.mp3"))</nowiki></code> materializes the streamable result in main-memory before returning it.* <code><nowiki>convert:binary-to-string(db:get-binary("DB", "info.txt"), 'UTF-8')</nowiki></code> converts a binary database resource as UTF-8 text and returns a string.

The following query code can be used to export parts of the database:

for $doc in db:openget('DB', 'collection')

==db:dropadd==

|{{Func|db:dropadd|$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()}}

|Drops 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 {{Function||db:put}} instead.* See {{Function||db:create}} for more details on the input and 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 connected resources.in lower case** parsing options will only impact string input (URIs, XML strings), because nodes have already been parsed

|{{Error|open|#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.

* <code>db:add("DB", "/home/dir/doc.xml")</code> adds the file {{Code|/home/dir/doc.xml}} to the database {{Code|DB}}.* <code>db:dropadd("DB", <a/>, "doc.xml")</code> adds a document node to the database {{Code|DB}} drops under the name {{Code|doc.xml}}.* <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.

==db:addput== {{Announce|Updated with Version 10}}: renamed (before: {{Code|db:replace}}); function signature aligned with {{Function||db:add}} (second and third argument swapped).

|{{Func|db:add|$db as xs:string, $input as item()|empty-sequence()}}<br/>{{Func|db:addput|$db as xs:string, $input as item(), $path as xs:string?|empty-sequence()}}<br/>{{Func|db:addput|$db as xs:string, $input as item(), $path as xs:string?, $options as map(*)?|empty-sequence()|empty-sequence()}}

|Adds documents Replaces a resource, specified by {{Code|$inputpath}} to , in the database {{Code|$db}} with the specified contents of {{Code|$pathinput}}:* A document with the same path may occur more than once in , or adds it as a database. If you want to enforce single instances, use {{Function||dbnew resource:update}} instead.* See {{Function||db:create}} for more details on the input and path arguments.

** allowed Allowed options are {{Option|ADDCACHE}} and the [[Options#Parsing|parsing]] and [[Options#XML Parsing|XML parsing]] options, all in lower case.** parsing Parsing options will only impact string input (URIs, XML strings), because nodes have already been parsed.* See {{Function||db:create}} for more details on the input argument.|-| '''Errors'''|{{Error|open|#Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|target|#Errors}} the path points to a directory.|-| '''Examples'''|* {{Code|db:put("DB", "/home/dir/doc.xml", "docs/dir/doc.xml")}} replaces the content of the document {{Code|docs/dir/doc.xml}} in the database {{Code|DB}} with the content of the file {{Code|/home/dir/doc.xml}}.* {{Code|db:put("DB", "<a/>", "docs/dir/doc.xml")}} replaces the content of the document {{Code|docs/dir/doc.xml}} in the database {{Code|DB}} with {{Code|&lt;a/&gt;}}.* {{Code|db:put("DB", document { <a/> }, "docs/dir/doc.xml")}} replaces the content of the document {{Code|docs/dir/doc.xml}} in the database {{Code|DB}} with the specified document node.The following query can be used to import files from a directory to a database:<syntaxhighlight lang="xquery">let $source := '/home/john/xml/source'for $file in file:list($source, true())let $path := $source || $filewhere not(file:is-dir($path))return db:put('db', doc($path), $file)</syntaxhighlight>|} ==db:put-binary== {{Announce|Updated with Version 10}}: renamed (before: {{Code|db:put}}); function signature aligned with {{Function||db:add}} (second and third argument swapped). {| width='100%'|-| width='120' | '''Signatures'''|{{Func|db:put-binary|$db as xs:string, $input as item(), $path as xs:string|empty-sequence()}}|-| '''Summary'''|Stores a binary resource specified by {{Code|$input}} in the database {{Code|$db}} and the location specified by {{Code|$path}}. Existing resources are overwritten.|-| '''Errors'''|{{Error|open|#Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|mainmem|#Errors}} the database is not ''persistent'' (stored on disk).|-| '''Examples'''|* {{Code|db:put-binary('DB', file:read-binary('video.mov'), 'video/sample.mov')}} stores the addressed video file at the specified location.* With the following query, you can copy the binary resources of one database into another:<syntaxhighlight lang="xquery">let $db := 'db'let $src-path := 'src/'let $trg-path := 'trg/'for $src in db:list($db, $src-path)where db:type($db, $src) = 'binary'let $trg := $trg-path || substring-after($src, $src-path)return db:put-binary($db, db:get-binary($db, $src), $trg)</syntaxhighlight>|} ==db:put-value== {{Announce|Introduced with Version 10.}} {| width='100%'|-| width='120' | '''Signatures'''|{{Func|db:put-value|$db as xs:string, $input as item()*, $path as xs:string|empty-sequence()}}|-| '''Summary'''|Stores a value resource specified by {{Code|$input}} in the database {{Code|$db}} and the location specified by {{Code|$path}}. Existing resources are overwritten. The value can be an arbitrary sequence of atomic items, nodes, maps, and arrays.

|{{Error|open|#Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|mainmem|#Errors}} the database is not ''persistent'' (stored on disk).

* <code>{{Code|db:addput-value("'DB"', 1 to 10000, "/home/dir/doc.xml"'sequence')</code> adds the file {{Code|/home/dir/doc.xml}} to stores a numeric range in the database {{Code|DB}}.* <code>db:add("DB"With the following query, <a/>, "doc.xml")</code> adds map with countries and associated cities is stored in a document node to the database {{Code|DB}} under the name {{Code|doc.xml}}The value resource can e.g.be used as index in future queries:* <codesyntaxhighlight lang="xquery">db:addput-value("DB" 'factbook', " map:merge( for $country in db:get('factbook')/home/dir"country return map:entry($country/@name, "docs$country//city/dir"name ! string()) ), map { 'addcachecities': true() })</codesyntaxhighlight> 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.

==db:updateflush== {{Announce|Updated with Version 10}}: renamed (before: {{Code|db:replace}}); function signature aligned with {{Function||db:add}} (second and third argument swapped).

|{{Func|db:updateflush|$db as xs:string, $input as item(), $path as xs:string|empty-sequence()}}<br/>{{Func|db:update|$db as xs:string, $input as item(), $path as xs:string, $options as map(*)?|empty-sequence()|empty-sequence()}}

|Replaces a resource, specified by {{Code|$path}}, in Explicitly flushes the buffers of the database {{Code|$db}} with the contents of {{Code|$input}}, or adds it as a new resource:* The parsing behavior can be controlled via {{Code|$options}}:** Allowed options are . This command is only useful if {{Option|ADDCACHEAUTOFLUSH}} and the [[Options#Parsing|parsing]] and [[Options#XML Parsing|XML parsing]] options, all in lower case.** Parsing options will only impact string input (URIs, XML strings), because nodes have already has been parsed.* See set to {{Function|Code|db:createfalse}} for more details on the input argument.

|{{Error|open|#Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|target|#Errors}} the path points to a directory.|-| '''Examples'''|* {{Code|db:update("DB", "/home/dir/doc.xml", "docs/dir/doc.xml")}} replaces the content of the document {{Code|docs/dir/doc.xml}} in the database {{Code|DB}} with the content of the file {{Code|/home/dir/doc.xml}}.* {{Code|db:update("DB", "<a/>", "docs/dir/doc.xml")}} replaces the content of the document {{Code|docs/dir/doc.xml}} in the database {{Code|DB}} with {{Code|&lt;a/&gt;}}.* {{Code|db:update("DB", document { <a/> }, "docs/dir/doc.xml")}} replaces the content of the document {{Code|docs/dir/doc.xml}} in the database {{Code|DB}} with the specified document node.The following query can be used to import files from a directory to a database:<syntaxhighlight lang="xquery">let $source := '/home/john/xml/source'for $file in file:list($source, true())let $path := $source || $filewhere not(file:is-dir($path))return db:update('db', doc($path), $file)</syntaxhighlight>

==db:putdrop== {{Announce|Introduced with Version 10.}}

|{{Func|db:putdrop|$db as xs:string, $input as item()*, $path as xs:string|empty-sequence()}}

|Stores a value resource specified by {{Code|$input}} in Drops the database {{Code|$db}} and the location specified by {{Code|$path}}. Existing all connected resources are overwritten. The value can be an arbitrary sequence of atomic items, nodes, maps, and arrays.

|{{Error|open|#Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|mainmemlock|#Errors}} a database is opened by another process.<br/>{{Error|conflict|#Errors}} the same database is not ''persistent'' (stored on disk)was addressed more than once.

* {{Code|db:putdrop('"DB', 1 to 10000, 'sequence')}} stores a numeric range in the database.* With the following query, a map with countries and associated cities is stored in a database. The value resource can e.g. be used as index in future queries:<syntaxhighlight lang="xquery">db:put( 'factbook', map:merge( for $country in db:open('factbook')//country return map:entry($country/@name, $country//city/name ! string()) ), 'cities')</syntaxhighlight>|} ==db:put-binary== {{Announce|Updated with Version 10}}: renamed (before: {{Code|db:put}}); function signature aligned with {{Function||db:add}} (second and third argument swapped). {| width='100%'|-| width='120' | '''Signatures'''|{{Func|db:put-binary|$db as xs:string, $input as item(), $path as xs:string|empty-sequence()}}|-| '''Summary'''|Stores a binary resource specified by {{Code|$input}} in the database {{Code|$db}} and the location specified by {{Code|$path}}. Existing resources are overwritten.|-| '''Errors'''|{{Error|open|#Errors}} drops the addressed database does not exist or could not be opened.<br/>{{Error|mainmem|#Errors}} the database is not ''persistent'' (stored on disk).|-| '''Examples'''|* {{Code|db:put-binary('DB', file:read-binary('video.mov'), 'video/sample.mov')}} stores the addressed video file at the specified location.* With the following query, you can copy the binary resources of one database into another:<syntaxhighlight lang="xquery">let $db := 'db'let $src-path := 'src/'let $trg-path := 'trg/'for $src in db:list($db, $src-path)where db:type($db, $src) = 'binary'let $trg := $trg-path || substring-after($src, $src-path)return db:put-binary($db, db:get-binary($db, $src), $trg)</syntaxhighlight>|} ==db:flush== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|db:flush|$db as xs:string|empty-sequence()}}|-| '''Summary'''|Explicitly flushes the buffers of the database {{Code|$db}}. This command is only useful if {{Option|AUTOFLUSH}} has been set to {{Code|false}}.|-| '''Errors'''|{{Error|open|#Errors}} the addressed database does not exist or could not be opened.

* Updated: {{Function||db:replaceget}}, {{Function||db:get-id}}, {{Function||db:get-pre}} renamed (before: {{Code|db:open}}, {{Code|db:open-id}}, {{Code|db:open-pre}} and )* Updated: {{Function||db:put-binary}} renamed (before: {{Code|db:replace}} ); function signature aligned with {{Function||db:add}} (second and third argument swapped).* Updated: {{Function||db:put-binary}} renamed (before: {{Code|db:store}}); function signature aligned with {{Function||db:add}} (second and third argument swapped).

* DeletesRemoved: {{Code|db:is-raw}}, {{Code|db:is-raw}} (new: {{Function||db:type}}).

* Updated: {{Function|Code|db:open-id}}, {{Function|Code|db:open-pre}}: support for multiple integers

* Updated: {{Function||db:list}}, {{Function|Code|db:open}}, {{Function||db:add}}