| XQUERY/XSLT API DOCUMENTATION 4.2 |
All XQuery & XSLT Functions MarkLogic Built-In Functions Admin (xdmp:) AppServer (xdmp:) Classifier (cts:) Debug (dbg:) Document Conversion (xdmp:) Extension (xdmp:) Documents, Directories, Properties, and Locks Functions Extension Functions Function Values Functions HTTP Functions JSON Functions MarkLogic Server Functions Search Functions XML Functions XQuery Context Functions XSLT Functions map (map:) Math (math:) Profile (prof:) Search (cts:) cts:query Constructors Functions Geospatial Functions Geospatial Lexicon Functions Lexicon Functions Search Functions Search Clustering Functions Security (xdmp:) Server Monitoring (xdmp:) Spell (spell:) Update (xdmp:) XQuery Library Modules Admin Library (admin:) Actions Functions Appserver Functions Database Functions Forest Functions Group Functions Host Functions Mimetypes Functions Scheduler Functions Alerting (alert:) Elastic Compute Cloud (ec2:) Entity Enrichment (entity:) Flexible Replication (flexrep:) Geospatial Supporting Functions GEO Functions GeoRSS Functions GML Functions KML Functions MCGM Functions Information Studio (info:) Information Studio Developer (infodev:) Library Services (dls:) cts:query Constructor Functions Document Management Functions Document Update Functions Retention Policy Functions XInclude Functions Modular Documents XInclude Functions XPointer Functions PKI (pki:) Plugin (plugin:) Search (search:) Security-sec (sec:) Spelling Dictionary Management (spell:) Thesaurus (thsr:) Triggers (trgr:) Triggers Library (trgr:) WordProcessingML (ooxml:) ZIP Package (ooxml:) CPF Functions Content Processing Framework (cpf:) CSS Conversion (css:) DocBook Conversion (dbk:) Domains (dom:) Excel Conversion (excel:) Generic Conversion (cvt:) Links (lnk:) MSWord Conversion (msword:) PDF Conversion (pdf:) Pipelines (p:) Powerpoint Conversion (ppt:) XHTML Conversion (xhtml:) W3C-Standard Functions Accessor (fn:) AnyURI (fn:) Boolean (fn:) Context (fn:) DurationDateTime (fn:) Error and Trace (fn:) Node (fn:) Numeric (fn:) QName (fn:) Sequence (fn:) String (fn:) XSLT (fn:) W3C XQuery/XSLT Reference W3C XQuery Functions W3C XQuery Language W3C XSLT Language
This page was generated September 12, 2012 6:01 AM | XQuery & XSLT Built-In & 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-open-replica | Returns a forest id or its open replica id if it is currently experiencing a local disk failover.
xdmp:forest-restart | Restarts a forest.
xdmp:forest-restore | Restores forest data files.
xdmp:forest-rollback | Rolls forests back to a previous point in time, marking any fragment newer than the specified timestamp as deleted.
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,
| [$include-replicas as xs:boolean?]
) 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.
$include-replicas (optional): Whether or not to include replica forests
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-database-backup-validate`
Example:
      xdmp:database-backup-validate((11183608861595735720,898513504988507762),
        "/backups/Data", fn:false())
      =>
    <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)
    =>
    <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>docapp</job:forest-name>
        <job:forest-id>7521617173471751251</job:forest-id>
        <job:status>in-progress</job:status>
      </job:forest>
    </job:job-status>
xdmp:database-restore-validate(
| $forestIDs as unsignedLong*,
| $pathname as xs:string,
| [$restoreToTime as xs:dateTime],
| [$include-replicas as xs:boolean?]
) 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.
$include-replicas (optional): Whether to include replica forests
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`
Usage Notes: The user under which MarkLogic Server is running must have permissions to read the specified directory. For example, on Windows systems, MarkLogic Server typically runs as the SYSTEM user, and therefore the SYSTEM user must have permissions to read the directory (even a mapped network drive directory). Similarly, on UNIX systems, MarkLogic Server typically runs as the daemon user, and that user needs to have read permission to the specified directory. If the user in which MarkLogic Server runs does not have the needed permissions, then a an error such as SVC-DIROPEN or SVC-FILOPEN is thrown when you attempt to call `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. If a forest has replica forests, the replicas are cleared as well.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-forest-clear`
Example:
      xdmp:forest-clear(11183608861595735720)
xdmp:forest-open-replica(
| $forestIDs as unsignedLong*
) as unsignedLong*
Summary: Returns a forest id or its open replica id if it is currently experiencing a local disk failover.
Parameters:
$forestIDs : The IDs of the forests that may have failed over.
Example:
      xdmp:forest-open-replica(xdmp:database-forests("Documents"))
xdmp:forest-restart(
| $forestIDs as unsignedLong*
) as empty-sequence()
Summary: Restarts a forest. If multiple forest IDs are specified, the restarts occur in parallel.
Parameters:
$forestIDs : A forest ID.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-forest-restart`
Example:
      xdmp:forest-restart((11183608861595735720,29382837261839278))
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:forest-rollback(
| $forestIDs as unsignedLong*,
| $timestamp as unsignedLong
) as empty-sequence()
Summary: Rolls forests back to a previous point in time, marking any fragment newer than the specified timestamp as deleted. Also, any fragments that were created before the specified timestamp and deleted after will be rolled back (un-deleted).
Parameters:
$forestIDs : A sequence of forest IDs.
$timestamp : The system timestamp to which you want to roll back.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-forest-rollback`
Usage Notes: If the timestamp specified is greater than the current system timestamp (that is, greater than the value of `xdmp:request-timestamp()`), then an exception is thrown. If the specified timestamp is less than (earlier) then the the oldest timestamp in the specified forest(s), then an exception is thrown. You should not have any updates occurring on a forest while it is being rolled back; the best practice is for the forest to be quiesced during a rollback operation. If you have failover replication configured for a forest, the replica forest(s) will be rolled back at the same time as the specified forest(s). If MarkLogic Server restarts during a rollback operation, the rollback will complete when the forest comes back online. You can only roll back a forest that is in the "Open" state. The `updates-allowed` setting must be set to `all` in order to successfully roll a forest back to a previous timestamp. As part of the `xdmp:forest-rollback` operation, the specified forest(s) are restarted. As a consequence of the forest(s) restarting, if the forest is a failover forest and it is failed over to another host, the system will attempt to mount the forest on the original host (that is, it will un-failover the forest). If you perform an `xdmp:forest-rollback` operation on a forest attached to the context database or any of its auxilliary databases (the security, modules, or triggers databases for that database), then the rollback is performed asyncronously in the background, and any exceptions that occur will not be reported back to the program; in this case, if an exception occurs it might be reported to the `ErrorLog.txt` file. Additionally, because the rollback of forests in the context database (or in its auxilliary databases) is run asyncronously, there might be a small delay between when the rollback is issued and when the forest is restarted, and the rollback state is not reflected until the forest restart is completed. Therefore, it is best practice to call `xdmp:forest-rollback` against forests not attached to the context database. After an `xdmp:forest-clear` operation on a forest, you will no longer be able to roll that forest back (because the forest clear deletes all of the stands in the forest). The forest rollback operation cannot be undone (except by restoring from backup); that is, after rolling a forest back to a point in time, you cannot roll the forest "forward" to where you started.
Example:
      xdmp:forest-rollback(11183608861595735720, 12345623)
Example:
       (:
       Run this against a different database context then
       the my-db database.
       :)
      xdmp:forest-rollback(
         xdmp:database-forests(xdmp:database("my-db")), 12345623)
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-2012 MarkLogic Corporation. All rights reserved.