MarkLogic Server 11.0 Product Documentation

Forest Configuration Help

A Forest is where a database stores its content and indexes. A database can have multiple forests.

A Forest consists of Stands. Each Stand is a set of XML fragments, and is implemented by a set of compressed binary files contained within a sub-directory of the forest directory.

The following are the configuration parameters for each forest:

• forest name is the name of the forest. The forest name must be a legal directory name and cannot contain any of the following 9 characters: \ * ? / : < > | ". Additionally, the name cannot begin or end with a space or a dot (.).
• host specifies the host on which the forest resides.
• data directory specifies a public directory in which the forest is located. If the data directory is not specified, the forest will be created in the default forest directory on the host machine and the specified host machine cannot be changed once the forest is created.
• large data directory specifies a directory in which large objects are stored. If the directory is not specified, large objects will be stored under the data directory.
• fast data directory specifies a directory that is smaller but faster than the data directory. The directory should be on a different storage device than the data directory. If specified, transaction journals and stands will be stored under this directory. When the directory becomes full, larger stands will be merged into the data directory. It is best to use fast solid state device (SSD) storage for this directory (for example, a PCI card that uses I/O accelerator technology). If multiple forests on the same host share the same fast data directory, the fast data directory for each forest will be allocated a portion of the size of the fast data directory; for example, if you have four forests on one host all configured to use the same 250GB SSD, then each forest will be allowed up to 62.5GB. When the size of the fast data directory approaches that limit, then stands are created in the data directory. The limit can also be set explicitly with the fast data max size configuration parameter.
• fast data max size specifies the maximum allowable size, in megabytes, of of the data to be kept by this forest in the fast data directory. The server limits the size allocated to this forest to a portion of the fast data directory. This limit is normally automatically calculated from the size of the fast data directory and the number of forests using it. When this parameter is not zero, it overrides the calculated limit. The default is zero. Recommended values are in the range of 16384 to 32768.
• updates allowed specifies which operations are allowed on this forest:
  • All specifies that read, insert, update, and delete operations are allowed on the forest.
  • delete-only specifies that read and delete operations are allowed on the forest, but insert and update operations are not allowed unless a forest ID is specified, in which case it results in the document being moved to another forest. Updates to a delete-only forest without specifying a forest ID throw an exception; updates to a delete-only forest that specify the forest ID of one or more forests that allow updates will result in the document being moved to one of the specified forests.
  • read-only specifies that read operations are allowed on the forest, but insert, update, and delete operations are not allowed. A transaction attempting to make changes to fragments in the forest will throw an exception.
  • flash-backup puts the forest in read-only mode without throwing exceptions on insert, update, or delete transactions, allowing the transactions to retry.
• availability of forest data, for use in Tiered Storage.
• rebalancer enable specifies whether rebalancing are automatically performed in the background after configuration settings are changed. When set to true, configuration changes automatically initiate a background rebalancing operation on this forest.
• range specifies the partition key range assigned to this forest, when the rebalancer with the range assignment policy is set for the database. The range settings are:
  • lower bound specifies the lower bound of the range for this forest.
  • upper bound specifies the upper bound of the range for this forest.
• partition number specifies which partition this forest belongs to when query assignment policy is used.
• failover enable indicates if this forest is set up for failover. To enable failover on a host, you must have the failover option enabled in your license key. Additionally, you must manually specify a data directory when you first create the forest; failover is not available in the default forest directory. To enable failover, specify a data directory that is on a storage area network (SAN). Then click true for the failover enable button, and specify the failover host(s).
• failover hosts specifies the host(s) used for shared-disk failover for this forest. You can specify one or more failover hosts for the forest, up to the number of hosts available in the cluster. When a forest fails over, it will first attempt to fail over to the first host in the list, and then if that is not successful, move to the next one, and so on. You cannot specify failover hosts if you have specified any forest replicas; you must choose between local-disk and shared-disk failover.
• forest replicas specifies the forest(s) used for local-disk failover for this forest. You can specify one or more replica forests for the forest. Only forests that are not attached to a database are listed to be used for replicas. Each replica forest maintains a fully replicated version of the forest. When a forest fails over, it will first attempt to fail over to the first replica in the list, and then if that is not successful, move to the next one, and so on. You cannot specify forest replicas if you have specified any failover hosts; you must choose between local-disk and shared-disk failover. Adding or removing replica forests will restart/unmount the primary content forest.

---

Buttons and Tabs:

• The merge button on the Forest Configuration page initiates a merge for the forest.
• The clear button on the Forest Configuration page deletes all the data stored in the forest permanently but preserves the forest configuration information.
• The delete button on the Forest Configuration page deletes the forest configuration information and all the data stored in the forest permanently.
• The disable button disables this forest, which marks the forest as disabled, unmounts the forest from the database, and clears all memory caches for all the forests in the database. The database remains unavailable for any query operations while any of its forests are disabled.
• The Summary tab lists information about all of the current forest configurations, as well as the current state of each forest. Additionally, you can attach a forest to a database or change the database to which a forest is attached by selecting the database drop-down list for one or more forests, selecting a new database, and clicking the OK button.
• The Status tab displays current information for the specified forest, including forest size, fragment information, and other current statistics about the forest. The Status tab also has a restart button, which forces the forest to go offline. Once the forest has gone offline, it will automatically attempt to rejoin the host, thus restarting the forest. There is a show reindex button that is only available when reindexing is disabled on the database. When you click the show reindex button, the page displays information about what would be reindexed if you enable reindexing for the database; the button is greyed out when reindexing is enabled (and if reindexing is in progress, the page shows reindexing activity).
• The Backup/Restore tab is for performing forest-level backup and restore operations.
• backup directory is the directory to which a forest is backed up, or from which a previously backed up forest is restored.
• Backup will copy all files for a given forest to the specified backup directory.
• Restore will restore all files for a given forest from the specfied directory, where it was previously backed up.
• The Create tab is for creating a new forest.