Compact a collection #

Queue one manual compaction (merge) pass on every started primary copy of the collection, cluster-wide. Useful when you want to reclaim disk space or reduce the segment count on demand, without waiting for the background compaction cadence.

The API is asynchronous: it fans out to at most one request per node hosting a started primary, and each node queues its own batch compaction job (one job per node, mutual exclusion — HTTP 409 from that node’s row while one runs). The request returns as soon as the jobs are queued; a pass can run for minutes, so nothing waits for the merges. Per-shard job state and live merge progress (phase, per-mille) are observable in each node’s task view, and a job is cancellable there too. A node-level failure fails that node’s row, not the whole request.

Examples #

The following request compacts the collection called my-collection:

POST /my-collection/_compact

The API returns the following result:

{
  "collection": "default:my-collection",
  "nodes": [
    {
      "node_id": "…",
      "job_id": "5f2c…",
      "queued": 3
    }
  ],
  "queued": 3,
  "failed": 0
}

Request #

POST /[<namespace>:]<name>/_compact

Path Parameters #

• <namespace>
  (Optional, string) The namespace which the collection belongs to.
• <name>
  (Required, string) Name of the collection to compact.

Response #

• nodes — one row per hosting node: node_id plus either job_id and queued (how many local primary shard passes the node’s job covers) or an error string when queuing on that node failed (for example a job already running there, or the node did not answer).
• queued — the total shard passes queued across all nodes.
• failed — how many node rows carry an error.

Only started primaries are compacted — followers never merge (compaction products arrive via segment distribution). The endpoint is not gated by the node-level compaction_paused setting, which only holds background compaction passes. The request answers 409 when the collection has no started primary shard copy at all.

Observing and cancelling #

Progress lives server-side and survives a client disconnect or page refresh. On each hosting node (directly, or via the per-node forward GET /_node/<node_id>/tasks):

• compaction_jobs[] — the batch jobs: per-shard rows (Queued → Merging → Done | Failed | Cancelled, merged_files, error, duration) plus per-state totals.
• compaction_tasks[] — the per-shard-copy registry: the live merge’s phase and completion per-mille while a merge runs.

Cancel a running job with POST /_node/<node_id>/tasks/compact/<job_id>/cancel: rows not yet dispatched are skipped (Cancelled), and a pass already parked on the engine’s manual compact lane or a merge already running is signalled to unwind at its next progress boundary.

The web console surfaces the same flow: the collection’s Storage page queues the jobs and streams both feeds, and each node’s Tasks tab shows the batch compaction jobs alongside the per-shard merges.