Loading TOC...
JavaScript tieredstorage.forestCombine

MarkLogic Server 11.0 Product Documentation
tieredstorage:forest-combine

tieredstorage:forest-combine(
   $forest-ids as xs:unsignedLong*,
   $forest-name as xs:string,
   $host-id as xs:unsignedLong,
   [$data-directory as xs:string?],
   [$large-data-directory as xs:string?],
   [$fast-data-directory as xs:string?],
   [$options as xs:string*]
) as empty-sequence()

Summary

This function combines data in multiple forests into one new forest. If no data directory is specified, the default data directory is used. 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 details, see Combining Forests in the Administrator's Guide.

Parameters
forest-ids IDs of the forests to be combined.
forest-name Name of the combined forest.
host-id ID of the destination host.
data-directory The optional data directory of the forest. If no directory is specified, then it will be a private forest.
large-data-directory The optional directory where large objects are stored. If no directory is specified, then large objects will be stored in DATA_DIR/Forests/FOREST_NAME/Large.
fast-data-directory The optional directory for the fast data directory for this forest. The fast data directory is typically located on a fast storage device, such as an SSD.
options Valid option values include: 
timeout=N
Specifies the number of seconds to wait for a forest to re-open after a change requiring the forest to close and re-mount is made during the migration operation. 
local-to-local
Indicates that the migration is between local storage to local storage. This is the default when no other direction parameter is specified and the type of storage cannot be derived from either the data directory path. 
local-to-shared
Indicates that the migration is between local storage and shared storage. This type of migration supports changing the host. 
shared-to-local
Indicates that the migration is to move data from shared storage to local storage. This type of migration supports changing the host. 
shared-to-shared
Indicates that the migration is to move data from shared storage to shared storage. This type of migration supports changing the host. 
keep-source-forests
Specifies to keep source forests after the combined forest is created. By default, the source forests are removed before the combine function returns. The source forests will not be removed when this option is turned on. This option can be used to combine forests associated with other forests as masters or replicas. 
snapshot
Specifies to create a combined forest based on a consistent snapshot of the source forests. The source forests will not be removed when this option is turned on. This option can be used to combine replica forests.

Usage Notes

If the forests reside in a database configured for database replication, you must specify the snapshot option when combining forests with overrides. Otherwise an TS-FORESTHASOVERRIDE exception will be thrown.

Example

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

ts:forest-combine(
   (xdmp:forest("Forest1"), xdmp:forest("Forest2")),
   "ForestCombined",
   xdmp:host(), 
   "/tmp/test")
 
(: Combines Forest1 and Forest2 into a single forest, named ForestCombined, in
   the /tmp/test data directory. :)

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.