All functions and errors in this module are assigned to the http://basex.org/modules/db
namespace, which is statically bound to the db
prefix.
Database Nodes
In BaseX, two internal representations exist for nodes.
- XML fragments are generated by XQuery node constructors.db:b
- Database nodes are:
- stored in a persistent database on disk;
- nodes of a document that has been generated temporarily with
fn:doc
, fn:parse-xml
and other functions; or
- result of a main-memory update operation.
Some operations are restricted to database nodes, but you can convert XML fragments to database nodes by applying an empty update or transform 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
ft:mark
for more details):
<syntaxhighlight lang="xquery">
copy $p := <xml>hello world</xml>
modify ()
return ft:mark($p[text() contains text 'word'], 'b')
</syntaxhighlight>
Updating Functions
Various functions in this module are updating. Updating functions will not be immediately executed, but queued on the Pending Update List, and processed after the remaining query has been evaluated. This means that the order in which the functions are specified in the query often does not reflect the order in which they will eventually be executed.
All functions in this section are updating functions.
db:create
Signatures
|
db:create($db as xs:string) as empty-sequence()
db:create($db as xs:string, $inputs as item()*) as empty-sequence()
db:create($db as xs:string, $inputs as item()*, $paths as xs:string*) as empty-sequence()
db:create($db as xs:string, $inputs as item()*, $paths as xs:string*, $options as map(*)?) as empty-sequence()
|
Summary
|
Creates a new database with name $db and adds initial documents specified via $inputs to the specified $paths :
$inputs may be strings or nodes:
- nodes may be of any type except for attributes
- strings can be a URI pointing to a file/directory or an XML string (which is detected by the leading
< 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
$options :
- An existing database will be overwritten.
- Database creation takes place after most other update operations (see Pending Update List). As a consequence, a newly created database cannot be addressed in the same query.
|
Errors
|
lock : a database is opened by another process.
name : the specified name is not a valid database name.
conflict : the same database was addressed more than once.
args : the number of specified inputs and paths differs.
|
Examples
|
db:create("DB") creates the empty database DB .
db:create("DB", "/home/dir/doc.xml") creates the database DB and adds the document /home/dir/doc.xml as initial content.
db:create("DB", <a/>, "doc.xml") creates the database DB and adds the document with content <a/> under the name doc.xml .
db:create("DB", "/home/dir/", "docs/dir") creates the database DB and adds the documents in /home/dir to the database under the path docs/dir .
db:create("DB", file:list('.'), (), map { 'ftindex': true() }) adds all files of the current working directory to a new database, preserving relative filesystem paths and creating a full-text index.
|
db:drop
Signatures
|
db:drop($db as xs:string) as empty-sequence()
|
Summary
|
Drops the database $db and all connected resources.
|
Errors
|
open : the addressed database does not exist or could not be opened.
lock : a database is opened by another process.
conflict : the same database was addressed more than once.
|
Examples
|
db:drop("DB") drops the database DB .
|
db:add
Signatures
|
db:add($db as xs:string, $input as item()) as empty-sequence()
db:add($db as xs:string, $input as item(), $path as xs:string?) as empty-sequence()
db:add($db as xs:string, $input as item(), $path as xs:string?, $options as map(*)?) as empty-sequence()
|
Summary
|
Adds documents specified by $input to the database $db with the specified $path :
- A document with the same path may occur more than once in a database. If you want to enforce single instances, use db:update instead.
- See db:create for more details on the input and path arguments.
- The parsing behavior can be controlled via
$options :
- allowed options are
ADDCACHE and the parsing and XML parsing options, all in lower case
- parsing options will only impact string input (URIs, XML strings), because nodes have already been parsed
|
Errors
|
open : the addressed database does not exist or could not be opened.
|
Examples
|
db:add("DB", "/home/dir/doc.xml") adds the file /home/dir/doc.xml to the database DB .
db:add("DB", <a/>, "doc.xml") adds a document node to the database DB under the name doc.xml .
db:add("DB", "/home/dir", "docs/dir", map { 'addcache': true() }) adds all documents in /home/dir to the database DB under the path docs/dir . In order to reduce memory consumption, the files will be cached before being added to the database.
|
db:delete
Signatures
|
db:delete($db as xs:string, $path as xs:string) as empty-sequence()
|
Summary
|
Deletes resource(s), specified by $path , from the database $db .
|
Errors
|
open : the addressed database does not exist or could not be opened.
path : the specified path is invalid.
|
Examples
|
db:delete("DB", "docs/dir/doc.xml") deletes the resource docs/dir/doc.xml from DB .
db:delete("DB", "docs/dir") deletes all resources from DB in the specified path docs/dir .
|
db:copy
Signatures
|
db:copy($db as xs:string, $name as xs:string) as empty-sequence()
|
Summary
|
Creates a copy of the database $db , which will be called $name .
|
Errors
|
open : the addressed database does not exist or could not be opened.
lock : a database is opened by another process.
name : invalid database name.
conflict : the same database was addressed more than once.
|
db:alter
Signatures
|
db:alter($db as xs:string, $name as xs:string) as empty-sequence()
|
Summary
|
Renames the database $db to $name .
|
Errors
|
open : the addressed database does not exist or could not be opened.
lock : a database is opened by another process.
name : invalid database name.
conflict : the same database was addressed more than once.
|
db:optimize
Signatures
|
db:optimize($db as xs:string) as empty-sequence()
db:optimize($db as xs:string, $all as xs:boolean) as empty-sequence()
db:optimize($db as xs:string, $all as xs:boolean, $options as map(*)?) as empty-sequence()
|
Summary
|
Optimizes the meta data and indexes of the database $db . If $all is true , the complete database will be rebuilt. The $options argument can be used to control indexing. The syntax is identical to the db:create function: Allowed options are all indexing and full-text options. UPDINDEX is only supported if $all is true .
|
Errors
|
open : the addressed database does not exist or could not be opened.
|
Examples
|
db:optimize("DB") optimizes the database structures of the database DB .
db:optimize("DB", true(), map { 'ftindex': true() }) optimizes all database structures of the database DB and creates a full-text index.
|
db:rename
Signatures
|
db:rename($db as xs:string, $source as xs:string, $target as xs:string) as empty-sequence()
|
Summary
|
Moves all resources(s) of database $db , which are found in the supplied $source path, to the supplied $target path. The paths may point to single resources or directories. No updates will take place if a non-existing source path is supplied.
|
Errors
|
open : the addressed database does not exist or could not be opened.
path : the specified source or target path, or one of its descendants, is invalid.
|
Examples
|
db:rename("DB", "docs/dir/doc.xml", "docs/dir/newdoc.xml") renames the resource docs/dir/doc.xml to docs/dir/newdoc.xml in the database DB .
db:rename("DB", "docs/dir", "docs/newdir") moves all resources in the database DB from docs/dir to {Code|docs/newdir}}.
|
db:update
Updated with Version 10: renamed (before: db:replace
); function signature aligned with db:add
(second and third argument swapped).
Signatures
|
db:update($db as xs:string, $input as item(), $path as xs:string) as empty-sequence()
db:update($db as xs:string, $input as item(), $path as xs:string, $options as map(*)?) as empty-sequence()
|
Summary
|
Replaces a resource, specified by $path , in the database $db with the contents of $input , or adds it as a new resource:
- The parsing behavior can be controlled via
$options :
- Allowed options are
ADDCACHE and the parsing and XML parsing options, all in lower case.
- Parsing options will only impact string input (URIs, XML strings), because nodes have already been parsed.
- See db:create for more details on the input argument.
|
Errors
|
open : the addressed database does not exist or could not be opened.
target : the path points to a directory.
|
Examples
|
db:update("DB", "/home/dir/doc.xml", "docs/dir/doc.xml") replaces the content of the document docs/dir/doc.xml in the database DB with the content of the file /home/dir/doc.xml .
db:update("DB", "<a/>", "docs/dir/doc.xml") replaces the content of the document docs/dir/doc.xml in the database DB with <a/> .
db:update("DB", document { <a/> }, "docs/dir/doc.xml") replaces the content of the document docs/dir/doc.xml in the database 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 || $file
where not(file:is-dir($path))
return db:replace('db', doc($path), $file)
</syntaxhighlight>
|
db:store
Signatures
|
db:store($db as xs:string, $path as xs:string, $input as item()) as empty-sequence()
|
Summary
|
Replaces a binary resource specified by $input in the database $db and the location specified by $path , or adds it as new resource.
|
Errors
|
open : the addressed database does not exist or could not be opened.
mainmem : the database is not persistent (stored on disk).
|
Examples
|
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:
<syntaxhighlight lang="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))
</syntaxhighlight>
|
db:flush
Signatures
|
db:flush($db as xs:string) as empty-sequence()
|
Summary
|
Explicitly flushes the buffers of the database $db . This command is only useful if AUTOFLUSH has been set to false .
|
Errors
|
open : the addressed database does not exist or could not be opened.
|
Introduced with Version 10: Support for general data (registered users, scheduled services and key-value stores).
All functions in this section except for db:backups
are updating functions.
db:create-backup
Updated with Version 10: Options argument added.
Signatures
|
db:create-backup($db as xs:string) as empty-sequence()
db:create-backup($db as xs:string, $options as map(*)) as empty-sequence()
|
Summary
|
Creates a backup of the database $db . If no name is supplied, general data will be backed up. The following $options are available:
- With
comment , a comment string can be attached to the backup.
- By setting
compress to false, the backup will be created faster, but it will take more space on disk.
|
Errors
|
open : the addressed database does not exist or could not be opened.
name : invalid database name.
conflict : the same database was addressed more than once.
|
Examples
|
db:create-backup('DB', map { 'compress': false() }) creates a backup of the database DB without compressing its entries.
|
db:drop-backup
Signatures
|
db:drop-backup($name as xs:string) as empty-sequence()
|
Summary
|
Drops all backups of the database with the specified $name . If the name ends with a timestamp, only the specified backup file will be deleted. If no name is supplied, backups with general data are addressed.
|
Errors
|
backup : No backup file found.
name : invalid database name.
conflict : the same database was addressed more than once.
|
Examples
|
db:drop-backup("DB") drops all backups of the database DB .
db:drop-backup("DB-2014-03-13-17-36-44") drops the specific backup file DB-2014-03-13-17-36-44.zip of the database DB .
|
db:alter-backup
Signatures
|
db:alter-backup($name as xs:string, $new-name as xs:string) as empty-sequence()
|
Summary
|
Renames all backups of the database with the specified $name to $new-name . If the name ends with a date, only the specified backup file will be renamed.
|
Errors
|
backup : No backup file found.
name : invalid database name.
conflict : the same database was addressed more than once.
|
Examples
|
db:alter-backup("DB", "DB2) renames all backups of the database DB to DB2 .
|
db:restore
Signatures
|
db:restore($name as xs:string) as empty-sequence()
|
Summary
|
Restores the database with the specified $name . The $name may include the timestamp of the backup file. If no name is supplied, general data will be restored. If general data is restored, it will only be available after BaseX has been restarted.
|
Errors
|
lock : a database is opened by another process.
name : invalid database name.
no-backup : No backup found.
conflict : the same database was addressed more than once.
|
Examples
|
db:restore("DB") restores the database DB .
db:restore("DB-2014-03-13-18-05-45") restores the database DB from the backup file with the given timestamp.
|
db:backups
Signatures
|
db:backups() as element(backup)*
db:backups($db as xs:string) as element(backup)*
|
Summary
|
Returns an element sequence containing all available database backups with timestamp, file size and comment. If a database $db is specified, the sequence will be restricted to the backups matching this database.
|
Examples
|
db:backups("factbook") returns all backups that have been made from the factbook database.
|