Index overview
How collection indexing actually works — configuration, build, and activation.
Index overview
An index is what makes search fast on a large collection — an ANN (approximate nearest neighbour) structure built over a collection's vectors, instead of scanning every record.
Collection created (exact search — no index yet)
↓
Configure/build an index — hnsw, ivf, or bq
↓
Build runs (asynchronous — status: "building")
↓
Active index serves searches (status: "active")
A collection with no index still works — Vector search just does an exact (brute-force) scan. Building an index is an optimization, not a prerequisite.
Two different scopes — don't confuse them
The contract exposes indexing at two levels, and they answer different questions:
| Node index config | Collection index state | |
|---|---|---|
| Scope | The whole node | One collection |
| Answers | Legacy/global reporting only — index_type is always "collection_scoped" on current nodes | What's actually active, building, or failed for this collection |
| Buildable kinds | brute, bruteforce, hnsw, ivf, bq, auto, mstg (via project-wide rebuild) | hnsw, ivf, bq only (via Configure a collection's index) — brute/auto are project-level selections, not buildable per-collection structures |
If you're asking "what index does collection X have right now," the answer is always Collection index state — never the node-level config endpoint.
desired vs. active vs. status
Collection index state returns three related fields that describe a build in progress, not just a static config:
desired_type— what was asked for.active_type— what's actually serving searches right now.status— the lifecycle state of the active-or-building generation.
In standalone mode these settle to the same value once a build finishes.
In cluster mode, desired_type is cluster-wide (from the Raft-replicated
spec) while active_type/status are this specific node's local state —
they can genuinely differ while a build propagates across replicas.
Two ways to build
- Configure a collection's index
— single collection, asynchronous (
202, poll for completion), doesn't block writes to other collections. - Rebuild all indexes — every collection at once, synchronous, holds the write lock for its entire duration. Reach for this only when you specifically need a project-wide rebuild; the per-collection endpoint is the normal path.