MarkLogic 9 Product Documentation

PUT /manage/v2/forests

Summary

Perform an operation on one or more forests, such as combining multiple forests into a single new one, or migrating the data in the forests to a new data directory.

Response

Upon successful completion, MarkLogic Server returns status code 202 (Accepted) and ticket information you can use to check on the operation status.

Required Privileges

• the manage-user role
• the following privilege:

  http://marklogic.com/xdmp/privileges/manage

• the manage role plus one of the following granular privileges:
  • http://marklogic.com/xdmp/privileges/admin/forest
  • http://marklogic.com/xdmp/privileges/admin/forest/forest-ID

Usage Notes

The operation performed by the request is determined by the wrapper element name in XML or the value of the operation key in JSON. The following operations are supported: forest-combine and forest-migrate.

The operations performed by this request are asynchronous. If your request is accepted, MarkLogic Server returns ticket information that can be used with GET /manage/v2/tickets to check on the status and eventual outcome of your request.

The forest-combine operation combines multiple forests into one new forest. The source forests are required to be either all in "open" or "open-replica" state or all in "sync replicating" state. If a forest's state changes during the combine operation, an error may be thrown. If all source forests are in "open" or "open replica" state and are all attached to a database, the combined forest will be attached to the database and the source forests (or their masters) detached to the database.

For the forest-combine operation, you must include the list of forests to combine (forest), the destination forest name (forest-name), and the host of the destination forest (host). In JSON, define the operation by setting operation to "forest-combine".

The forest-migrate operation moves data in one or more forests to new data directories and optionally sets a new host for the destination.

For the forest-migrate operation, you must include the list of forests to migrate (forest) and the destination host. In JSON, define the operation by setting operation to "forest-migrate".

For both operations, you can optionally specify data-directory, large-data-directory, fast-data-directory, and options. For a list of options, see tieredstorage:forest-combine or tieredstorage:forest-migrate.

For details, see Common Forest and Partition Operations in the Administrator's Guide.

The data in the request body for forest-combine has the following structure. The structure for forest-migrate is similar, except it does not include forest-name.

forests

This is a complex structure with the following children:

forest

A host forset or id.

host

A host name or id.

forest-name

The forest name.

data-directory

The optional public directory for forests.

large-data-directory

The optional directory for large objects in a forest.

fast-data-directory

The optional smaller but faster directory for forests.

options

A list of options.

This is a complex structure with the following children:

option

An option.

Example

$  cat forest-combine.xml
==> 
<forest-combine xmlns="http://marklogic.com/manage">
  <forests>
    <forest>example-1</forest>
    <forest>example-2</forest>
  </forests>
  <forest-name>new-forest</forest-name>
  <host>my-host</host>
</forest-combine>

$ cat forest-combine.json
==> 
{
  "operation": "forest-combine",
  "forest": [ "example-1", "example-2" ],
  "forest-name": "new-forest",
  "host": "my-host"
}

$  curl --anyauth --user user:password -X PUT -d @./forest-combine.xml \
     -i -H "Content-type: application/xml" \
     http://localhost:8002/manage/v2/forests

==> Combine forests example-1 and example-2 into a new forest named
    "new-forest" on my-host. MarkLogic Server responds with output
    similar to the following. This is an asynchronous operation. To
    check the status or outcome, use the reference in the Location header
    or the uriref.

HTTP/1.1 202 Accepted
Location: /manage/v2/tickets/6699732791380391489?view=process-status
Content-type: application/xml
Cache-Control: no-cache
Expires: -1
Server: MarkLogic
Content-Length: 218
Connection: Keep-Alive
Keep-Alive: timeout=5

<forest-combine>
  <link>
    <kindref>process-status</kindref>
    <uriref>/manage/v2/tickets/6699732791380391489?view=process-status</uriref>
  </link>
  <message>Monitor operation progress by viewing ticket</message>
</forest-combine>

$ curl --anyauth --user user:password -X GET -i -H "Accept: application/xml" \
    http://localhost:8002/manage/v2/tickets/6699732791380391489?view=process-status

==> MarkLogic Server returns the status of this forest-combine operation.
    For details, see GET /manage/v2/tickets/{id}.

<ticket-process-status xmlns="http://marklogic.com/manage/tickets">
  <id>6699732791380391489</id>
  ...
  <status-properties>
    <status>completed</status>
    <start-time>2013-09-21T12:02:54.866173-07:00</start-time>
    <ticket-expiration>2013-09-28T12:02:54.866173-07:00</ticket-expiration>
    <database>App-Services</database>
    ...
    <time-consumed>PT41.128523S</time-consumed>
    <errors>0</errors>
    ...
  </status-properties>
  ...
</ticket-process-status>
  

Example

$  cat forest-migrate.xml
==> 
<forest-migrate xmlns="http://marklogic.com/manage">
  <forests>
    <forest>example-1</forest>
    <forest>example-2</forest>
  </forests>
  <host>my-host</host>
</forest-combine>

$ cat forest-migrate.json
==> 
{
  "operation": "forest-migrate",
  "forest": ["example-1", "example-2"],
  "host": "my-host"
}

$  curl --anyauth --user user:password -X PUT -d @./forest-migrate.xml \
     -i -H "Content-type: application/xml" \
     http://localhost:8002/manage/v2/forests

==> Migrate forests example-1 and example-2 to "my-host". MarkLogic
    Server responds with output similar to the following. This is 
    an asynchronous operation. To check the status or outcome, use the 
    reference in the Location header or the uriref.

HTTP/1.1 202 Accepted
Location: /manage/v2/tickets/6699732791380391489?view=process-status
Content-type: application/xml
Cache-Control: no-cache
Expires: -1
Server: MarkLogic
Content-Length: 218
Connection: Keep-Alive
Keep-Alive: timeout=5

<forest-migrate>
  <link>
    <kindref>process-status</kindref>
    <uriref>/manage/v2/tickets/6699732791380391489?view=process-status</uriref>
  </link>
  <message>Monitor operation progress by viewing ticket</message>
</forest-migrate>