Rebalance Based on File Transfer

The Search-Service REST API configures rebalance based on file transfer.

HTTP Method and URI

PUT /api/managerOptions

Description

The Search Service automatically partitions its indexes across all Search nodes in the cluster, ensuring optimal distribution, following rebalance.

To achieve this, in versions of Couchbase Server prior to 7.1, by default, partitions needing to be newly created were entirely built, on their newly assigned nodes. In 7.1+, by default, new partitions are created by the transfer of partition files from old nodes to new nodes: this significantly enhances performance. This is an Enterprise-only feature, which requires all Search Service nodes either to be running 7.1 or later; or to be running 7.0.2, with the feature explicitly switched on by means of this endpoint. Note that users of 7.1+ can explicitly switch the feature off by means of this endpoint; in which case partition build is used to establish new partitions, rather than file transfer.

During file transfer, should an unresolvable error occur, file transfer is automatically abandoned, and partition build is used instead.

Curl Syntax

curl -X PUT http://<ip-address-or-domain-name>:8094/api/managerOptions
  -u <username>:<password>
  -H "Content-type:application/json"
  -d '{"disableFileTransferRebalance": [ "true" | "false" ]}'
  -d '{"enableReplicaCatchupOnRebalance": [ "true" | "false" ]}'

If the value specified for the key disableFileTransferRebalance is false (which is the default in 7.1+), new Search-Service partitions are created during rebalance by means of partition-file transfer. If the value is true, partitions are created by means of partition build, from scratch; over DCP connections from the Data Service.

If you set enableReplicaCatchupOnRebalance to true, Couchbase Server tracks its progress when copying FTS replica index partitions during a rebalance. This option only has an effect when disableFileTransferRebalance is false. It tracks its progress by comparing the sequence numbers of the partitions it has copied with the partition sequence numbers on the node containing the original partitions. Having Couchbase Server track its progress helps prevent problems such as rollbacks in later rebalance operations. Couchbase Server automatically tracks its progress using this method when copying active partitions. When enableReplicaCatchupOnRebalance is the default value of false, Couchbase Server does not monitor its progress when copying replica partitions. This setting reduces the overhead of a rebalance. However it can result in some replica partitions being only partially rebuilt.

Enabling enableReplicaCatchupOnRebalance impacts performance due to the added overhead of monitoring the progress of copying replica partitions.

Responses

Success returns 200 OK, and the message {"status":"ok"}. If the URI is incorrectly specified, 404 Object Not Found is returned. If the method is incorrectly specified, 405 Method Not Allowed is returned, with the message {"error":"Method not allowed for endpoint","status":"fail"}.

Failure to authenticate returns 401 Unauthorized.

Examples

The following example disables the creation of new partitions by means of file-transfer:

curl -X PUT http://localhost:8094/api/managerOptions \
-u Administrator:password \
-H "Content-type:application/json" \
-d '{"disableFileTransferRebalance": "true" }'

From this point, Search-Service index-partitions are built on the new nodes assigned to them during rebalance.

The following example re-enables the creation of new partitions by means of file-transfer:

curl -X PUT http://localhost:8094/api/managerOptions \
-u Administrator:password \
-H "Content-type:application/json" \
-d '{"disableFileTransferRebalance": "false" }'

From this point, Search-Service index-partitions are again created by file transfer, on the new nodes assigned to them during rebalance.

In each case, successful execution returns the following:

{"status":"ok"}