MarkLogic Server
XQUERY API DOCUMENTATION
4.1
All XQuery Functions
MarkLogic Built-In Functions
XQuery Library Modules
CPF Functions
W3C-Standard Functions
  W3C XQuery Reference
W3C XQuery Functions
W3C XQuery Language
This page was generated
August  8,  2011
2:24  AM
XQuery Built-In and Modules Function Reference

Built-In: Admin

Implements a library of administrative functions for MarkLogic Server.
Function Summary
xdmp:database-backup Starts an asynchronous backup of the specified list of forests to the backup data directory.
xdmp:database-backup-cancel Cancels an outstanding backup job with the specified job ID, returning true if the cancel operation is successful, false if the cancel operation is not successful.
xdmp:database-backup-purge Purge old backups from a directory.
xdmp:database-backup-status Checks the status of the outstanding backup job with the specified job ID.
xdmp:database-backup-validate Validates that the specified list of forests can be backed up to the backup data directory.
xdmp:database-restore Starts an asynchronous restore of the specified list of forests from the backup data directory.
xdmp:database-restore-cancel Cancels an outstanding restore job with the specified job ID, returning true if the cancel operation is successful, false if the cancel operation is not successful.
xdmp:database-restore-status Checks the status of the outstanding restore job with the specified job ID.
xdmp:database-restore-validate Validates that the specified list of forests can be restored from the backup data directory.
xdmp:filesystem-directory Performs a directory listing of the given file pathname.
xdmp:filesystem-file Reads a file from the filesystem.
xdmp:forest-backup Backs up forest data files.
xdmp:forest-clear Clears forest data files.
xdmp:forest-restart Restarts a forest.
xdmp:forest-restore Restores forest data files.
xdmp:merge-cancel Cancel the merge with the specified merge ID on a forest with the specified forest ID.
xdmp:restart Restart servers on hosts.
xdmp:shutdown Shutdown servers on hosts.
Function Detail
xdmp:database-backup(
$forestIDs as unsignedLong*,
$pathname as xs:string
)  as   xs:unsignedLong
Summary:

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

Parameters:
$forestIDs : A sequence of forest IDs.
$pathname : A backup data directory pathname. The directory must exist and be writable by the operating system user under which MarkLogic Server is running. The directory cannot be the MarkLogic Server install directory or the MarkLogic Server data directory.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-database-backup
Usage Notes:

You cannot restore to a read-only forest.

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

The backup directory must exist on each host that has a forest specified in the database backup call (that is, the d-nodes in which the forests being backed up are hosted).


Example: 
  xdmp:database-backup((11183608861595735720,898513504988507762), 
    "/backups/Data")
  => 33030877979801813489
Example: 
  xdmp:database-backup(xdmp:database-forests(xdmp:database("Documents")),
    "/backups/Data")
  => 437302857479804813287
xdmp:database-backup-cancel(
$jobid as unsignedLong
)  as   xs:boolean
Summary:

Cancels an outstanding backup job with the specified job ID, returning true if the cancel operation is successful, false if the cancel operation is not successful.

Parameters:
$jobid : A backup job ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-database-backup-cancel
Example: 
  xdmp:database-backup-cancel(33030877979801813489)
  => true
xdmp:database-backup-purge(
$dir as xs:string,
$keep-num-backups as xs:unsignedInt
)  as   empty-sequence()
Summary:

Purge old backups from a directory.

Parameters:
$dir : The directory under which to look for backups.
$keep-num-backups : The maximum number of old backups to keep.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-database-backup-purge
xdmp:database-backup-status(
$jobid as unsignedLong,
[$hostid as unsignedLong]
)  as   element()
Summary:

Checks the status of the outstanding backup job with the specified job ID. Returns a database backup status node defined in the job-status.xsd schema.

Parameters:
$jobid : A backup job ID.
$hostid (optional): The ID of the host that the backup was started on.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-database-backup-status
Usage Notes:

The structure of the XML node returned is as follows:

forest
The forest being backed up. There is one forest element for each forest in the backup.

This is a complex element with the following element children:

forest-name
The name of the forest.

forest-id
The forest ID.

status
The status of the forest backup. The status is one of: "queued", "in-progress", "failed", "canceled", completed", or "unknown".

Example: 
  xdmp:database-backup-status(33030877979801813489, 16529920850295602277)
  => 
<job:job-status 
   xsi:schemaLocation="http://marklogic.com/xdmp/job-status job-status.xsd" 
   xmlns:job="http://marklogic.com/xdmp/job-status" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <job:forest>
    <job:forest-name>Documents</job:forest-name>
    <job:forest-id>9157142760003704384</job:forest-id>
    <job:status>in-progress</job:status>
  </job:forest>
</job:job-status>
xdmp:database-backup-validate(
$forestIDs as unsignedLong*,
$pathname as xs:string
)  as   element()
Summary:

Validates that the specified list of forests can be backed up to the backup data directory. Returns a database backup set node.

Parameters:
$forestIDs : A sequence of forest IDs.
$pathname : A backup data directory pathname.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-database-backup-validate
Example: 
  xdmp:database-backup-validate((11183608861595735720,898513504988507762), 
    "/backups/Data")
  => 
<bp:backup-plan 
   xsi:schemaLocation="http://marklogic.com/xdmp/backup-plan backup-plan.xsd"
   xmlns:bp="http://marklogic.com/xdmp/backup-plan" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
  <bp:forest>
    <bp:forest-name>Documents</bp:forest-name>
    <bp:forest-id>9157142760003704384</bp:forest-id>
    <bp:forest-status>okay</bp:forest-status>
    <bp:directory-path>/tmp</bp:directory-path>
    <bp:directory-status>okay</bp:directory-status>
    <bp:action>backup</bp:action>
  </bp:forest>

  <bp:forest>
    <bp:forest-name>Security</bp:forest-name>
    <bp:forest-id>5999952135320153149</bp:forest-id>
    <bp:forest-status>okay</bp:forest-status>
    <bp:directory-path>/tmp</bp:directory-path>
    <bp:directory-status>okay</bp:directory-status>
    <bp:action>backup</bp:action>
  </bp:forest>

  <bp:forest>
    <bp:forest-name>Schemas</bp:forest-name>
    <bp:forest-id>10012970808570479716</bp:forest-id>
    <bp:forest-status>okay</bp:forest-status>
    <bp:directory-path>/tmp</bp:directory-path>
    <bp:directory-status>okay</bp:directory-status>
    <bp:action>backup</bp:action>
  </bp:forest>

  <bp:forest>
    <bp:forest-name>Triggers</bp:forest-name>
    <bp:forest-id>17114437544213719134</bp:forest-id>
    <bp:forest-status>okay</bp:forest-status>
    <bp:directory-path>/tmp</bp:directory-path>
    <bp:directory-status>okay</bp:directory-status>
    <bp:action>backup</bp:action>
  </bp:forest>
</bp:backup-plan>
xdmp:database-restore(
$forestIDs as unsignedLong*,
$pathname as xs:string,
[$restoreToTime as xs:dateTime?]
)  as   xs:unsignedLong
Summary:

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

Parameters:
$forestIDs : A sequence of forest IDs.
$pathname : A backup data directory pathname.
$restoreToTime (optional): The date and time to restore the forest data to.

Required Privilege:

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

Reindexing will stop while a backup or restore is in progress.
Example: 
  xdmp:database-restore((11183608861595735720,898513504988507762),
    "/backups/Data")
  => 33030877979801813489
xdmp:database-restore-cancel(
$jobid as unsignedLong
)  as   xs:boolean
Summary:

Cancels an outstanding restore job with the specified job ID, returning true if the cancel operation is successful, false if the cancel operation is not successful.

Parameters:
$jobid : A restore job ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-database-restore-cancel
Example: 
  xdmp:database-restore-cancel(33030877979801813489)
  => true
xdmp:database-restore-status(
$jobid as unsignedLong
)  as   element()
Summary:

Checks the status of the outstanding restore job with the specified job ID. Returns a database restore status node.

Parameters:
$jobid : A restore job ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-database-restore-status
Example: 
  xdmp:database-restore-status(33030877979801813489)
  => ..database restore status node
xdmp:database-restore-validate(
$forestIDs as unsignedLong*,
$pathname as xs:string,
[$restoreToTime as xs:dateTime]
)  as   element()
Summary:

Validates that the specified list of forests can be restored from the backup data directory. Returns a database restore set node.

Parameters:
$forestIDs : A sequence of forest IDs.
$pathname : A backup data directory pathname.
$restoreToTime (optional): The date and time to restore the forest data to.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-database-restore-validate
Example: 
  xdmp:database-restore-validate((11183608861595735720,898513504988507762), 
    "/backups/Data")
  => ..database restore set node
xdmp:filesystem-directory(
$pathname as xs:string
)  as   element(dir:directory)
Summary:

Performs a directory listing of the given file pathname.

Parameters:
$pathname : Pathname of the directory to be listed.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-filesystem-directory
Example: 
  xdmp:filesystem-directory("/etc")
  => ..directory listing node
xdmp:filesystem-file(
$pathname as xs:string
)  as   xs:string
Summary:

Reads a file from the filesystem. The file at the specified path must be UTF-8 encoded.

Parameters:
$pathname : Pathname of the file to be read.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-filesystem-file
Example: 
  xdmp:filesystem-file("/etc/motd")
  => contents of /etc/motd
xdmp:forest-backup(
$forestID as unsignedLong,
$pathname as xs:string
)  as   empty-sequence()
Summary:

Backs up forest data files.

Parameters:
$forestID : A forest ID.
$pathname : A forest backup pathname. If the directory does not exist, it is created when you run this function. The filesystem permissions must be such that the directory is writable by the operating system user under which MarkLogic Server is running. The directory cannot be the MarkLogic Server install directory or the MarkLogic Server data directory.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-forest-backup
Usage Notes:

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


Example: 
  xdmp:forest-backup(11183608861595735720,"/backups/Data/Forests/Documents")
xdmp:forest-clear(
$forestIDs as unsignedLong*
)  as   empty-sequence()
Summary:

Clears forest data files.

Parameters:
$forestIDs : The IDs of the forests to clear.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-forest-clear
Example: 
  xdmp:forest-clear(11183608861595735720)
xdmp:forest-restart(
$forestID as unsignedLong
)  as   empty-sequence()
Summary:

Restarts a forest.

Parameters:
$forestID : A forest ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-forest-restart
Example: 
  xdmp:forest-restart(11183608861595735720)
xdmp:forest-restore(
$forestID as unsignedLong,
$pathname as xs:string
)  as   empty-sequence()
Summary:

Restores forest data files. Restarts the forest to complete the restoration.

Parameters:
$forestID : A forest ID.
$pathname : A forest backup pathname.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-forest-restore
Usage Notes:

Reindexing will stop while a backup or restore is in progress.
Example: 
  xdmp:forest-restore(11183608861595735720,"/backups/Data/Forests/Documents")
xdmp:merge-cancel(
$forest-ID as xs:unsignedLong,
$merge-ID as xs:unsignedLong
)  as   empty-sequence()
Summary:

Cancel the merge with the specified merge ID on a forest with the specified forest ID.

Parameters:
$forest-ID : A forest ID.
$merge-ID : A merge ID, which is available from the output of xdmp:forest-status.

Required Privilege:

http://marklogic.com/xdmp/privileges/request-my-requests or http://marklogic.com/xdmp/privileges/request-any-requests
Usage Notes:

To cancel a merge on a database, find all of the forests in the database and use xdmp:merge-cancel on each forest.

Example: 
  xdmp:merge-cancel(98394839084390843,3838938902783)
   => ()
xdmp:restart(
$hostIDs as unsignedLong*,
$reason as xs:string
)  as   empty-sequence()
Summary:

Restart servers on hosts.

Parameters:
$hostIDs : A sequence of host IDs, or empty sequence for the local host.
$reason : Prepositional phrase describing the reason to restart.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-restart
Example: 
  xdmp:restart((), "to reload server.xml")
xdmp:shutdown(
$hostIDs as unsignedLong*,
$reason as xs:string
)  as   empty-sequence()
Summary:

Shutdown servers on hosts.

Parameters:
$hostIDs : A sequence of host IDs, or empty sequence for the local host.
$reason : Prepositional phrase describing the reason to shutdown.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-shutdown
Example: 
  xdmp:shutdown((), "for software upgrade")
 © Copyright 2002-2011 MarkLogic Corporation.    All rights reserved.