Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
{{Mark|Updated with Version 9.0:}}
Database In BaseX, two internal representations exist for nodes . * XML fragments are XML generated by XQuery node constructors.* Database nodes which are either :** stored in a persistent databaseon disk;** nodes of a document that has been generated temporarily with {{Code|fn:doc}}, or which contained in {{Code|fn:parse-xml}} and other functions;** result of a somain-called ''memory update operation. Some operations are restricted to database fragment''. All nodes, but you can convert XML fragments can be converted to database fragments nodes by e. g. applying the an empty [[XQuery_Update#update|update]] or [[XQuery_Update#transform|transform]] expression on operation to a node. Two examples: * Retrieve the internal node id of an XML fragment: <syntaxhighlight lang="xquery">let $xml := <xml>hello world</xml> update {}return db:node-id($xml/text())</syntaxhighlight> * Puts a marker element around the result of a full-text request (see {{Function|Full-Text|ft:mark}} for more details):
{{Mark|Introduced with Version 9.0:}}
{{Mark|Updated with Version 9.0:}}
→db:export
=Conventions=
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/>
==Database Nodes==
<pre classsyntaxhighlight lang="brush:xquery">copy $c p := element <xml>hello { 'world' } </xml>modify () return ft:mark($cp[text() contains text 'word'], 'b')</presyntaxhighlight>
=General Functions=
|-
| '''Summary'''
|Returns general information on the database system the current values of all global and local [[Options]]. The [[Commands#INFO{{Command|INFO]] }} command returns similar output.
|}
==db:option==
{| width='100%'
|-
| '''Summary'''
|Returns the current value (string, integer, boolean, map) of a global or local [[Options|Option]] with the specified {{Code|$name}}. The [[Commands#GET{{Command|GET]] }} command works similar.|-| '''Errors'''|{{Error|option|#Errors}} the specified option is unknown.
|-
| '''Examples'''
|-
| '''Summary'''
|Returns meta information on the database {{Code|$db}}. The output is similar to the [[Commands#INFO DB{{Command|INFO DB]] }} command.
|-
| '''Errors'''
|-
| 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'''
|
* {{Code|db:list-details("shop")}} returns the names plus additional info on all resources of a database named {{Code|shop}}.
|}
==db:dir==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:dir|$db as xs:string, $path as xs:string|element()*}}
|-
| '''Summary'''
|Returns meta data on all directories and resources of the database {{Code|$db}} in the specified directory {{Code|$path}}. Two types of elements are returned:
* {{Code|resource}} represents a resource. The element value is the directory path; content type, modification date, raw flag (which indicates if the resource is binary or XML), and size of the resource are returned as attributes.
* {{Code|dir}} represents a directory. The element value is the directory path; the modification date is returned as attribute.
Please note that directories are not stored in BaseX. Instead, they result implicitly from the paths of stored resources.
|-
| '''Errors'''
|{{Error|open|#Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|path|#Errors}} the specified path is invalid.
|-
| '''Examples'''
|
* {{Code|db:dir('shop', 'books')}} returns all entries of the {{Code|books}} directory of a {{Code|shop}} database.
|}
|-
| width='120' | '''Signatures'''
|{{Func|db:open-pre|$db as xs:string, $pre pres as xs:integer*|node()*}}
|-
| '''Summary'''
|Opens the database {{Code|$db}} and returns the node all distinct nodes with the specified pre values {{Code|$prepres}} valuein document order.<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.
|-
| '''Errors'''
|-
| width='120' | '''Signatures'''
|{{Func|db:open-id|$db as xs:string, $id ids as xs:integer*|node()*}}
|-
| '''Summary'''
|Opens the database {{Code|$db}} and returns the node all distinct nodes with the specified {{Code|$idids}} valuein document order.<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 {{Option|UPDINDEX}} option.
|-
| '''Errors'''
|-
| '''Summary'''
|Returns the ''pre'' values of the nodes supplied by specified {{Code|$nodes}}, 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.
|-
| '''Errors'''
|-
| '''Summary'''
|Returns the ''id'' values of the nodes supplied by specified {{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 {{Option|UPDINDEX}} option.
|-
| '''Errors'''
|-
| '''Summary'''
|Exports the specified database {{Code|$db}} to the specified file {{Code|$path}}. Existing files will be overwritten. <br />The {{Code|$params}} argument contains serialization parameters (see [[Serialization|serialization parameters]] for more details. As with [https://www.w3.org/TR/xpath-functions-31/#func-serialize fn:serialize()], which the parameters can either be specified<br />* either as children of an {{Code|<output:serialization-parameters/>}} element, as defined for the [http://www.w3.org/TR/xpath-functions-30/#func-serialize fn:serialize()] function; e.g.:<pre classsyntaxhighlight lang="brush:xml">
<output:serialization-parameters>
<output:method value='xml'/>
...
</output:serialization-parameters>
</presyntaxhighlight>* or as map, which contains all key/value pairs:<pre classsyntaxhighlight lang="brush:xmlxquery">
map { "method": "xml", "cdata-section-elements": "div", ... }
</presyntaxhighlight>
|-
| '''Errors'''
| '''Examples'''
| Export all files as text:<br/>
<pre classsyntaxhighlight lang="brush:xquery">
db:export("DB", "/home/john/xml/texts", map { 'method': 'text' })
</presyntaxhighlight>
The following query can be used to export parts of the database:
<pre classsyntaxhighlight lang="brush:xquery">
let $target := '/home/john/xml/target'
for $doc in db:open('DB', 'collection')
file:write($path, $doc)
)
</presyntaxhighlight>
|}
|-
| width='120' | '''Signatures'''
|{{Func|db:text|$db as xs:string, $strings as xs:string as item()*|text()*}}
|-
| '''Summary'''
|Returns all text nodes of the database {{Code|$db}} that have one of the specified {{Code|$stringstrings}} as their string value values and that are stored in the text index.
|-
| '''Errors'''
|-
| '''Summary'''
|Returns all text nodes of the database {{Code|$db}} that whose values are located in between the {{Code|$min}} and {{Code|$max}} strings and that are stored in the text index.
|-
| '''Errors'''
|-
| width='120' | '''Signatures'''
|{{Func|db:attribute|$db as xs:string, $strings as xs:string as item()*|attribute()*}}<br/>{{Func|db:attribute|$db as xs:string, $strings as xs:string as item()*, $name as xs:string|attribute()*}}
|-
| '''Summary'''
|Returns all attribute nodes of the database {{Code|$db}} that have one of the specified {{Code|$stringstrings}} as string value values and that are stored in the attribute index.<br />If {{Code|$name}} is specified, the resulting attribute nodes are filtered by their attribute name.
|-
| '''Errors'''
|-
| width='120' | '''Signatures'''
|{{Func|db:token|$db as xs:string, $token tokens as item()xs:string*|attribute()*}}<br/>{{Func|db:token|$db as xs:string, $token tokens as item()xs:string*, $name as xs:string|attribute()*}}
|-
| '''Summary'''
|Returns all attribute nodes of the database {{Code|$db}}, the value values of which contains contain one of the specified {{Code|$tokentokens}}.<br />If {{Code|$name}} is specified, the resulting attribute nodes are filtered by their attribute name.
|-
| '''Errors'''
|-
| 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.
* See [[#db:create|db:create]] for more details on the input argumentand 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 in lower case
* {{Code|db:drop-backup("DB")}} drops all backups of the database {{Code|DB}}.
* {{Code|db:drop-backup("DB-2014-03-13-17-36-44")}} drops the specific backup file {{Code|DB-2014-03-13-17-36-44.zip}} of the database {{Code|DB}}.
|}
==db:alter-backup==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:alter-backup|$name as xs:string, $new-name as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Renames all backups of the database with the specified {{Code|$name}} to {{Code|$new-name}}. The directory inside the archive will be renamed as well. If the given {{Code|$name}} points to a specific backup file, only this specific backup file will be renamed.
|-
| '''Errors'''
|{{Error|backup|#Errors}} No backup file found.<br/>{{Error|name|#Errors}} invalid database name.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.
|-
| '''Examples'''
|
* {{Code|db:alter-backup("DB", "DB2)}} renames all backups of the database {{Code|DB}} to {{Code|DB2}}.
|}
* {{Code|db:replace("DB", "docs/dir/doc.xml", document { <a/> })}} 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:
<pre classsyntaxhighlight lang="brush:xquery">
let $source := '/home/john/xml/source'
for $file in file:list($source, true())
where not(file:is-dir($path))
return db:replace('db', $file, doc($path))
</presyntaxhighlight>
|}
* {{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 classsyntaxhighlight lang="brush:xquery">
let $db := 'db'
let $src-path := 'src/'
let $trg := $trg-path || substring-after($src, $src-path)
return db:store($db, $trg, db:retrieve($db, $src))
</presyntaxhighlight>
|}
=Errors=
{| class="wikitable" width="100%"
|{{Code|open}}
|The addressed database does not exist or could not be opened.
|-
|{{Code|option}}
|The specified option is unknown.
|-
|{{Code|path}}
|-
|{{Code|property}}
|A The specified database property is unknown.
|-
|{{Code|range}}
=Changelog=
;Version 9.3
* Added: [[#db:alter-backup|db:alter-backup]]
* Updated: [[#db:open-id|db:open-id]], [[#db:open-pre|db:open-pre]]: support for multiple integers
;Version 9.2
* Added: [[#db:dir|db:dir]]
* Updated: [[#db:add|db:add]]: {{Code|$path}} allow empty path argument
;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)
;Version 7.7
* Added: [[#db:export|db:export]], [[#db:name|db:name]], [[#db:path|db:path]]
* Updated: {{Code|$options}} argument added to [[#db:create|db:create]] and [[#db:optimize|db:optimize]].
;Version 7.6
* Updated: [[#db:create|db:create]]: allow more than one input and path.
;Version 7.5
* Updated: [[#db:add|db:add]]: input nodes will be automatically converted to document nodes
* Added: [[#db:backups|db:backups]]
;Version 7.3
* Added: [[#db:flush|db:flush]]
;Version 7.2.1
* Added: [[#db:text-range|db:text-range]], [[#db:attribute-range|db:attribute-range]], [[#db:output|db:output]]
;Version 7.1
* Added: [[#db:list-details|db:list-details]], [[#db:content-type|db:content-type]]
* Updated: [[#db:info|db:info]], [[#db:system|db:system]], [[#db:retrieve|db:retrieve]]
;Version 7.0
* 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]]
