MarkLogic 12 Product Documentation

POST /manage/v2/forests

Summary

Create a new forest, including replicas if specified. If a database id or database is included, attach the new forest(s) to the database. For an example, see Preliminary Configuration Procedures in the Scripting Administrative Tasks Guide.

Response

Upon successful completion, MarkLogic Server returns status code 201 (Created).

Required Privileges

• the manage-admin role
• the following privileges:

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

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

• 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 payload can specify either replica forests or failover hosts, but not both. If replicas are specified in the POST body, then replication is enabled by default.

Newly created forests are enabled by default.

Setting range boundaries for the forest in the POST body does not modify the configuration of the database to which the forest is attached.

The structure of the data in the POST body is shown below. You must include at least forest-name and host. If replicas are included, the configuration data for each replica must include at least replica-name and host.

Note: The properties described here are for XML payloads. In general they are the same for JSON, with the exception that, in JSON, failover-hosts and forest-replicas are expressed in singular form. For example, in JSON, failover-hosts is instead failover-host and the format is: "failover-host":["hostname"].

The data in the POST body must be valid according to the schema type "forest-properties" in the "manage-forest-properties.xsd" schema. JSON payloads are internally converted to XML before validation.

forest-name

The forest name.

host

A host name or id.

database

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.

availability

Availability of the forest data.

rebalancer-enable

Enable automatic rebalancing after configuration changes.

range

Range configuration for the range assignment policy.

This is a complex structure with the following children:

lower-bound

The lower bound of the range on the forest.

upper-bound

The upper bound of the range on the forest.

failover-hosts

A list of hosts for shared disk failover.

This is a complex structure with the following children:

failover-host

A host name or id for shared disk failover.

failover-enable

Enable assignment to a failover host if the primary host is down.

forest-backups

Backups scheduled for this forest.

This is a complex structure with the following children:

forest-backup

A scheduled forest backup.

This is a complex structure with the following children:

backup-id

The backup ID.

backup-enabled

Whether or not a backup is enabled

backup-directory

The backup directory pathname.

backup-type

What type of backup is this.

backup-period

How often this backup should run (every n months, weeks, days, hours or minutes).

backup-month-day

The day of the month that this backup happens.

backup-days

The days that this backup happens.

This is a complex structure with the following children:

backup-day

A day that this backup occurs.

backup-start-date

The starting date (in MM/DD/YYYY notation) for a one-time backup

backup-start-time

The starting time (in 24:00 notation).

backup-timestamp

The date and time this backup was created.

forest-replicas

Replica forest definitions.

This is a complex structure with the following children:

forest-replica

Replica forest definition.

This is a complex structure with the following children:

replica-name

Name of the replica forest.

host

A host name or id.

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.

database-replication

updates-allowed

The kinds of updates that should be allowed for this forest.

enabled

Forest enabled status.

Example

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

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

==> Create a forest named "example-1" on host "my-host". MarkLogic Server
    responds with output similar to the following. You can use the
    reference in the Location header to retrieve status and other 
    information about the new forest.

HTTP/1.1 201 Created
Location: /manage/v2/forests/2721944172534009539
Content-type: application/xml
Cache-Control: no-cache
Expires: -1
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
    

Example

$ cat forest-create.json
==> 
{
  "forest-name": "example-2",
  "host": "my-host",
  "database": "Documents"
}

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

==> Create a forest named "example-2" on host "my-host", and attach it
    to the Documents database. MarkLogic Server responds with headers 
    similar to the following. You can use the reference in the Location 
    header to retrieve status and other information about the new forest.

HTTP/1.1 201 Created
Location: /manage/v2/forests/2721944172534009539
Content-type: application/xml
Cache-Control: no-cache
Expires: -1
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
    

Example

$ curl --anyauth --user admin:admin -X POST \
-d '{"forest-name": "Documents", "host": "host-1.marklogic.com", "database": "Master", \
"forest-replicas": {"forest-replica":[{"replica-name": "Documents-R", "host": "host-3.marklogic.com"}]}}' \
-i -H "Content-type: application/json" http://localhost:8002/manage/v2/forests

==> Creates a "Documents" forest on "host-1" with a "Documents-R" replica forest
    on "host-3."  Note that both hosts must be in the same cluster.