MarkLogic 12 Product Documentation

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.

Required 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