MarkLogic Server 11.0 Product Documentation

Scripting Administrative Tasks Guide — Chapter 2

Importing the Admin Library Module

Because the Admin API is an XQuery library module, you must import it into your XQuery program. The Admin API is installed in the <marklogic-dir>/Modules/MarkLogic/admin.xqy file. To import the Admin API module, include the following in your XQuery prolog:

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

Getting the Current Configuration in Memory

The admin:get-configuration function gets an in-memory representation of the configuration for the purpose of modifying the configuration. It is designed to only be used with the Admin API, not to get the configuration for other purposes. To optimize performance, the admin:get-configuration function gets only the configuration information it needs to process configuration information in a given XQuery request. The configuration information is an XML structure, and it is designed to be used in conjunction with the other Admin API functions; do not try and use the admin:get-configuration function outside of the scope of the Admin API.

The typical design pattern to get the configuration is to get the configuration once per XQuery request and bind its value to a variable (for example, in the let clause of a FLWOR expression). Then you can use that variable through the query to refer to the configuration. Do not try and change the XML representation returned from the admin:get-configuration function.

Because it is optimized to only get the parts of the configuration it needs to make a set of changes, you might find that the admin:get-configuration function sometimes returns an empty element if you run it without performing any other functions. It is designed to be used only with the Admin API functions.

Saving the Configuration Changes

Once you use the various APIs to modify the configuration, you must save the configuration to make it take effect in the MarkLogic Server cluster. There are two APIs to save the configuration:

• admin:save-configuration
• admin:save-configuration-without-restart

Both functions take a configuration element, and then save that element to the configuration files. The configuration file changes are propagated to the entire cluster. The difference between the two functions is that the first one will automatically restart any MarkLogic Server instances when the configuration changes are cold and require a restart. The admin:save-configuration-without-restart function does not automatically restart MarkLogic Server; if a restart is needed for the changes to take effect, it returns the host IDs of the hosts needing a restart; if no restart is required, it returns the empty sequence.

You should only call these functions (one or the other of two) once per XQuery program (that is, once per transaction).

Saving versus Passing the Configuration

There are a number of ways to manage multiple changes to the configuration. The simplest, but most cumbersome, approach is to get and save the configuration for each admin function in a separate transaction. For example:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
         at "/MarkLogic/admin.xqy";
let $config := admin:get-configuration()
return admin:save-configuration(admin:function-call-1($config, ....));
xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
         at "/MarkLogic/admin.xqy";
let $config := admin:get-configuration()
return admin:save-configuration(admin:function-call-2($config, ....));

Another approach is to pass the configuration returned from a previous admin function to the next admin function. For example, in the following pseudo-code example, the $config variable returned from admin:get-configuration holds the initial configuration of MarkLogic Server. The $config variable is progressively updated as it is returned from each admin function and passed as input to the next admin function. The final $config variable holds the configuration from all of the admin function calls and is saved by admin:save-configuration.

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
         at "/MarkLogic/admin.xqy";
(: Get the configuration :)
let $config := admin:get-configuration()
(: Update the configuration :)
let $config := admin:function-call-1($config, ....)
let $config := admin:function-call-2($config, ....)
(: etc....... :)
(: Save the configuration :)
return admin:save-configuration($config5)

Creating and Configuring Objects in a Single Transaction

The admin:object-get-id functions (admin:forest-get-id, admin:database-get-id, admin:group-get-id, admin:appserver-get-id, admin:host-get-id) allow you to create and configure a server object in a single transaction. The main difference between the admin:object-get-id functions and their xdmp:object counterparts is that the admin:object-get-id functions return object IDs from the configuration, whether it has been saved or not, whereas their xdmp:object counterparts return the object IDs of existing objects in MarkLogic Server. In this way, the admin:object-get-id functions provide a faster alternative to what would otherwise be a need to create the object, save the configuration, configure the object, and save the configuration.

For example, the following is an abbreviated version of the code shown in Creating and Configuring Databases in a Single Transaction :

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
         at "/MarkLogic/admin.xqy";
(: Get the configuration :)
let $config := admin:get-configuration()
(: Add new database to the configuration :)
let $config := admin:database-create(
    $config, 
    "Sample-Database",
    xdmp:database("Security"),
    xdmp:database("Schemas"))
(: Obtain the database ID of Sample-Database :)
let $Sample-Database := admin:database-get-id(
    $config, 
    "Sample-Database")
(: Attach the "SampleDB-Forest" forest to Sample-Database :)
let $config := admin:database-attach-forest(
    $config,
    $Sample-Database,
    xdmp:forest("SampleDB-Forest"))
(: Add an index to Sample-Database :)
let $rangespec := admin:database-range-element-index(
    "string", 
    "http://marklogic.com/wikipedia",
    "name", 
    "http://marklogic.com/collation/",
    fn:false() )
let $config := admin:database-add-range-element-index(
    $config, 
    $Sample-Database, 
    $rangespec)
return
   admin:save-configuration($config)

The IDs returned by the admin:object-get-id functions should only be passed to other functions in the Admin library because they operate on the configuration of objects, rather than the existing objects in MarkLogic Server. Functions outside the Admin library only understand the existing objects in MarkLogic Server.

Making Transactions Idempotent

There may be circumstances in which you want to modify a configuration without the need to uninstall it first. For example, you may want to update your configuration program to change an App Server setting or add an index to a database without removing and reinstalling the entire configuration. To enable this option, you need to write idempotent transactions, so that the transaction doesn't fail if some of the objects already exist or have already been deleted.

For example, the transaction that creates and configures a database shown above in Creating and Configuring Objects in a Single Transaction will fail if any of the objects it attempts to create already exist. To make this transaction idempotent, you need to check for the existence of objects before creating them. If an object exists, then no change is made to the configuration. This allows you to modify the transaction later to create, modify, or delete individual objects without the entire transaction failing.

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
         at "/MarkLogic/admin.xqy";
declare namespace xdmpdb = "http://marklogic.com/xdmp/database";
(: Get the configuration :)
let $config := admin:get-configuration()
(: Get all of the existing databases :)
let $ExistingDatabases :=
    for $id in admin:get-database-ids($config)
       return admin:database-get-name($config, $id)
(: Check to see if "Sample-Database" already exists. 
   If not, create new database :)
let $config :=
    if ("Sample-Database" = $ExistingDatabases) 
    then $config
    else  
      admin:database-create(
        $config, 
        "Sample-Database",
        xdmp:database("Security"),
        xdmp:database("Schemas"))
(: Obtain the database ID of Sample-Database :)
let $Sample-Database := admin:database-get-id(
    $config, 
    "Sample-Database")
(: Get all of the forests attached to Sample-Database :)
let $AttachedForests :=
    admin:forest-get-name( 
       $config, 
       (admin:database-get-attached-forests(
          $config, 
          $Sample-Database) ))
(: Check to see if the "SampleDB-Forest" forest is already attached 
   to Sample-Database. If not, attach the forest to the database :)
let $config :=
    if ("SampleDB-Forest" = $AttachedForests) 
    then $config
    else
       admin:database-attach-forest(
          $config,
          $Sample-Database,
          xdmp:forest("SampleDB-Forest"))
(: Define a new range element index :)
let $rangespec := admin:database-range-element-index(
    "string", 
    "http://marklogic.com/wikipedia",
    "name", 
    "http://marklogic.com/collation/",
    fn:false() )
(: Get the existing range element indexes for Sample-Database :)
let $ExistingREindexes :=
    fn:data(admin:database-get-range-element-indexes(
      $config, 
      $Sample-Database)/xdmpdb:localname)
(: Check to see if the name range element index already exists 
   for "Sample-Database". If not, add the index :)
let $config :=
    if ("name" = $ExistingREindexes) 
    then $config
    else 
       admin:database-add-range-element-index(
          $config, 
          $Sample-Database, 
          $rangespec)
return
   admin:save-configuration($config)

When Separate Transactions are Needed

There are cases where you must make configuration changes in separate transactions. If you are creating a new object that is to be used by another object, each task must be done in a separate transaction. For example, to create a forest and attach it to a database, you must first create the forest and save the configuration in one transaction, then attach the forest to the database and save the configuration in a separate transaction. Similarly, if you are deleting an object and then deleting an object that uses that object, the deletes must occur and the configuration must be saved in separate transactions.

You can define separate transactions in a single module by separating the transactions with semi-colons. Alternatively you can create separate modules for each transaction or execute each admin create/delete function using a different-transaction isolation of an xdmp:eval or xdmp:invoke.

Specifically, for the following functions, the forest/database/group must first exist or be deleted/reassigned before calling the function or an exception is thrown:

See Sequence for Creating Server and Security Objects and Sequence for Deleting Server and Security Objects for the specific order in which objects should be created and deleted. For details on transactions, see Understanding Transactions in MarkLogic Server in the Application Developer's Guide.