MarkLogic Server 11.0 Product Documentation

admin:forest-rename

admin:forest-rename(
   $config as element(configuration),
   $forest-id as xs:unsignedLong,
   $new-name as xs:string
) as element(configuration)

Summary

This function renames a forest.

Required Privileges

http://marklogic.com/xdmp/privileges/admin/database

http://marklogic.com/xdmp/privileges/admin/database/{id}

http://marklogic.com/xdmp/privileges/admin/forest

http://marklogic.com/xdmp/privileges/admin/forest/{id}

Usage Notes

The admin:forest-rename() function returns immediately, but the rename operation runs asynchronously in the background. Use this function for routine administrative work, such as correcting a forest name after initial setup or handling small cleanup tasks.

For production clusters, the safer approach is usually to:

1. Create a new forest with the correct name.
2. Attach the new forest to the database.
3. Retire the old forest.
4. Allow the rebalancer to move documents.
5. Detach and delete the old forest.

This method helps avoid unnecessary rebalancing churn and reduces the risk of leaving the cluster in an inconsistent state.

For local-disk failover, if renaming a primary forest with replication is unavoidable:

1. Restart or disable the primary forest while the replica is in sync to trigger failover.
2. Wait for the replica to become the active primary (see Forest Mount States).
3. If you disabled it, re-enable the original primary forest.
4. Rename the original primary forest.
5. Restart or disable the acting primary forest to complete the switchback.
6. (Optional) If disabled, re-enable the replica forest.
7. (Optional) Rename the replica forest to match your naming convention.

Before applying either approach:

• Back up database data and export relevant cluster configuration.
• Record current forest order (see database replication forest order guidance).
• Test the change in a representative lower environment.
• Apply changes in small batches and monitor health (for example, Checking the Rebalancer Status).

Example

xquery version "1.0-ml";

import module namespace admin = "http://marklogic.com/xdmp/admin"
      at "/MarkLogic/admin.xqy";

let $config := admin:forest-rename(admin:get-configuration(), 15096846875773626521, "blah")
return admin:save-configuration($config)

   => returns the new configuration element -- use admin:save-configuration
      to save the changes to the configuration or pass the configuration
      to other Admin API functions to make other changes.