MarkLogic 10 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. :)

MarkLogic 10 Product Documentationtieredstorage:forest-combine

Summary

Usage Notes

Example

MarkLogic 10 Product Documentation
tieredstorage:forest-combine