All functions in this module are assigned to the http://basex.org/modules/db
namespace, which is statically bound to the db
prefix.
All errors are assigned to the http://basex.org/errors
namespace, which is statically bound to the bxerr
prefix.
Database Nodes
Many function signatures in this and other modules share $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:
BXDB0001
: $db
references an XML node that is not stored in a database, or is no database fragment.
BXDB0002
: the addressed database cannot be opened.
Last not but least, the argument may also reference a BaseX-specific database fragment. All XML fragments can be converted to database fragments by applying the transform expression on an XML fragment:
copy $c := element hello { 'world' }
modify ()
return db:text($c, 'world')
Important note: All functions in this section are updating functions: they will not be immediately executed, but queued on the Pending Update List, which will be processed after the actual query has been evaluated. This means that the order in which the functions are specified in the query does usually not reflect the order in which the code will be evaluated.
db:create
Template:Mark
Signatures
|
db:create($db as xs:string) as empty-sequence()
db:create($db as xs:string, $input as item()) as empty-sequence()
db:create($db as xs:string, $input as item(), $path as xs:string) as empty-sequence()
|
Summary
|
Creates a new database with name $db and adds the initial document $input to the specified $path .
$input may be a string or a node different than attribute. If the $input source is not a file or a folder, $path must be specified.
|
Errors
|
FODC0002 : $input points to an unknown resource.
FOUP0001 : $input is neither string nor a document node.
BXDB0011 : $db is not a valid database name.
|
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:drop
Template:Mark
Signatures
|
db:drop($db as item()) as empty-sequence()
|
Summary
|
Drops the database specified by the database node $db and all connected resources.
|
Errors
|
BXDB0007 : $db is opened by another process.
|
Examples
|
db:drop("DB") drops the database DB .
|
db:add
Template:Mark Node inputs will be automatically converted to document nodes.
Signatures
|
db:add($db as item(), $input as item()) as empty-sequence()
db:add($db as item(), $input as item(), $path as xs:string) as empty-sequence()
|
Summary
|
Adds documents specified by $input to the database specified by the database node $db and the specified $path .
$input may be a string or a node different than attribute. If the $input source is not a file or a folder, $path must be specified.
|
Errors
|
FODC0002 : $input points to an unknown resource.
FOUP0001 : $input is neither string nor a document node.
|
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 with content <a/> to the database DB under the name doc.xml .
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") adds all documents in /home/dir to the database DB under the path docs/dir .
|
db:delete
Signatures
|
db:delete($db as item(), $path as xs:string) as empty-sequence()
|
Summary
|
Deletes document(s), specified by $path , from the database specified by the database node $db .
|
Examples
|
db:delete("DB", "docs/dir/doc.xml") deletes the document docs/dir/doc.xml in the database DB .
db:delete("DB", "docs/dir") deletes all documents with paths beginning with docs/dir in the database DB .
|
db:optimize
Signatures
|
db:optimize($db as item()) as empty-sequence()
db:optimize($db as item(), $all as xs:boolean) as empty-sequence()
|
Summary
|
Optimizes the meta data and indexes of the database specified by the database node $db . If $all is set to true() , the complete database will be rebuilt.
|
Errors
|
FOUP0002 : an error occurred while optimizing the database.
|
Examples
|
db:optimize("DB") optimizes the database structures of the database DB .
db:optimize("DB", true()) optimizes all database structures of the database DB .
|
db:rename
Signatures
|
db:rename($db as item(), $path as xs:string, $newpath as xs:string) as empty-sequence()
|
Summary
|
Renames document(s), specified by $path to $newpath in the database specified by the database node $db .
|
Errors
|
BXDB0008 : new document names would be empty.
|
Examples
|
db:rename("DB", "docs/dir/doc.xml", "docs/dir/newdoc.xml") renames the document docs/dir/doc.xml to docs/dir/newdoc.xml in the database DB .
db:rename("DB", "docs/dir", "docs/newdir") renames all documents with paths beginning with docs/dir to paths beginning with docs/newdir in the database DB .
|
db:replace
Template:Mark Node inputs will be automatically converted to document nodes.
Signatures
|
db:replace($db as item(), $path as xs:string, $input as item()) as empty-sequence()
|
Summary
|
Replaces a document, specified by $path , in the database specified by the database node $db with the content of $input , or adds it as a new document.
|
Errors
|
BXDB0006 : $path is not a single document path.
FODC0002 : $input is a string representing a path, which cannot be read.
FOUP0001 : $input is neither a string nor a document node.
|
Examples
|
db:replace("DB", "docs/dir/doc.xml", "/home/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:replace("DB", "docs/dir/doc.xml", "<a/>") replaces the content of the document docs/dir/doc.xml in the database DB with <a/> .
db:replace("DB", "docs/dir/doc.xml", document { <a/> }) replaces the content of the document docs/dir/doc.xml in the database DB with the specified document node.
|
db:store
Signatures
|
db:store($db as item(), $path as xs:string, $input as item()) as empty-sequence()
|
Summary
|
Stores a binary resource specified by $input in the database specified by the database node $db and the location specified by $path .
|
Errors
|
BXDB0003 : the databse is not persistent (stored on disk).
FODC0007 : the specified path is invalid.
FOUP0002 : the resource cannot be stored at the specified location.
|
Examples
|
db:store("DB", "video/sample.mov", file:read-binary('video.mov')) stores the addressed video file at the specified location.
|
db:output
Signatures
|
db:output($data as item()*) as empty-sequence()
|
Summary
|
This function can be used to both perform updates and return results in a single query. The argument of the function will be evaluated, and the resulting value will be cached and returned after the updates on the pending update list have been processed. The function can only be used together with updating expressions; if the function is called within a transform expression, its results will be discarded.
|
Examples
|
db:output("Prices have been deleted."), delete node //price deletes all price elements in a database and returns an info message.
|
db:flush
Template:Mark
Signatures
|
db:flush($db as item()) as empty-sequence()
|
Summary
|
Explicitly flushes the buffers of the database specified by the database node $db . This command is only useful if AUTOFLUSH has been set to false .
|