Changes

This [[Module Library|XQuery Module]] contains functions for processing databases from within XQuery. Existing databases can be opened and listed, its contents can be directly accessed, documents can be added to and removed, etc. All functions are introduced with the {{MonoCode|db:}} prefix, which is linked to the statically declared {{MonoCode|http://basex.org/modules/db}} namespace.

Many function signatures in this and other modules share {{MonoCode|$db}} as argument to reference an existing database. The argument may either be a string, denoting the name of the addressed database, or a single node from an already opened database. The following errors may be raised by these functions:

* '''[[#Errors|BXDB0001]]''' is raised if {{MonoCode|$db}} references an XML node that is not stored in a database, or is no database fragment.

|{{MonoCode|'''db:info'''($db as item()) as element(Database)}}

|{{MonoCode|'''db:list'''() as xs:string*}}<br/>{{MonoCode|'''db:list'''($db as item()) as xs:string*}}<br/>{{MonoCode|'''db:list'''($db as item(), $path as xs:string) as xs:string*}}

|Returns an {{MonoCode|xs:string}} sequence with the names of all databases.<br/>If <code>[[#Database Nodes|$db]]</code> is specified, all documents and raw files of the specified database are returned.<br/>The list of resources can be further restricted by the {{MonoCode|$path}} argument.

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

|{{MonoCode|'''db:list-details'''() as element(database)*}}<br/>{{MonoCode|'''db:list-details'''($db as item()) as element(resource)*}}<br/>{{MonoCode|'''db:list-details'''($db as item(), $path as xs:string) as element(resource)*}}

|Returns an {{MonoCode|element}} sequence with the names of all databases together with their database path, the number of stored resources and the date of modification.<br/>If <code>[[#Database Nodes|$db]]</code> is specified, all documents and raw files of the specified database together with their content-type, the modification date and the resource type are returned.<br/>The list of resources can be further restricted by the {{MonoCode|$path}} argument.

* {{MonoCode|db:list-details("docs")}} returns the names plus additional data of all documents from the database named {{MonoCode|docs}}.

|{{MonoCode|'''db:open'''($db as item()) as document-node()*}}<br />{{MonoCode|'''db:open'''($db as item(), $path as xs:string) as document-node()*}}

|Returns a sequence with all document nodes contained in the database specified by <code>[[#Database Nodes|$db]]</code>.<br/>The document nodes to be returned can be restricted by the {{MonoCode|$path}} argument.

* {{MonoCode|db:open("docs")}} returns all documents from the database named {{MonoCode|docs}}.* {{MonoCode|db:open("docs", "one")}} returns all documents from the database named {{MonoCode|docs}} in the subpath {{MonoCode|one}}.

|{{MonoCode|'''db:open-id'''($db as item(), $id as xs:integer) as node()}}

|Opens the database specified by <code>[[#Database Nodes|$db]]</code> and returns the node with the specified {{MonoCode|$id}} value.<br />Each database node has a persistent ''id'', which remains valid after update operations. If no updates are performed, the ''pre'' value can be requested, which provides access to database nodes in constant time.

|{{MonoCode|'''db:open-pre'''($db as item(), $pre as xs:integer) as node()}}

|Opens the database specified by <code>[[#Database Nodes|$db]]</code> and returns the node with the specified {{MonoCode|$pre}} value.<br />The ''pre'' value provides access to a database node in constant time, but it is ''transient'', i.e., it may change when database updates are performed.

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

|{{MonoCode|'''db:system'''() as element(system)}}

|{{MonoCode|'''db:attribute'''($db as item(), $string as item()) as attribute()*}}<br/>{{MonoCode|'''db:attribute'''($db as item(), $string as item(), $attname as xs:string) as attribute()*}}

|Returns all attribute nodes of the database specified by <code>[[#Database Nodes|$db]]</code> that have {{MonoCode|$string}} as string value. If available, the value index is used to speed up evaluation.<br />If {{MonoCode|$attname}} is specified, the resulting attribute nodes are filtered by their attribute name.

* {{MonoCode|db:attribute("DB", "QUERY", "id")/..}} returns the parents of all {{MonoCode|id}} attribute nodes of the database {{MonoCode|DB}} that have {{MonoCode|QUERY}} as string value.

|{{MonoCode|'''db:attribute-range'''($db as item(), $min as xs:string, $max as xs:string) as text()*}}<br/>{{MonoCode|'''db:attribute-range'''($db as item(), $min as xs:string, $max as xs:string, $attname as xs:string) as attribute()*}}

|Returns all attributes of the database specified by <code>[[#Database Nodes|$db]]</code>, the string values of which are larger than or equal to {{MonoCode|$min}} and smaller than or equal to {{MonoCode|$max}}. If available, the value index is used to speed up evaluation.

* {{MonoCode|db:attribute-range("DB", "id456", "id473", 'id')}} returns all {{MonoCode|@id}} attributes of the database {{MonoCode|DB}} that have a string value in between {{MonoCode|id456}} and {{MonoCode|id473}}.

|{{MonoCode|'''db:fulltext'''($db as item(), $terms as xs:string) as text()*}}

|Returns all text nodes from the full-text index of the database specified by <code>[[#Database Nodes|$db]]</code> that contain the text specified as {{MonoCode|$terms}}.<br/>The options used for building the full-text will also be applied to the search terms. As an example, if the index terms have been stemmed, the search string will be stemmed as well.

* {{MonoCode|db:fulltext("DB", "QUERY")}} returns all text nodes of the database {{MonoCode|DB}} that contain the string {{MonoCode|QUERY}}.

|{{MonoCode|'''db:node-id'''($nodes as node()*) as xs:integer*}}

|Returns the ''id'' values of all {{MonoCode|$nodes}} of the database specified by <code>[[#Database Nodes|$db]]</code>.<br/>Each database node has a persistent ''id'', which remains valid after update operations. If no updates are performed, the ''pre'' value can be requested, which provides access to database nodes in constant time.

|{{MonoCode|'''db:node-pre'''($nodes as node()*) as xs:integer*}}

|Returns the ''pre'' values of all {{MonoCode|$nodes}} of the database specified by <code>[[#Database Nodes|$db]]</code>.<br/>The ''pre'' value provides access to a database node in constant time, but it is ''transient'', i.e., it may change when database updates are performed.

* {{MonoCode|db:node-pre(doc("input"))}} returns {{MonoCode|0}} if the database {{MonoCode|input}} contains a single document.

|{{MonoCode|'''db:retrieve'''($db as item(), $path as xs:string) as xs:base64Binary}}

|Returns a binary database resource addressed by <code>[[#Database Nodes|$db]]</code> and {{MonoCode|$path}}.

* {{MonoCode|declare option output:method 'raw';<br/>db:retrieve("DB", "music/01.mp3")}} returns the specified audio file as raw data.

|{{MonoCode|'''db:text'''($db as item(), $string as item()) as text()*}}

|Returns all text nodes of the database specified by <code>[[#Database Nodes|$db]]</code> that have {{MonoCode|$string}} as their string value. If available, the value index is used to speed up evaluation.

* {{MonoCode|db:text("DB", "QUERY")/..}} returns the parents of all text nodes of the database {{MonoCode|DB}} that match the string {{MonoCode|QUERY}}.

|{{MonoCode|'''db:text-range'''($db as item(), $min as xs:string, $max as xs:string) as text()*}}

|Returns all text nodes of the database specified by <code>[[#Database Nodes|$db]]</code> that are located in between the {{MonoCode|$min}} and {{MonoCode|$max}} strings. If available, the value index is used to speed up evaluation.

* {{MonoCode|db:text-range("DB", "2000", "2001")}} returns all text nodes of the database {{MonoCode|DB}} that are found in between {{MonoCode|2000}} and {{MonoCode|2001}}.

|{{MonoCode|'''db:add'''($db as item(), $input as item()) as empty-sequence()}}<br/>{{MonoCode|'''db:add'''($db as item(), $input as item(), $path as xs:string) as empty-sequence()}}

|Adds documents specified by {{MonoCode|$input}} to the database <code>[[#Database Nodes|$db]]</code> and the specified {{MonoCode|$path}}.

|'''[[XQuery Errors#Functions Errors|FODC0002]]''' is raised if {{MonoCode|$input}} is a string representing a path, which cannot be read.<br/>'''[[XQuery Errors#Update Errors|FOUP0001]]''' is raised if {{MonoCode|$input}} is neither string nor a document node.

* {{MonoCode|db:add("DB", "/home/dir/doc.xml")}} adds the file {{MonoCode|/home/dir/doc.xml}} to the database {{MonoCode|DB}}.* {{MonoCode|db:add("DB", "<a/>", "doc.xml")}} adds a document with content {{MonoCode|&lt;a/&gt;}} to the database {{MonoCode|DB}} under the name {{MonoCode|doc.xml}}.* {{MonoCode|db:add("DB", document { <a/> }, "doc.xml")}} adds the document node to the database {{MonoCode|DB}} under the name {{MonoCode|doc.xml}}.* {{MonoCode|db:add("DB", "/home/dir", "docs/dir")}} adds all documents in {{MonoCode|/home/dir}} to the database {{MonoCode|DB}} under the path {{MonoCode|docs/dir}}.

|{{MonoCode|'''db:delete'''($db as item(), $path as xs:string) as empty-sequence()}}

|Deletes document(s), specified by {{MonoCode|$path}}, from the database <code>[[#Database Nodes|$db]]</code>.

* {{MonoCode|db:delete("DB", "docs/dir/doc.xml")}} deletes the document {{MonoCode|docs/dir/doc.xml}} in the database {{MonoCode|DB}}.* {{MonoCode|db:delete("DB", "docs/dir")}} deletes all documents with paths beginning with {{MonoCode|docs/dir}} in the database {{MonoCode|DB}}.

|{{MonoCode|'''db:optimize'''($db as item()) as empty-sequence()}}<br/>{{MonoCode|'''db:optimize'''($db as item(), $all as xs:boolean) as empty-sequence()}}

|Optimizes the meta data and indexes of the database <code>[[#Database Nodes|$db]]</code>.<br/>If {{MonoCode|$all}} is set to {{MonoCode|true()}}, the complete database will be rebuilt.

|'''[[XQuery Errors#BaseX Errors|BASX0014]]''' is raised if an error occurs during optimizing the data structures.<br/>'''[[XQuery Errors#BaseX Errors|BASX0015]]''' is raised if the {{MonoCode|$all}} flag is set to {{MonoCode|true()}}, but the database is an in-memory database.<br/>'''[[XQuery Errors#BaseX Errors|BASX0016]]''' is raised if the database {{MonoCode|$db}} is in use by other user(s).

* {{MonoCode|db:optimize("DB")}} optimizes the database structures of the database {{MonoCode|DB}}.* {{MonoCode|db:optimize("DB", true())}} optimizes all database structures of the database {{MonoCode|DB}}.

|{{MonoCode|'''db:rename'''($db as item(), $path as xs:string, $newpath as xs:string) as empty-sequence()}}

|Renames document(s), specified by {{MonoCode|$path}} to {{MonoCode|$newpath}} in the database <code>[[#Database Nodes|$db]]</code>.

* {{MonoCode|db:rename("DB", "docs/dir/doc.xml", "docs/dir/newdoc.xml")}} renames the document {{MonoCode|docs/dir/doc.xml}} to {{MonoCode|docs/dir/newdoc.xml}} in the database {{MonoCode|DB}}.* {{MonoCode|db:rename("DB", "docs/dir", "docs/newdir")}} renames all documents with paths beginning with {{MonoCode|docs/dir}} to paths beginning with {{MonoCode|docs/newdir}} in the database {{MonoCode|DB}}.

|{{MonoCode|'''db:replace'''($db as item(), $path as xs:string, $input as item()) as empty-sequence()}}

|Replaces a document, specified by {{MonoCode|$path}}, in the database <code>[[#Database Nodes|$db]]</code> with the content of {{MonoCode|$input}}.

|'''[[#Errors|BXDB0006]]''' is raised if {{MonoCode|$path}} is not a single document path.<br/>'''[[XQuery Errors#Functions Errors|FODC0002]]''' is raised if {{MonoCode|$input}} is a string representing a path, which cannot be read.<br/>'''[[XQuery Errors#Update Errors|FOUP0001]]''' is raised if {{MonoCode|$input}} is neither a string nor a document node.

* {{MonoCode|db:replace("DB", "docs/dir/doc.xml", "/home/dir/doc.xml")}} replaces the content of the document {{MonoCode|docs/dir/doc.xml}} in the database {{MonoCode|DB}} with the content of the file {{MonoCode|/home/dir/doc.xml}}.* {{MonoCode|db:replace("DB", "docs/dir/doc.xml", "<a/>")}} replaces the content of the document {{MonoCode|docs/dir/doc.xml}} in the database {{MonoCode|DB}} with {{MonoCode|&lt;a/&gt;}}.* {{MonoCode|db:replace("DB", "docs/dir/doc.xml", document { <a/> })}} replaces the content of the document {{MonoCode|docs/dir/doc.xml}} in the database {{MonoCode|DB}} with the specified document node.

|{{MonoCode|'''db:store'''($db as item(), $path as xs:string, $data as item()) as empty-sequence()}}

|Stores a binary resource specified by {{MonoCode|$data}} in the database specified by <code>[[#Database Nodes|$db]]</code> and the location specified by {{MonoCode|$path}}.

* {{MonoCode|db:store("DB", "video/sample.mov", file:read-binary('video.mov'))}} stores the addressed video file at the specified location.

|{{MonoCode|'''db:output'''($data as item()*) as empty-sequence()}}

* {{MonoCode|db:output("Prices have been deleted."), delete node //price}} deletes all {{MonoCode|price}} elements in a database and returns an info message.

|{{MonoCode|'''db:exists'''($db as item()) as xs:boolean}}<br/>{{MonoCode|'''db:exists'''($db as item(), $path as xs:string) as xs:boolean}}

|Checks if the database specified by <code>[[#Database Nodes|$db]]</code> or the resource specified by {[Mono|$path}} exists. {{MonoCode|false}} is returned if a database directory has been addressed.

* {{MonoCode|db:exists("DB")}} returns {{MonoCode|true}} if the database {{MonoCode|DB}} exists.* {{MonoCode|db:exists("DB", "resource")}} returns {{MonoCode|true}} if {{MonoCode|resource}} is an XML document or a raw file.

|{{MonoCode|'''db:is-raw'''($db as item(), $path as xs:string) as xs:boolean}}

|Checks if the specified resource in the database <code>[[#Database Nodes|$db]]</code> and the path {{MonoCode|$path}} exists, and if it is a raw file.

* {{MonoCode|db:is-raw("DB", "music/01.mp3")}} returns {{MonoCode|true}}.

|{{MonoCode|'''db:is-xml'''($db as item(), $path as xs:string) as xs:boolean}}

|Checks if the specified resource in the database <code>[[#Database Nodes|$db]]</code> and the path {{MonoCode|$path}} exists, and if it is an XML document.

* {{MonoCode|db:is-xml("DB", "dir/doc.xml")}} returns {{MonoCode|true}}.

|{{MonoCode|'''db:content-type'''($db as item(), $path as xs:string) as xs:string}}

|Retrieves the content type of a resource in the database <code>[[#Database Nodes|$db]]</code> and the path {{MonoCode|$path}}.<br/>The file extension is used to recognize the content-type of a resource stored in the database. Content-type {{MonoCode|application/xml}} will be returned for any XML document stored in the database, regardless of its file name extension.

* {{MonoCode|db:content-type("DB", "docs/doc01.pdf")}} returns {{MonoCode|application/pdf}}.* {{MonoCode|db:content-type("DB", "docs/doc01.xml")}} returns {{MonoCode|application/xml}}.* {{MonoCode|db:content-type("DB", "docs/doc01")}} returns {{MonoCode|application/xml}}, if {{MonoCode|db:is-xml("DB", "docs/doc01")}} returns {{MonoCode|true}}.

|{{MonoCode|'''db:event'''($name as xs:string, $query as item()) as empty-sequence()}}

|Executes a {{MonoCode|$query}} and sends the resulting value to all clients watching the [[Events|Event]] with the specified {{MonoCode|$name}}. The query may also perform updates; no event will be sent to the client that fired the event.

|A database path addressed with {{MonoCode|doc()}} contains more than one document.