BUCKET.INDEX

Manages indexes on bucket fields. Indexes speed up queries by allowing efficient lookups on specific fields.

Subcommands

Subcommand	Description
CREATE	Create a new index on one or more fields.
LIST	List all indexes on a bucket.
DESCRIBE	Get detailed information about an index.
DROP	Drop an existing index.
TASKS	List background maintenance tasks for an index.
ANALYZE	Trigger index statistics analysis.

---

BUCKET.INDEX CREATE

Creates one or more indexes on bucket fields.

Syntax

BUCKET.INDEX CREATE <bucket> <schema>

Parameters

Parameter	Type	Required	Description
bucket	string	Yes	Name of the target bucket. The bucket must already exist.
schema	JSON	Yes	Index schema defining the fields to index.

Index Schema Format

The schema is a JSON object that can contain single-field indexes, compound indexes, or both:

{
  "<field>": { "bson_type": "<type>" [, "multi_key": true] [, "unique": true] [, "name": "<name>"] },
  "$compound": [ { "fields": [ { "selector": "<field>", "bson_type": "<type>" }, ... ] [, "unique": true] [, "name": "<name>"] } ]
}

Field selectors

Field selectors use dot notation to address nested fields inside documents. Arrays are traversed automatically. When a selector crosses an array, each element is evaluated independently.

Selector	Targets
name	Top-level field name.
address.city	city inside the nested object address.
tags	The tags field itself (use with multi_key for arrays).
orders.total	total inside each element of the orders array.

Example document:

{
  "username": "alice",
  "address": { "city": "Istanbul", "zip": "34000" },
  "tags": ["admin", "editor"],
  "orders": [
    { "total": 120, "status": "shipped" },
    { "total": 45, "status": "pending" }
  ]
}

• Selector address.city reaches "Istanbul".
• Selector tags with multi_key: true indexes each element ("admin", "editor") separately.
• Selector orders.total with multi_key: true indexes each order’s total (120, 45) separately.

Single-field indexes

Each top-level key (other than $compound) is a field selector. The value defines the index properties:

{
  "field_name": {
    "bson_type": "type",
    "multi_key": true|false,
    "name": "optional_custom_name"
  }
}

Property	Type	Required	Description
bson_type	string	Yes	The BSON type of the field values. See Supported BSON Types.
multi_key	boolean	No	When true, creates a multi-key index for array fields. Each array element generates a separate index entry. Default: false.
unique	boolean	No	When true, rejects any document whose value on this field already exists. Cannot be combined with multi_key. Default: false.
name	string	No	Custom name for the index. If omitted, a name is auto-generated from the selector and type.
collation	object	No	Collation spec for locale-aware string ordering. Only valid for string type. See Collation.

Compound indexes

The $compound key holds an array of compound index definitions. Each definition specifies an ordered list of fields:

{
  "$compound": [
    {
      "name": "optional_custom_name",
      "fields": [
        { "selector": "field_a", "bson_type": "string" },
        { "selector": "field_b", "bson_type": "int32", "multi_key": false }
      ]
    }
  ]
}

Each field in the fields array supports:

Property	Type	Required	Description
selector	string	Yes	Dot-notation path to the field.
bson_type	string	Yes	The BSON type of the field values. See Supported BSON Types.
multi_key	boolean	No	When true, creates a multi-key index entry per array element. Default: false.

The compound index definition also supports:

Property	Type	Required	Description
name	string	No	Custom name for the compound index. If omitted, a name is auto-generated.
unique	boolean	No	When true, the combination of all field values must be unique across documents. Cannot be combined with a multi-key field. Default: false.
collation	object	No	Collation spec for locale-aware string ordering. Requires at least one string field. See Collation.

Constraints:

• A compound index must have at least two fields.
• A compound index supports at most 32 fields.
• At most one field can have multi_key enabled.
• A unique compound index cannot contain a multi-key field.
• Each field selector must appear exactly once within a compound index.

See Compound Indexes for detailed rules including the prefix rule and supported operators.

Multi-key Index Behavior

When multi_key is set to true, the index is designed for array fields. Each element in the array creates a separate index entry, allowing queries to match documents where any array element satisfies the condition.

Limitations:

• Undefined ordering: Result ordering is undefined with multi-key indexes. Since each document can have multiple index entries (one per array element), the order in which documents are returned cannot be guaranteed.
• Index size: Multi-key indexes can be significantly larger than regular indexes because each array element creates a separate index entry.
• Type matching: Only array elements matching the specified bson_type are indexed.

Return Value

Returns OK on success.

Errors

Bucket errors:

Error Code	Error message	Cause
NOSUCHBUCKET	No such bucket: '<bucket>'	-
BUCKETBEINGREMOVED	Bucket '<bucket>' is being removed	-

Index errors:

Error Code	Error message	Cause
ERR	An index on field '<field>' already exists	-
ERR	Invalid index schema	-
ERR	Unknown BSON type: <type>	-
ERR	A unique index cannot be multi-key	-

Examples

Create a single-field index:

> BUCKET.INDEX CREATE users '{"username": {"bson_type": "string"}}'
OK

Create multiple indexes at once:

> BUCKET.INDEX CREATE users '{"age": {"bson_type": "int32"}, "email": {"bson_type": "string"}}'
OK

Create an index with a custom name:

> BUCKET.INDEX CREATE users '{"username": {"bson_type": "string", "name": "idx_username"}}'
OK

Create a multi-key index for array fields:

> BUCKET.INDEX CREATE products '{"tags": {"bson_type": "string", "multi_key": true}}'
OK

Create a unique index:

> BUCKET.INDEX CREATE users '{"email": {"bson_type": "string", "unique": true}}'
OK

Index a nested field using dot notation:

> BUCKET.INDEX CREATE users '{"address.city": {"bson_type": "string"}}'
OK

Index elements inside an array of objects:

> BUCKET.INDEX CREATE users '{"orders.total": {"bson_type": "int32", "multi_key": true}}'
OK

Create a single-field index with collation:

> BUCKET.INDEX CREATE users '{
  "username": {
    "bson_type": "string",
    "collation": {"locale": "tr", "strength": 2}
  }
}'
OK

Create a compound index:

> BUCKET.INDEX CREATE products '{
  "$compound": [{
    "name": "idx_cat_price",
    "fields": [
      {"selector": "category", "bson_type": "string"},
      {"selector": "price", "bson_type": "double"}
    ]
  }]
}'
OK

Create a unique compound index:

> BUCKET.INDEX CREATE users '{
  "$compound": [{
    "unique": true,
    "fields": [
      {"selector": "name", "bson_type": "string"},
      {"selector": "age", "bson_type": "int32"}
    ]
  }]
}'
OK

Create a compound index with collation:

> BUCKET.INDEX CREATE products '{
  "$compound": [{
    "fields": [
      {"selector": "category", "bson_type": "string"},
      {"selector": "price", "bson_type": "double"}
    ],
    "collation": {"locale": "en"}
  }]
}'
OK

Create single-field and compound indexes together:

> BUCKET.INDEX CREATE products '{
  "email": {"bson_type": "string"},
  "$compound": [{
    "fields": [
      {"selector": "status", "bson_type": "string"},
      {"selector": "region", "bson_type": "string"}
    ]
  }]
}'
OK

---

BUCKET.INDEX LIST

Lists all indexes defined on a bucket.

Syntax

BUCKET.INDEX LIST <bucket>

Parameters

Parameter	Type	Required	Description
bucket	string	Yes	Name of the bucket.

Return Value

Returns an array of index names.

Errors

Bucket errors:

Error Code	Error message	Cause
NOSUCHBUCKET	No such bucket: '<bucket>'	-
BUCKETBEINGREMOVED	Bucket '<bucket>' is being removed	-

Examples

> BUCKET.INDEX LIST users
1) "primary-index"
2) "selector:username.bsonType:STRING"
3) "selector:age.bsonType:INT32"

---

BUCKET.INDEX DESCRIBE

Gets detailed information about a specific index.

Syntax

BUCKET.INDEX DESCRIBE <bucket> <index>

Parameters

Parameter	Type	Required	Description
bucket	string	Yes	Name of the bucket.
index	string	Yes	Name of the index to describe.

Return Value

Returns a map. The fields depend on the index type.

Single-field index (index_type is single_field):

Field	Type	Description
index_type	string	single_field.
id	integer	Index identifier.
selector	string	The field selector the index is built on.
bson_type	string	The BSON type of indexed values.
status	string	Current index status. See Index Lifecycle.
unique	boolean	Whether the index enforces value uniqueness.
collation	map	Collation configuration (see below). Empty when no collation is set.
statistics	map	Index statistics including cardinality.

Compound index (index_type is compound):

Field	Type	Description
index_type	string	compound.
id	integer	Index identifier.
fields	array	The indexed fields in index order. Each entry is a map with selector and bson_type.
status	string	Current index status. See Index Lifecycle.
unique	boolean	Whether the index enforces value uniqueness.
collation	map	Collation configuration (see below). Empty when no collation is set.
statistics	map	Index statistics including cardinality.

Vector index (index_type is vector):

Field	Type	Description
index_type	string	vector.
id	integer	Index identifier.
selector	string	The field selector the index is built on.
dimensions	integer	The vector length the index accepts.
distance	string	The distance function of the index.
status	string	Current index status. See Index Lifecycle.
statistics	map	Index statistics including cardinality.

Collation sub-fields

Field	Type	Description
locale	string	ICU locale identifier (e.g., "en", "tr").
strength	integer	Comparison strength level (1-5).
case_level	boolean	Whether to include case-level comparisons.
case_first	string	Sort order of case differences ("upper", "lower", "off").
numeric_ordering	boolean	Whether to compare numeric strings as numbers.
alternate	string	Handling of variable-weight characters ("non-ignorable", "shifted").
backwards	boolean	Whether to reverse secondary-level comparisons (for French).
normalization	boolean	Whether to perform Unicode normalization.
max_variable	string	Which characters are ignorable when alternate="shifted" ("punct", "space").

Errors

Bucket errors:

Error Code	Error message	Cause
NOSUCHBUCKET	No such bucket: '<bucket>'	-
BUCKETBEINGREMOVED	Bucket '<bucket>' is being removed	-

Index errors:

Error Code	Error message	Cause
NOSUCHINDEX	No such index: '<index>'	-

Examples

> BUCKET.INDEX DESCRIBE users "selector:username.bsonType:STRING"
index_type -> "single_field"
id -> 2
selector -> "username"
bson_type -> "STRING"
status -> "WAITING"
unique -> (false)
collation -> {}
statistics -> {cardinality -> 0}

RESP2 clients

RESP2 has no map and no boolean type. On a RESP2 connection the reply is a flat array where each field name is followed by its value, unique and the collation flags are sent as 1 or 0, and the nested collation, statistics and compound fields entries become flat arrays too:

> BUCKET.INDEX DESCRIBE users "selector:username.bsonType:STRING"
 1) "index_type"
 2) "single_field"
 3) "id"
 4) (integer) 2
 5) "selector"
 6) "username"
 7) "bson_type"
 8) "STRING"
 9) "status"
10) "WAITING"
11) "unique"
12) (integer) 0
13) "collation"
14) (empty array)
15) "statistics"
16) 1) "cardinality"
    2) (integer) 0

---

BUCKET.INDEX DROP

Drops an existing index from a bucket.

Syntax

BUCKET.INDEX DROP <bucket> <index>

Parameters

Parameter	Type	Required	Description
bucket	string	Yes	Name of the bucket.
index	string	Yes	Name of the index to drop.

Return Value

Returns OK on success. The index is marked as DROPPED and a background task is created to clean up the index data.

Errors

Bucket errors:

Error Code	Error message	Cause
NOSUCHBUCKET	No such bucket: '<bucket>'	-
BUCKETBEINGREMOVED	Bucket '<bucket>' is being removed	-

Index errors:

Error Code	Error message	Cause
NOSUCHINDEX	No such index: '<index>'	-
ERR	Cannot drop the primary index	-
ERR	Index is already in the 'DROPPED' status	-
ERR	Index has active tasks	-

Examples

> BUCKET.INDEX DROP users "selector:username.bsonType:STRING"
OK

Attempting to drop the primary index:

> BUCKET.INDEX DROP users "primary-index"
(error) ERR Cannot drop the primary index

---

BUCKET.INDEX TASKS

Lists background maintenance tasks associated with an index.

Syntax

BUCKET.INDEX TASKS <bucket> <index>

Parameters

Parameter	Type	Required	Description
bucket	string	Yes	Name of the bucket.
index	string	Yes	Name of the index.

Return Value

Returns a map where each key is a task ID and the value contains task details:

For BUILD tasks:

Field	Type	Description
kind	string	Task type (BUILD).
cursor	string	Current position in the build process.
lower	string	Lower bound position.
upper	string	Upper bound position.
status	string	Task status.
error	string	Error message if failed.

For DROP tasks:

Field	Type	Description
kind	string	Task type (DROP).
status	string	Task status.
error	string	Error message if failed.

For BOUNDARY tasks:

Field	Type	Description
kind	string	Task type (BOUNDARY).
status	string	Task status.
error	string	Error message if failed.

For ANALYZE tasks:

Field	Type	Description
kind	string	Task type (ANALYZE).
status	string	Task status.
error	string	Error message if failed.

Errors

Bucket errors:

Error Code	Error message	Cause
NOSUCHBUCKET	No such bucket: '<bucket>'	-
BUCKETBEINGREMOVED	Bucket '<bucket>' is being removed	-

Examples

> BUCKET.INDEX TASKS users "selector:username.bsonType:STRING"
"5K8G4R000000000000000000" -> {
  kind -> "BUILD"
  cursor -> "5K8G4R000000000000000500"
  lower -> "0000000000000000000000000"
  upper -> "5K8G4R000000000000001000"
  status -> "RUNNING"
  error -> ""
}

RESP2 clients

RESP2 has no map type. On a RESP2 connection the reply is a flat array where each task ID is followed by its field list:

> BUCKET.INDEX TASKS users "selector:username.bsonType:STRING"
1) "5K8G4R000000000000000000"
2)  1) "kind"
    2) "BUILD"
    3) "cursor"
    4) "5K8G4R000000000000000500"
    5) "lower"
    6) "0000000000000000000000000"
    7) "upper"
    8) "5K8G4R000000000000001000"
    9) "status"
   10) "RUNNING"
   11) "error"
   12) ""

---

BUCKET.INDEX ANALYZE

Trigger index statistics analysis. Statistics help the query optimizer make better decisions.

Syntax

BUCKET.INDEX ANALYZE <bucket> <index>

Parameters

Parameter	Type	Required	Description
bucket	string	Yes	Name of the bucket.
index	string	Yes	Name of the index to analyze.

Return Value

Returns OK on success. A background task is created to compute index statistics.

Errors

Bucket errors:

Error Code	Error message	Cause
NOSUCHBUCKET	No such bucket: '<bucket>'	-
BUCKETBEINGREMOVED	Bucket '<bucket>' is being removed	-

Index errors:

Error Code	Error message	Cause
NOSUCHINDEX	No such index: '<index>'	-
ERR	An analyze task has already exist	-
ERR	Cannot analyze index: index is not in READY state (current=<status>)	-

Examples

> BUCKET.INDEX ANALYZE users "selector:username.bsonType:STRING"
OK

Errors

Argument errors:

Error Code	Error message	Cause
ERR	unknown subcommand: '<subcommand>'	-

Indexes go through the following states:

Status	Description
WAITING	Index is created but background building has not started yet.
BUILDING	Index is being built by a background task.
READY	Index is fully built and available for queries.
DROPPED	Index is marked for deletion; background cleanup is in progress.
FAILED	Index building failed due to an error.

---

Supported BSON Types

The following BSON types can be indexed:

Type	Description
string	UTF-8 string values.
int32	32-bit signed integers.
int64	64-bit signed integers.
double	64-bit IEEE 754 floating point.
boolean	Boolean values (true / false).
datetime	UTC datetime (milliseconds since Unix epoch).
timestamp	Internal timestamp type.
binary	Binary data.
objectid	ObjectId values.
decimal128	128-bit decimal floating point. Not yet fully supported for indexing.

---