Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
|}
==db:backups==
{{Mark|Updated with Version 10:}} Support for comments.
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:backups||element(backup)*}}<br/>{{Func|db:backups|$db as xs:string|element(backup)*}}
|-
| '''Summary'''
|Returns an element sequence containing all available database backups with timestamp, file size and comment.<br/>If a database {{Code|$db}} is specified, the sequence will be restricted to the backups matching this database.
|-
| '''Examples'''
|
* {{Code|db:backups("factbook")}} returns all backups that have been made from the {{Code|factbook}} database.
'''Important note:''' All functions in this section are ''updating functions'': they will not be immediately executed, but queued on the [[XQuery Update#Pending Update ListUpdating Functions|Pending Update Listupdating functions]], 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.
→Changelog
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 [[XQuery Update#Pending Update List|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.
=General Functions=
|
* {{Code|db:dir('shop', 'books')}} returns all entries of the {{Code|books}} directory of a {{Code|shop}} database.
|}
=Updates=
==db:create==
|}
==db:create-backupoptimize== {{Mark|Updated with Version 10:}} Options argument added.
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:createoptimize|$db as xs:string|empty-backupsequence()}}<br/>{{Func|db:optimize|$db as xs:string, $all as xs:boolean|empty-sequence()}}<br/>{{Func|db:create-backupoptimize|$db as xs:string, $all as xs:boolean, $options as map(*)?|empty-sequence()}}
|-
| '''Summary'''
|Creates a backup Optimizes the meta data and indexes of the database {{Code|$db}}. The following <br/>If {{Code|$optionsall}} are available:* With is {{Code|commenttrue}}, a comment string the complete database will be rebuilt.<br/>The {{Code|$options}} argument can be attached used to control indexing. The syntax is identical to the backup[[#db:create|db:create]] function: Allowed options are all [[Options#Indexing|indexing]] and [[Options#Full-Text|full-text]] options.* By setting {{Option|UPDINDEX}} is only supported if {{Code|$all}} is {{Code|compresstrue}} to false, the backup will be created faster, but it will take more space on disk.
|-
| '''Errors'''
|{{Error|open|#Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|name|#Errors}} invalid database name.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.
|-
| '''Examples'''
|
* {{Code|db:create-backupoptimize("DB")}} optimizes the database structures of the database {{Code|DB}}.* <code>db:optimize('"DB'", true(), map { 'compressftindex': falsetrue() })}} creates a backup </code> optimizes all database structures of the database {{Code|DB}} without compressing its entriesand creates a full-text index.
|}
==db:drop-backuprename==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:drop-backuprename|$name db as xs:string, $source as xs:string, $target as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Drops Moves all backups resources(s) of the database with {{Code|$db}}, which are found in the specified supplied {{Code|$namesource}}. If the name ends with a datepath, only to the specified backup file supplied {{Code|$target}} path. The paths may point to single resources or directories. No updates will be deletedtake place if a non-existing source path is supplied.
|-
| '''Errors'''
|{{Error|backupopen|#Errors}} No backup file found.<br/>{{Error|name|#Errors}} invalid the addressed database namedoes not exist or could not be opened.<br/>{{Error|conflictpath|#Errors}} the same database was addressed more than oncespecified source or target path, or one of its descendants, is invalid.
|-
| '''Examples'''
|
* {{Code|db:drop-backuprename("DB", "docs/dir/doc.xml", "docs/dir/newdoc.xml")}} drops all backups of renames the resource {{Code|docs/dir/doc.xml}} to {{Code|docs/dir/newdoc.xml}} in the database {{Code|DB}}.* {{Code|db:drop-backuprename("DB-2014-03-13-17-36-44", "docs/dir", "docs/newdir")}} drops moves all resources in the specific backup file database {{Code|DB-2014-03-13-17-36-44.zip}} of the database from {{Code|DBdocs/dir}} to {Code|docs/newdir}}.
|}
==db:alter-backupreplace==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:alterreplace|$db as xs:string, $path as xs:string, $input as item()|empty-backupsequence()}}<br/>{{Func|db:replace|$name db as xs:string, $new-name path as xs:string, $input as item(), $options as map(*)?|empty-sequence()|empty-sequence()}}
|-
| '''Summary'''
|Renames all backups of Replaces a resource, specified by {{Code|$path}}, in the database {{Code|$db}} with the specified contents of {{Code|$nameinput}} to , or adds it as a new resource:* See [[#db:create|db:create]] for more details on the input argument.* The parsing behavior can be controlled via {{Code|$new-nameoptions}}:** allowed options are {{Option|ADDCACHE}}. If and the name ends with a date[[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 been parsed* For historical reasons, the specified backup file will be renamed.order of the 2nd and 3rd argument is different to [[#db:add|db:add]] and [[#db:create|db:create]]
|-
| '''Errors'''
|{{Error|backupopen|#Errors}} No backup file found.<br/>{{Error|name|#Errors}} invalid the addressed database namedoes not exist or could not be opened.<br/>{{Error|conflicttarget|#Errors}} the same database was addressed more than oncepath points to a directory.
|-
| '''Examples'''
|
* {{Code|db:alter-backupreplace("DB", "docs/dir/doc.xml", "/home/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:replace("DB", "DB2docs/dir/doc.xml", "<a/>")}} renames all backups replaces the content of the document {{Code|docs/dir/doc.xml}} in the database {{Code|DB}} to with {{Code|<a/>}}.* {{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|DB2DB}}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:replace('db', $file, doc($path))</syntaxhighlight>
|}
==db:restorestore==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:restorestore|$name db as xs:string, $path as xs:string, $input as item()|empty-sequence()}}
|-
| '''Summary'''
|Restores Replaces a binary resource specified by {{Code|$input}} in the database with the specified {{Code|$namedb}}. The and the location specified by {{Code|$namepath}} may include the timestamp of the backup file, or adds it as new resource.
|-
| '''Errors'''
|{{Error|lockopen|#Errors}} a the addressed database is does not exist or could not be opened by another process.<br/>{{Error|name|#Errors}} invalid database name.<br/>{{Error|no-backup|#Errors}} No backup found.<br/>{{Error|conflictmainmem|#Errors}} the same database was addressed more than onceis not ''persistent'' (stored on disk).
|-
| '''Examples'''
|
* {{Code|db:restorestore("DB", "video/sample.mov", file:read-binary('video.mov'))}} restores stores the addressed video file at the database {{Code|DB}}specified location.* {{Code|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:restorelist("DB$db, $src-2014path)where db:is-03raw($db, $src)let $trg := $trg-13path || substring-18after($src, $src-05-45"path)return db:store($db, $trg, db:retrieve($db, $src))}} restores the database {{Code|DB}} from the backup file with the given timestamp.</syntaxhighlight>
|}
==db:optimizeflush==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:optimizeflush|$db as xs:string|empty-sequence()}}<br/>{{Func|db:optimize|$db as xs:string, $all as xs:boolean|empty-sequence()}}<br/>{{Func|db:optimize|$db as xs:string, $all as xs:boolean, $options as map(*)?|empty-sequence()}}
|-
| '''Summary'''
|Optimizes Explicitly flushes the meta data and indexes buffers of the database {{Code|$db}}.<br/>If {{Code|$all}} is {{Code|true}}, the complete database will be rebuilt.<br/>The {{Code|$options}} argument can be used to control indexing. The syntax is identical to the [[#db:create|db:create]] function: Allowed options are all [[Options#Indexing|indexing]] and [[Options#Full-Text|full-text]] options. {{Option|UPDINDEX}} This command is only supported useful if {{CodeOption|$allAUTOFLUSH}} is has been set to {{Code|truefalse}}.
|-
| '''Errors'''
|{{Error|open|#Errors}} the addressed database does not exist or could not be opened.
|}
=Backups=
{{Announce|Introduced with Version 10:}} Support for general data ([[User Management|registered users]], [[Jobs Module#Services|scheduled services]] and [[Store Module|key-value stores]]).
All functions in this section except for {{Function||db:backups}} are [[#Updating Functions|updating functions]].
==db:create-backup==
{{Announce|Updated with Version 10:}} Options argument added.
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:create-backup|$db as xs:string|empty-sequence()}}<br/>{{Func|db:create-backup|$db as xs:string, $options as map(*)|empty-sequence()}}
|-
| '''Summary'''
|Creates a backup of the database {{Code|$db}}. If no name is supplied, general data will be backed up. The following {{Code|$options}} are available:
* With {{Code|comment}}, a comment string can be attached to the backup.
* By setting {{Code|compress}} to false, the backup will be created faster, but it will take more space on disk.
|-
| '''Errors'''
|{{Error|open|#Errors}} the addressed database does not exist or could not be opened.<br/>{{Error|name|#Errors}} invalid database name.<br/>{{Error|conflict|#Errors}} the same database was addressed more than once.
|-
| '''Examples'''
|
* {{Code|db:optimizecreate-backup("'DB")}} optimizes the database structures of the database {{Code|DB}}.* <code>db:optimize("DB", true()', map { 'ftindexcompress': truefalse() })</code> optimizes all database structures }} creates a backup of the database {{Code|DB}} and creates a full-text indexwithout compressing its entries.
|}
==db:renamedrop-backup==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:renamedrop-backup|$db as xs:string, $source as xs:string, $target name as xs:string|empty-sequence()}}
|-
| '''Summary'''
|Moves Drops all resources(s) backups of the database with the specified {{Code|$dbname}}, which are found in . If the supplied {{Code|$source}} pathname ends with a timestamp, to only the supplied {{Code|$target}} path. The paths may point to single resources or directoriesspecified backup file will be deleted. No updates will take place if a non-existing source path If no name is supplied, backups with general data are addressed.
|-
| '''Errors'''
|{{Error|openbackup|#Errors}} the addressed No backup file found.<br/>{{Error|name|#Errors}} invalid database does not exist or could not be openedname.<br/>{{Error|pathconflict|#Errors}} the specified source or target path, or one of its descendants, is invalidsame database was addressed more than once.
|-
| '''Examples'''
|
* {{Code|db:renamedrop-backup("DB", "docs/dir/doc.xml", "docs/dir/newdoc.xml")}} renames the resource {{Code|docs/dir/doc.xml}} to {{Code|docs/dir/newdoc.xml}} in drops all backups of the database {{Code|DB}}.* {{Code|db:renamedrop-backup("DB", "docs/dir", "docs/newdir-2014-03-13-17-36-44")}} moves all resources in drops the database specific backup file {{Code|DB-2014-03-13-17-36-44.zip}} from of the database {{Code|docs/dir}} to {Code|docs/newdirDB}}.
|}
==db:replacealter-backup==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:replacealter-backup|$db as xs:string, $path name as xs:string, $input as item()|emptynew-sequence()}}<br/>{{Func|db:replace|$db name as xs:string, $path as xs:string, $input as item(), $options as map(*)?|empty-sequence()|empty-sequence()}}
|-
| '''Summary'''
|Replaces a resource, specified by {{Code|$path}}, in Renames all backups of the database {{Code|$db}} with the contents of specified {{Code|$inputname}}, or adds it as a new resource:* See [[#db:create|db:create]] for more details on the input argument.* The parsing behavior can be controlled via to {{Code|$optionsnew-name}}:** allowed options are {{Option|ADDCACHE}} and . If the [[Options#Parsing|parsing]] and [[Options#XML Parsing|XML parsing]] optionsname ends with a date, all in lower case** parsing options will only impact string input (URIs, XML strings), because nodes have already been parsed* For historical reasons, the order of the 2nd and 3rd argument is different to [[#db:add|db:add]] and [[#db:create|db:create]]specified backup file will be renamed.
|-
| '''Errors'''
|{{Error|openbackup|#Errors}} the addressed No backup file found.<br/>{{Error|name|#Errors}} invalid database does not exist or could not be openedname.<br/>{{Error|targetconflict|#Errors}} the path points to a directorysame database was addressed more than once.
|-
| '''Examples'''
|
* {{Code|db:replacealter-backup("DB", "docs/dir/doc.xml", "/home/dir/doc.xml"DB2)}} replaces the content renames all backups of the document {{Code|docs/dir/doc.xml}} in the database {{Code|DB}} with the content of the file {{Code|/home/dir/doc.xml}}.* to {{Code|db:replace("DB", "docs/dir/doc.xml", "<a/>")DB2}} replaces the content of the document {{Code|docs/dir/doc.xml}} in the database {{Code|DB}} with {{Code|<a/>}}.* {{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:<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:replace('db', $file, doc($path))</syntaxhighlight>
|}
==db:storerestore==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:storerestore|$db name as xs:string, $path as xs:string, $input as item()|empty-sequence()}}
|-
| '''Summary'''
|Replaces a binary resource Restores the database with the specified by {{Code|$inputname}} in the database . The {{Code|$dbname}} and may include the timestamp of the location specified by {{Code|$path}}backup file. If no name is supplied, general data will be restored. If general data is restored, or adds it as new resourcewill only be available after BaseX has been restarted.
|-
| '''Errors'''
|{{Error|openlock|#Errors}} the addressed a database does not exist or could not be is openedby another process.<br/>{{Error|name|#Errors}} invalid database name.<br/>{{Error|mainmemno-backup|#Errors}} No backup found.<br/>{{Error|conflict|#Errors}} the same database is not ''persistent'' (stored on disk)was addressed more than once.
|-
| '''Examples'''
|
* {{Code|db:storerestore("DB", "video/sample.mov", file:read-binary('video.mov'))}} stores restores the addressed video file at the specified locationdatabase {{Code|DB}}.* With the following query, you can copy full directories{{Code|db:<syntaxhighlight lang=restore("xquery">let $db := 'db'let $srcDB-path := 'src/'let $trg-path := 'trg/'for $src in db:list($db, $src2014-path)where db:is03-raw($db, $src)let $trg := $trg13-path || substring18-after($src, $src05-path45")return db:store($db, $trg, db:retrieve($db, $src))</syntaxhighlight>}} restores the database {{Code|DB}} from the backup file with the given timestamp.
|}
==db:flushbackups==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|db:flushbackups||element(backup)*}}<br/>{{Func|db:backups|$db as xs:string|empty-sequenceelement(backup)*}}
|-
| '''Summary'''
|Explicitly flushes the buffers of the Returns an element sequence containing all available database backups with timestamp, file size and comment.<br/>If a database {{Code|$db}}. This command is only useful if {{Option|AUTOFLUSH}} has been set specified, the sequence will be restricted to {{Code|false}}the backups matching this database.
|-
| '''ErrorsExamples'''|* {{ErrorCode|opendb:backups("factbook")}} returns all backups that have been made from the {{Code|#Errorsfactbook}} the addressed database does not exist or could not be opened.
|}
;Version 10
* Added: [[#Backups|Backups]]: Support for general data ([[User Management|registered users]], [[Jobs Module#Services|scheduled services]] and [[Store Module|key-value stores]]).
* Updated: [[#db:backups|db:backups]], [[#db:create-backups|db:create-backup]]: Options added.
