Update collection settings #

Update the collection-level settings of an existing collection. The change is applied through the Raft-replicated metadata request, so it survives restarts and reaches every node.

Examples #

Change the default replica count used for newly allocated rollings:

PUT /my-collection/_settings
{
  "rolling": { "number_of_replicas": 2 }
}

Restrict the collection’s shard copies to two nodes:

PUT /my-collection/_settings
{
  "routing": {
    "allocation": {
      "include": { "_id": "node-a,node-b" }
    }
  }
}

The API returns the following result:

{
  "acknowledged": true,
  "collection": "default:my-collection",
  "number_of_replicas": 2
}

Request #

PUT /[<namespace>:]<name>/_settings

Path Parameters #

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

Request body #

• rolling.number_of_replicas
  (Optional, integer, max 32) The collection-level default replica count used when a new rolling is allocated (by automatic rollover or by Roll over a collection). Existing rollings keep their current shards — changing the replica count of an existing rolling requires Update rolling settings.
• routing.allocation
  (Optional, object) The shard-routing policy (total_shards_per_node, include._id, exclude._id — see Create a collection for the format). It applies to every placement decided afterwards, and the allocation service relocates existing replica copies that violate the new policy. Primaries are never relocated in place; roll over to spread them.

An empty update (neither key present) is rejected with 400, as is a replica count that equals the current one with nothing else to change.