Reshard a rolling #

Change the number of shards of a rolling, online. Splitting raises the shard count (finer partition ranges, e.g. 1 → 2); merging lowers it (e.g. 2 → 1).

The reshard builds a hidden target rolling while the source keeps serving every read and write. Existing documents are streamed into the target with their _id preserved, the write tail is replayed until the target converges, and a single metadata commit then swaps the target in atomically. Documents stay addressable under the same _id and _key throughout, including for writes issued while the reshard is building.

Start a reshard #

POST /my-collection/_rolling/0/_reshard
{
  "number_of_shards": 2
}

The API returns as following result:

{
  "acknowledged": true,
  "state": "building",
  "number_of_shards_before": 1,
  "number_of_shards_after": 2,
  ...
}

Path parameters #

• <target>
  (Required, string) Name of the collection to target.
• <rolling_id>
  (Required, integer) The rolling to reshard.

Request body #

• number_of_shards
  (Required, integer) The shard count to change to. Must differ from the current shard count.

The request is rejected with 400 when number_of_shards equals the current shard count or is out of range, when another reshard of the same rolling is already in progress, or when the deployment’s WAL configuration does not support resharding. An unknown rolling returns 404.

Get reshard status #

GET /my-collection/_rolling/0/_reshard

The API returns as following result:

{
  "acknowledged": true,
  "collection": "default:my-collection",
  "rolling_id": 0,
  "state": "building",
  "phase": "catching_up",
  "shards": [
    {
      "id": "04ffe003da1e4fcab235",
      "phase": "catching_up",
      "detail": "..."
    }
  ],
  ...
}

• state is building while the hidden target converges, and committed_draining after the atomic swap, while the final write tail is being drained.
• phase reports the worst phase across the target’s primaries: waiting_for_engine, bulk_snapshot, catching_up, ready, draining, done, or draining overall once the commit landed.

Returns 404 when no reshard is in progress for the rolling.

Get reshard events #

The lifecycle event feed (“related log”) of this rolling’s most recent reshard, oldest first:

GET /my-collection/_rolling/0/_reshard/_events

The API returns the following result:

{
  "acknowledged": true,
  "collection": "default:my-collection",
  "rolling_id": 0,
  "events": [
    { "ts_millis": 1700000000123, "shard": "04ffe...", "message": "..." },
    ...
  ]
}

Events are recorded by the nodes that run the workers (the target’s primaries), the leader (coordinator milestones) and the handling node (user actions); the response merges and orders all of them by timestamp.

The endpoint always answers 200 — an empty list means no reshard ran since startup, and a finished reshard’s event ring survives (it is cleared only when the next reshard of the same rolling starts), so you can keep inspecting what happened after the fact.

Cancel a reshard #

POST /my-collection/_rolling/0/_reshard/_cancel

The API returns as following result:

{
  "acknowledged": true,
  "state": "cancelled",
  ...
}

Cancellation is only possible while the reshard is still building; the source rolling serves traffic untouched and the hidden target is discarded. Once the commit swapped the target in, the reshard is irreversible and cancel returns 400 (as it does when no reshard is running).