xdmp:database-restore

xdmp:database-restore(
   $forestIDs as xs:unsignedLong*,
   $pathname as xs:string,
   [$restoreToTime as xs:dateTime?],
   [$journal-archiving as xs:boolean?],
   [$journal-archive-path as xs:string?],
   [$incremental-backup as xs:boolean?],
   [$incremental-backup-path as xs:string?],
   [$backup-passphrase as xs:string?],
   [$forest-map as map:map?]
) as xs:unsignedLong

Summary

Starts an asynchronous restore of the specified list of destination forests from the backup data directory. Returns a job ID that uniquely identifies the restore task.

Parameters
forestIDs	A sequence of destination forest IDs.
pathname	A backup data directory pathname.
restoreToTime	The date and time to restore the forest data to.
journal-archiving	Whether to restore from archived journals. Defaults to false.
journal-archive-path	Path to where archived journals are stored. Defaults to the backup data directory.
incremental-backup	Whether to restore using incremental backups. Defaults to false.
incremental-backup-path	Path to where incremental backups are stored. Defaults to the backup data directory.
backup-passphrase	An additional backup passphrase that can be used to restore from backup.
forest-map	An optional forest map that specify the change of forest topology.

Required Privileges

This operation requires at least one of the following privileges:

http://marklogic.com/xdmp/privileges/xdmp-database-restore

http://marklogic.com/xdmp/privileges/xdmp-database-restore/database/{id}

Usage Notes

Reindexing and rebalancing will stop while a backup or restore is in progress.

All forests in forestIDs must exist in the current configuration.

$forest-map is a map from the names of destination forests to be restored to the names of backup forests (fd1<-fb1, fd2<-fb2, ...). Please note that there are several constraints on the map:

There should be exactly one forest in the key of each map entry.
Keys of the map must be a subset of $forestIDs, otherwise XDMP-FORESTMAPNOTSUBSET will be thrown.
If some forests in forestIDs are not provided in the keys of the map, they will be self-mapped. Self-mapping means mapping destination forests to backup forests that have the same names.
There should be zero or more forests in the value of each map entry. When there are zero forests in the value, it means clearing the destination forest, instead of detaching or deleting it.
There shouldn't be duplicated values in the map (after supplement of self-mapping). Otherwise, XDMP-FORESTMAPDUPVALUE will be thrown.
If $forest-map is not provided, all forests will by default be self-mapped.
All backup forests in the value of a map entry must be accessible to the host where the destination forest is located.

Example

(: Example of default self-mapping :)

xquery version "1.0-ml";

xdmp:database-restore((11183608861595735720,898513504988507762),
    "/backups/Data")
=> 33030877979801813489

Example

(: Example of changing forest topology. :)

xquery version "1.0-ml";

let $map := map:new(
(
  map:entry("fd1", ("fb3")),
  map:entry("fd2", ("fb1")),
  map:entry("fd3", ("fb2"))
))

return xdmp:database-restore(xdmp:database-forests(xdmp:database("db")),
  "/backups/Data", (), fn:false(), "", fn:false(), "", "", $map)
=> 33030877979801813489

Example

(: Example of changing forest topology. Backup forests fb1 and fb2 are restored
to destination forest fd1; fb3 is restored to fd2; fd3 and fd4 are cleared. :)

xquery version "1.0-ml";

let $map := map:new(
(
  map:entry("fd1", ("fb1","fb2")),
  map:entry("fd2", ("fb3")),
  map:entry("fd3", ()),
  map:entry("fd4", ()),
))

return xdmp:database-restore(xdmp:database-forests(xdmp:database("db")),
  "/backups/Data", (), fn:false(), "", fn:false(), "", "", $map)
=> 33030877979801813489