Collection

Create a collection #

Creates a new collection.

Examples #

The following request creates a new collection called my-collection in the namespace my-namespace:

PUT /my-namespace:my-collection

If creating a collection within the default namespace, it can be simplified as:

PUT /my-collection

Request #

PUT /[<namespace>:]<name>

Path parameters #

<namespace>
(Optional, string) The namespace which the collection belongs to. Namespace names must meet the following criteria:
- Lowercase only
- Cannot include \ /, *, ?, ", <, >, |, , ,, #
- Cannot start with -, _, +
- Cannot be . or ..
- Cannot be longer than 255 bytes (note it is bytes, so multi-byte characters will count towards the 255 limit faster)
<name>
(Required, string) Name of the collection you wish to create. Collection names must meet the same criteria as namespace names.

Query parameters #

<wait_for_active_shards> \
...

Delete a collection #

Delete an existing collection.

Examples #

The following request deletes the collection called my-collection:

DELETE my-collection

Request #

DELETE /[<namespace>:]<name>

Path Parameters #

<namespace>
(Optional, string) The namespace which the collection belongs to.
<name>
(Required, string) Name of the collection you wish to delete.

Get collection #

Returns information about one or more collections.

Examples #

The following request gets all the collections under the default namespace:

GET /default:*

Request #

GET /<target>

Path Parameters #

target
(Required, String) Comma-separated, names of the collections to get (wildcard supported)

Response #

One entry per collection, keyed by its namespace:collection name. Each entry combines the schema, settings, index definitions and rollings:

...

Update collection schema #

Apply an additive schema diff (new or updated field definitions) to an existing collection. The change is replicated through Raft and every shard engine of the collection picks it up.

Field deletion is not supported by design — a schema diff can only add or update properties.

Examples #

Add a title text field and a non-indexed user.name keyword field to the collection my-collection:

...

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:

...

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.

...

Flush a collection

/ Flush, / Collection

Flush a collection #

Queue a flush of every live shard copy of the collection, cluster-wide — primaries and started replicas. A flush seals the shard’s mutable state into the WAL and builds a new immutable .fire segment from the WAL tail, turning in-memory writes into durable segment storage so the WAL can be purged afterwards.

Both a flush and a Compact a collection request queue node-local jobs that run asynchronously — the request returns as soon as the jobs are queued. Track or cancel them on the node’s task list (GET /_node/_local/tasks): flush jobs under flush_jobs, compaction under compaction_tasks[]. Only one flush job runs per node at a time — a node already running one answers 409 in its row. The difference is what the job does: compaction merges existing immutable segments, a flush seals the mutable tail into a new one.

...

Roll over a collection

/ Rolling, / Collection

Roll over a collection #

Allocate a new rolling for the collection now, regardless of whether the active rolling is full — subsequent writes go to the new rolling. This is the manual form of the automatic rollover that happens when a rolling reaches its document capacity.

The change is replicated through Raft (the same metadata request used by automatic rollovers), so the shard groups of the new rolling are created on every node.

...