MarkLogic Server
XQUERY/XSLT API DOCUMENTATION
5.0
All XQuery & XSLT Functions
MarkLogic Built-In Functions
XQuery Library Modules
CPF Functions
W3C-Standard Functions
  W3C XQuery/XSLT Reference
W3C XQuery Functions
W3C XQuery Language
W3C XSLT Language
This page was generated
March  13,  2012
4:48  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Admin Library - Database Replication Functions

The Admin module is an XQuery library module that allows you to script administrative tasks that you otherwise would need the Admin Interface to perform. Most functions in this library perform adminstrative tasks and therefore require the user who runs the XQuery program to have the Admin role.

Many of these functions provide new configuration information. In most cases, you must save the configuration (with admin:save-configuration, for example) in the same statement that you use the functions in order for them to take effect.

To use the Admin module as part of your own XQuery module, include the following line in your XQuery prolog:

import module namespace admin = "http://marklogic.com/xdmp/admin" at "/MarkLogic/admin.xqy" ;

The library namespace prefix admin is not predefined in the server.
Function Summary
admin:database-add-foreign-replicas This function adds one or more replica databases to the database replication configuration.
admin:database-delete-foreign-master This function removes the specified master database from the database replication configuration on the replica host.
admin:database-delete-foreign-replicas This function deletes the foreign replica database configurations for the specified master database.
admin:database-foreign-master This function returns a master database configuration.
admin:database-foreign-master-get-cluster-id This function returns the id of the cluster from the specified foreign master configuration.
admin:database-foreign-master-get-connect-forests-by-name This function returns the connect-forests-by-name setting from the master database configuration.
admin:database-foreign-master-get-database-id This function returns the id of the foreign master database.
admin:database-foreign-replica This function returns a replica database configuration.
admin:database-foreign-replica-get-cluster-id This function returns the id of the replica cluster from the replica database configuration.
admin:database-foreign-replica-get-connect-forests-by-name This function returns the connect-forests-by-name setting from the replica database configuration.
admin:database-foreign-replica-get-database-id This function returns the id of the replica database from the replica database configuration.
admin:database-foreign-replica-get-lag-limit This function returns the lag limit value from the replica database configuration.
admin:database-get-foreign-master This function returns the configuration for the foreign master database.
admin:database-get-foreign-replicas This function returns the configuration elements of the replica databases associated with the master database specified by database-id.
admin:database-set-foreign-master This function configures the specified replica database to receive replicated data from the specified foreign master.
admin:database-set-foreign-replicas This function sets the foreign replica database configuration.
admin:forest-add-foreign-replicas This function adds the replica forest that is associated with the specified master forest to the database replication configuration.
admin:forest-delete-foreign-master This function deletes the master forest associated with the specified replica forest from the database replication configuration.
admin:forest-delete-foreign-replicas This function deletes the foreign replica of the specified forest on the master host.
admin:forest-foreign-master This function creates a replicaton configuration element for the specified master forest.
admin:forest-foreign-master-get-cluster-id This function returns the id for the cluster from the foreign master forest configuration element.
admin:forest-foreign-master-get-database-id This function returns the id for the database from the foreign master forest configuration element.
admin:forest-foreign-master-get-forest-id This function returns the id for the forest from the foreign master forest configuration element.
admin:forest-foreign-replica This function returns a replica forest configuration.
admin:forest-foreign-replica-get-cluster-id This function returns the id of the replica cluster from the specified replica forest configuration element.
admin:forest-foreign-replica-get-database-id This function returns the id of the replica database from the specified replica forest configuration element.
admin:forest-foreign-replica-get-forest-id This function returns the id of the replica forest from the specified replica forest configuration element.
admin:forest-get-foreign-master This function returns the replication configuration for the master forest associated with the specified replica forest.
admin:forest-get-foreign-replicas This function returns the foreign replicas configuration element.
admin:forest-set-foreign-master This function writes the specified foreign master forest configuration into the database replication configuration.
admin:forest-set-foreign-replicas This function writes the specified replica forest configuration into the database replication configuration.
Function Detail
admin:database-add-foreign-replicas(
$config as element(configuration),
$database-id as xs:unsignedLong,
$replicas as element(db:foreign-replica)*
)  as   element(configuration)
Summary:

This function adds one or more replica databases to the database replication configuration. This function must be executed on the master cluster.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$database-id : The id of the replica database to be added.
$replicas : One or more replica database configuration elements. More than one replica database elements may be specified in a one-to-many replication scheme.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $fdb := 7746794057802787479
  let $cfg := admin:get-configuration()
  let $fcl := admin:cluster-get-foreign-cluster-id($cfg, "ClusterA")
  let $freplica := admin:database-foreign-replica($fcl, $fdb, fn:true(), 300)
  
  return admin:database-add-foreign-replicas($cfg, xdmp:database("NewDB"), $freplica)
  
  (: Adds the 'NewDB' database to the replica databases configuration. Use 
     admin:save-configuration to save the changes to the configuration or 
     pass the configuration to other Admin API functions to make other changes. :)
admin:database-delete-foreign-master(
$config as element(configuration),
$database-id as xs:unsignedLong
)  as   element(configuration)
Summary:

This function removes the specified master database from the database replication configuration on the replica host. This function must be executed on the replica cluster.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$database-id : The id of the domestic database whose foreign master is to be removed from the database replication configuration.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()

  return admin:database-delete-foreign-master($cfg, xdmp:database("Documents"))
 
  (: Returns a configuration element with the foreign master database, 'Documents',
     removed.  Use admin:save-configuration to save the changes to the configuration 
     or pass the configuration to other Admin API functions to make other changes. :)
admin:database-delete-foreign-replicas(
$config as element(configuration),
$database-id as xs:unsignedLong,
$foreign-replicas as element(db:foreign-replica)*
)  as   element(configuration)
Summary:

This function deletes the foreign replica database configurations for the specified master database. This function must be executed on the master cluster.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$database-id : The id of the database.
$foreign-replicas : The configuration elements for the replica databases. These configuration elements can be returned using the admin:database-get-foreign-replicas function. More than one replica database elements may be specified in a one-to-many replication scheme.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";
 
  let $cfg := admin:get-configuration()
  let $freplica := admin:database-get-foreign-replicas($cfg, xdmp:database("Documents"))
  
  return admin:database-delete-foreign-replicas($cfg, xdmp:database("Documents"), $freplica)
   
  (: Removes the foreign replca databases for the master database, 'Documents', from
     the database replication configuration.  Use admin:save-configuration to save the 
     changes to the configuration or pass the configuration to other Admin API functions 
     to make other changes. :)
admin:database-foreign-master(
$foreign-cluster-id as xs:unsignedLong,
$foreign-database-id as xs:unsignedLong,
$connect-forests-by-name as xs:boolean
)  as   element(db:foreign-master)
Summary:

This function returns a master database configuration. Use the output of this function in the admin:database-set-foreign-master function to set the master database configuration.

Parameters:
$foreign-cluster-id : The id of the foreign cluster containing the master host.
$foreign-database-id : The id of the master database.
$connect-forests-by-name : Boolean that indicates whether to connect to forests by name. If fn:true, forests will automatically connect to/from foreign forests of the same name. If false, forests must be individually configured to replicate to/from foreign forests. Individual forest settings override the database level setting.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $fdb := 476761383313557950
  let $cfg := admin:get-configuration()
  let $fcl := admin:cluster-get-foreign-cluster-id($cfg, "ClusterA")

  return admin:database-foreign-master($fcl, $fdb, fn:true())
 
  (: Returns a master database configuration element.  Use the 
     admin:database-set-foreign-master function to set the
     configuration. :)
admin:database-foreign-master-get-cluster-id(
$foreign-master as element(db:foreign-master)
)  as   xs:unsignedLong
Summary:

This function returns the id of the cluster from the specified foreign master configuration.

Parameters:
$foreign-master : The foreign master configuration.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()
  let $fmaster := admin:database-get-foreign-master($cfg, xdmp:database("Documents"))

  return admin:database-foreign-master-get-cluster-id($fmaster)
  
  (: Returns the id of the master cluster from the foreign master configuration
     element. :)
admin:database-foreign-master-get-connect-forests-by-name(
$foreign-master as element(db:foreign-master)
)  as   xs:boolean
Summary:

This function returns the connect-forests-by-name setting from the master database configuration. This function must be executed on the replica cluster.

Parameters:
$foreign-master : The configuration element for the foreign master.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()
  let $fmaster := admin:database-get-foreign-master($cfg, xdmp:database("Documents"))

  return admin:database-foreign-master-get-connect-forests-by-name($fmaster)

  (: Returns the connect-forests-by-name setting from the foreign master database
     configuration element. :)
admin:database-foreign-master-get-database-id(
$foreign-master as element(db:foreign-master)
)  as   xs:unsignedLong
Summary:

This function returns the id of the foreign master database. This function must be executed on the replica cluster.

Parameters:
$foreign-master : The foreign master configuration.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";
 
  let $cfg := admin:get-configuration()
  let $fmaster := admin:database-get-foreign-master($cfg, xdmp:database("Documents"))

  return admin:database-foreign-master-get-database-id($fmaster)

  (: Returns the id of the master database from the foreign master configuration
     element. :)
admin:database-foreign-replica(
$foreign-cluster-id as xs:unsignedLong,
$foreign-database-id as xs:unsignedLong,
$connect-forests-by-name as xs:boolean,
$lag-limit as xs:unsignedInt
)  as   element(db:foreign-replica)
Summary:

This function returns a replica database configuration. Use the output of this function in the admin:database-set-foreign-replicas function to place the replica database configuration into the cluster configuration.

Parameters:
$foreign-cluster-id : The id of the foreign cluster containing the replica database.
$foreign-database-id : The id of the replica database.
$connect-forests-by-name : Boolean that indicates whether to connect to forests by name. If fn:true, forests will automatically connect to/from foreign forests of the same name. If false, forests must be individually configured to replicate to/from foreign forests. Individual forest settings override the database level setting.
$lag-limit : This parameter controls how far (in seconds) the replica may fall behind before the master stops accepting updates. If contact with the foreign cluster is lost, a warning will be logged and master forests will permit updates to proceed with no enforcement of the lag limit.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";
 
  let $fdb := 7746794057802787479
  let $cfg := admin:get-configuration()
  let $fcl := admin:cluster-get-foreign-cluster-id($cfg, "ClusterA")

  return admin:database-foreign-replica($fcl, $fdb, fn:true(), 300)

  (: Returns the replica database configuration.  Use the
     admin:database-set-foreign-replicas function to set
     the confirguration. :)
admin:database-foreign-replica-get-cluster-id(
$foreign-replica as element(db:foreign-replica)
)  as   xs:unsignedLong
Summary:

This function returns the id of the replica cluster from the replica database configuration.

Parameters:
$foreign-replica : The foreign replica configuration element.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()
  let $freplica := admin:database-get-foreign-replicas($cfg, xdmp:database("Documents")) 
  
  return admin:database-foreign-replica-get-cluster-id($freplica)
 
  (: Returns the id of the replica cluster from the foreign replica database 
     configuration element. :)
admin:database-foreign-replica-get-connect-forests-by-name(
$foreign-replica as element(db:foreign-replica)
)  as   xs:boolean
Summary:

This function returns the connect-forests-by-name setting from the replica database configuration. This function must be executed on the master cluster.

Parameters:
$foreign-replica : The configuration element for the foreign replicas.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()
  let $freplica := admin:database-get-foreign-replicas($cfg, xdmp:database("Documents")) 
  
  return admin:database-foreign-replica-get-connect-forests-by-name($freplica) 

  (: Returns the connect-forests-by-name setting from the foreign replica database
     configuration element. :)
admin:database-foreign-replica-get-database-id(
$foreign-replica as element(db:foreign-replica)
)  as   xs:unsignedLong
Summary:

This function returns the id of the replica database from the replica database configuration.

Parameters:
$foreign-replica : The foreign replica configuration element.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()
  let $freplica := admin:database-get-foreign-replicas($cfg, xdmp:database("Documents")) 
  
  return admin:database-foreign-replica-get-database-id($freplica)

  (: Returns the id of the replica database from the foreign replica database
     configuration element. :)
admin:database-foreign-replica-get-lag-limit(
$foreign-replica as element(db:foreign-replica)
)  as   xs:unsignedInt
Summary:

This function returns the lag limit value from the replica database configuration.

Parameters:
$foreign-replica : The configuration element for the foreign replica database.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";
 
  let $cfg := admin:get-configuration()
  let $freplica := admin:database-get-foreign-replicas($cfg, xdmp:database("Documents")) 
  
  return admin:database-foreign-replica-get-lag-limit($freplica) 

  (: Returns the lag limit setting from the foreign replica database
     configuration element. :)
admin:database-get-foreign-master(
$config as element(configuration),
$database-id as xs:unsignedLong
)  as   element(db:foreign-master)?
Summary:

This function returns the configuration for the foreign master database. This function must be executed on the replica host.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$database-id : The id of the database.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()

  return admin:database-get-foreign-master($cfg, xdmp:database("Documents"))

  (: Returns the configuration element for the foreign master database. :)
admin:database-get-foreign-replicas(
$config as element(configuration),
$database-id as xs:unsignedLong
)  as   element(db:foreign-replica)*
Summary:

This function returns the configuration elements of the replica databases associated with the master database specified by database-id. This function must be executed on the master cluster.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$database-id : The id of the database.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";
 
  let $cfg := admin:get-configuration()
 
  return admin:database-get-foreign-replicas($cfg, xdmp:database("Documents"))
 
  (: Returns the configuration element for the replica databases associated with 
     the master database, 'Documents'. :)
admin:database-set-foreign-master(
$config as element(configuration),
$database-id as xs:unsignedLong,
$foreign-master as element(db:foreign-master)
)  as   element(configuration)
Summary:

This function configures the specified replica database to receive replicated data from the specified foreign master. This function must be executed on the replica cluster.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$database-id : The id of the database.
$foreign-master : The foreign master configuration returned by the admin:database-foreign-master function.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $fdb := 476761383313557950
  let $cfg := admin:get-configuration()
  let $fcl := admin:cluster-get-foreign-cluster-id($cfg, "ClusterA")
  let $fmaster := admin:database-foreign-master($fcl, $fdb, fn:true())

  return admin:database-set-foreign-master(
                $cfg,
                xdmp:database("Documents"),
                $fmaster)
 
  (: Returns a configuration element that includes the foreign master configuration
     for the 'Documents' database. Use admin:save-configuration to save the changes 
     to the configuration or pass the configuration to other Admin API functions 
     to make other changes. :)
admin:database-set-foreign-replicas(
$config as element(configuration),
$database-id as xs:unsignedLong,
$replicas as element(db:foreign-replica)*
)  as   element(configuration)
Summary:

This function sets the foreign replica database configuration. This function must be executed on the master cluster.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$database-id : The id of the database.
$replicas : One or more replica configuration elements. More than one replica database elements may be specified in a one-to-many replication scheme.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $fdb := 7746794057802787479
  let $cfg := admin:get-configuration()
  let $fcl := admin:cluster-get-foreign-cluster-id($cfg, "ClusterA")
  let $freplica := admin:database-foreign-replica($fcl, $fdb, fn:true(), 300)

  return admin:database-set-foreign-replicas($cfg, xdmp:database("Documents"), $freplica)

  (: Returns the full database configuration element that includes the replication configuration
     for the 'Documents' database. Use admin:save-configuration to save the changes to the 
     configuration or pass the configuration to other Admin API functions to make other changes. :)
admin:forest-add-foreign-replicas(
$config as element(configuration),
$forest-id as xs:unsignedLong,
$foreign-replicas as element(as:foreign-replica)*
)  as   element(configuration)
Summary:

This function adds the replica forest that is associated with the specified master forest to the database replication configuration. This function must be executed on the master host.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$forest-id : The id of the forest on the master host to be replicated.
$foreign-replicas : The element returned by the admin:forest-foreign-replica function that specifies the configuration for the replica forest. More than one forest replica configuration elements may be specified in a one-to-many replication scheme.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()
  let $fcl := admin:cluster-get-foreign-cluster-id($cfg, "ClusterA")
  let $fdb := admin:database-foreign-replica-get-database-id(
                      admin:database-get-foreign-replicas($cfg, xdmp:database("Documents")))
  let $mforest := xdmp:forest("Documents2")
  let $fforest := admin:forest-foreign-replica($fcl, $fdb , 2863600501631949400)
  
  return admin:forest-add-foreign-replicas($cfg, $mforest, $fforest)

  (: Adds the foreign forest, 'Document2', to the forests used by the replica database, 
    'Documents'.  Use admin:save-configuration to save the changes to the configuration 
    or pass the configuration to other Admin API functions to make other changes. :):)
admin:forest-delete-foreign-master(
$config as element(configuration),
$forest-id as xs:unsignedLong
)  as   element(configuration)
Summary:

This function deletes the master forest associated with the specified replica forest from the database replication configuration. This function must be executed on the replica host.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$forest-id : The id of the replica forest associated with the master forest to be deleted from the database replication configuration.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()
 
  return admin:forest-delete-foreign-master($cfg, xdmp:forest("Documents")) 
 
  (: Deletes the foreign master forest from the configuration.  Use 
     admin:save-configuration to save the changes to the configuration 
     or pass the configuration to other Admin API functions to make other changes. :):)
admin:forest-delete-foreign-replicas(
$config as element(configuration),
$forest-id as xs:unsignedLong,
$foreign-replicas as element(as:foreign-replica)*
)  as   element(configuration)
Summary:

This function deletes the foreign replica of the specified forest on the master host.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$forest-id : The id of the replicated forest on the master host.
$foreign-replicas : The element returned by the admin:forest-get-foreign-replicas function that specifies the configuration for the replica forest. More than one forest replica configuration elements may be specified in a one-to-many replication scheme.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";
 
  let $cfg := admin:get-configuration()
  let $freplica := admin:forest-get-foreign-replicas($cfg, xdmp:forest("Documents"))

  return admin:forest-delete-foreign-replicas($cfg, xdmp:forest("Documents"), $freplica)

  (: Returns a configuration element with the foreign replica forest, 'Documents',
     removed. Use admin:save-configuration to save the changes to the configuration 
     or pass the configuration to other Admin API functions to make other changes. :)
admin:forest-foreign-master(
$foreign-cluster-id as xs:unsignedLong,
$foreign-database-id as xs:unsignedLong,
$foreign-forest-id as xs:unsignedLong
)  as   element(as:foreign-master)
Summary:

This function creates a replicaton configuration element for the specified master forest. This function must be executed on the replica cluster.

Parameters:
$foreign-cluster-id : The id of the master cluster.
$foreign-database-id : The id of the master database.
$foreign-forest-id : The id of the master forest.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";
 
  let $cfg := admin:get-configuration()
  let $fcl := admin:cluster-get-foreign-cluster-id($cfg, "ClusterA")
  let $fdb := admin:database-foreign-master-get-database-id(
                  admin:database-get-foreign-master($cfg, xdmp:database("Documents")))
  
  return admin:forest-foreign-master($fcl, $fdb , 3017132713745743620)
 
  (: Returns a configuration element for the foreign master forest. :)
admin:forest-foreign-master-get-cluster-id(
$foreign-master as element(as:foreign-master)
)  as   xs:unsignedLong
Summary:

This function returns the id for the cluster from the foreign master forest configuration element.

Parameters:
$foreign-master : The element returned by the admin:forest-foreign-master or admin:forest-get-foreign-master function that specifies the configuration for the master forest. More than one forest master configuration elements may be specified in a one-to-many replication scheme.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";
 
  let $cfg := admin:get-configuration()
  let $fmforest := admin:forest-get-foreign-master($cfg, xdmp:forest("Documents"))

  return admin:forest-foreign-master-get-cluster-id($fmforest)

  (: Returns the id for the foreign master cluster. :)
admin:forest-foreign-master-get-database-id(
$foreign-master as element(as:foreign-master)
)  as   xs:unsignedLong
Summary:

This function returns the id for the database from the foreign master forest configuration element.

Parameters:
$foreign-master : The element returned by the admin:forest-foreign-master or admin:forest-get-foreign-master function that specifies the configuration for the master forest. More than one forest master configuration elements may be specified in a one-to-many replication scheme.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";
 
  let $cfg := admin:get-configuration()
  let $fmforest := admin:forest-get-foreign-master($cfg, xdmp:forest("Documents"))

  return admin:forest-foreign-master-get-database-id($fmforest)

  (: Returns the id for the foreign master database. :)
admin:forest-foreign-master-get-forest-id(
$foreign-master as element(as:foreign-master)
)  as   xs:unsignedLong
Summary:

This function returns the id for the forest from the foreign master forest configuration element.

Parameters:
$foreign-master : The element returned by the admin:forest-foreign-master or admin:forest-get-foreign-master function that specifies the configuration for the master forest. More than one forest master configuration elements may be specified in a one-to-many replication scheme.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";
 
  let $cfg := admin:get-configuration()
  let $fmforest := admin:forest-get-foreign-master($cfg, xdmp:forest("Documents"))

  return admin:forest-foreign-master-get-forest-id($fmforest)

  (: Returns the id for the foreign master forest. :)
admin:forest-foreign-replica(
$foreign-cluster-id as xs:unsignedLong,
$foreign-database-id as xs:unsignedLong,
$foreign-forest-id as xs:unsignedLong
)  as   element(as:foreign-replica)
Summary:

This function returns a replica forest configuration. Use the output of this function in the admin:forest-set-foreign-replicas function to place the replica forest configuration into the cluster configuration. This function must be executed on the master host.

Parameters:
$foreign-cluster-id : The id of the foreign cluster containing the replica host.
$foreign-database-id : The id of the replica database.
$foreign-forest-id : The id of the foreign forest.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()

  let $fcl := admin:cluster-get-foreign-cluster-id($cfg, "ClusterA")
  let $fdb := admin:database-foreign-replica-get-database-id(
                      admin:database-get-foreign-replicas($cfg, xdmp:database("Documents")))
  
  return admin:forest-foreign-replica($fcl, $fdb , 2331251018938912591)

  (: Returns a replica forest configuration for the master 'Documents' forest. :)
admin:forest-foreign-replica-get-cluster-id(
$foreign-replica as element(as:foreign-replica)
)  as   xs:unsignedLong
Summary:

This function returns the id of the replica cluster from the specified replica forest configuration element. This function must be executed on the master cluster.

Parameters:
$foreign-replica : The element returned by the admin:forest-foreign-replica or admin:forest-get-foreign-replicas function that specifies the configuration for the replica forest.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()
  let $fmforest := admin:forest-get-foreign-replicas($cfg, xdmp:forest("Documents"))

  return admin:forest-foreign-replica-get-cluster-id($fmforest) 

  (: Returns the id for the foreign replica cluster configured for the 
     master 'Documents' forest. :)
admin:forest-foreign-replica-get-database-id(
$foreign-replica as element(as:foreign-replica)
)  as   xs:unsignedLong
Summary:

This function returns the id of the replica database from the specified replica forest configuration element. This function must be executed on the master cluster.

Parameters:
$foreign-replica : The element returned by the admin:forest-foreign-replica or admin:forest-get-foreign-replicas function that specifies the configuration for the replica forest.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()
  let $fmforest := admin:forest-get-foreign-replicas($cfg, xdmp:forest("Documents"))

  return admin:forest-foreign-replica-get-database-id($fmforest)

  (: Returns the id for the foreign replica database configured for the 
     master 'Documents' forest. :)
admin:forest-foreign-replica-get-forest-id(
$foreign-replica as element(as:foreign-replica)
)  as   xs:unsignedLong
Summary:

This function returns the id of the replica forest from the specified replica forest configuration element. This function must be executed on the master cluster.

Parameters:
$foreign-replica : The element returned by the admin:forest-foreign-replica or admin:forest-get-foreign-replicas function that specifies the configuration for the replica forest.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()
  let $fmforest := admin:forest-get-foreign-replicas($cfg, xdmp:forest("Documents"))

  return admin:forest-foreign-replica-get-forest-id($fmforest)

  (: Returns the id for the foreign replica forest configured for the 
     master 'Documents' forest. :)
admin:forest-get-foreign-master(
$config as element(configuration),
$forest-id as xs:unsignedLong
)  as   element(as:foreign-master)?
Summary:

This function returns the replication configuration for the master forest associated with the specified replica forest. This function must be executed on the replica host.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$forest-id : The id of the replica forest.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()
 
  return admin:forest-get-foreign-master($cfg, xdmp:forest("Documents"))

 (: Returns the replication configuration for the master forest. :)
admin:forest-get-foreign-replicas(
$config as element(configuration),
$forest-id as xs:unsignedLong
)  as   element(as:foreign-replica)*
Summary:

This function returns the foreign replicas configuration element. This function must be executed on the master cluster.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$forest-id : The id of the master forest.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";
 
  let $cfg := admin:get-configuration()

  return admin:forest-get-foreign-replicas($cfg, xdmp:forest("Documents"))

  (: Returns the configuration element for the foreign replicas. :)
admin:forest-set-foreign-master(
$config as element(configuration),
$forest-id as xs:unsignedLong,
$foreign-master as element(as:foreign-master)
)  as   element(configuration)
Summary:

This function writes the specified foreign master forest configuration into the database replication configuration. Any forest-level configuration will override the database level-configuration. This function must be executed on the replica cluster.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$forest-id : The id of the replica forest associated with the master forest to be set.
$foreign-master : The element returned by the admin:forest-foreign-master or admin:forest-get-foreign-master function that specifies the configuration for the master forest. More than one forest master configuration elements may be specified in a one-to-many replication scheme.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()
  let $fcl := admin:cluster-get-foreign-cluster-id($cfg, "ClusterA")
  let $fdb := admin:database-foreign-master-get-database-id(
                   admin:database-get-foreign-master($cfg, xdmp:database("Documents")))
  let $fforest := admin:forest-foreign-master($fcl, $fdb , 3017132713745743620)

  return admin:forest-set-foreign-master($cfg, xdmp:forest("Documents"), $fforest)
 
  (: Sets the configuration for the specified foreign master forest.  Use 
     admin:save-configuration to save the changes to the configuration or 
     pass the configuration to other Admin API functions to make other changes. :):)
admin:forest-set-foreign-replicas(
$config as element(configuration),
$forest-id as xs:unsignedLong,
$foreign-replicas as element(as:foreign-replica)*
)  as   element(configuration)
Summary:

This function writes the specified replica forest configuration into the database replication configuration. Any forest-level configuration will override the database level-configuration. This function must be executed on the master cluster.

Parameters:
$config : A configuration specification, typically as returned from one of the Admin module functions.
$forest-id : The id of the forest on the master host to be replicated.
$foreign-replicas : The element returned by the admin:forest-foreign-replica function that specifies the configuration for the replica forest. More than one forest replica configuration elements may be specified in a one-to-many replication scheme.

Example: 
  xquery version "1.0-ml"; 
 
  import module namespace admin = "http://marklogic.com/xdmp/admin" 
      at "/MarkLogic/admin.xqy";

  let $cfg := admin:get-configuration()
  let $fcl := admin:cluster-get-foreign-cluster-id($cfg, "ClusterA")
  let $fdb := admin:database-foreign-replica-get-database-id(
                      admin:database-get-foreign-replicas($cfg, xdmp:database("Documents")))
  
  let $fforest :=
    admin:forest-foreign-replica($fcl, $fdb , 2331251018938912591)
  
  return
     admin:forest-set-foreign-replicas($cfg, xdmp:forest("Documents2"), $fforest)

  (: Returns a configuration element that includes the specified foreign replica
     forests.  Use admin:save-configuration to save the changes to the configuration 
     or pass the configuration to other Admin API functions to make other changes. :)
Copyright  © 2012 MarkLogic Corporation.    All rights reserved.