BUCKET.CREATE

Creates a new bucket with optional shard assignment and index definitions.

Syntax

BUCKET.CREATE <bucket> [SHARDS <shard-id> [shard-id ...]] [INDEXES <schema>] [COLLATION <spec>] [IF-NOT-EXISTS]

Parameters

Keyword names are not case-sensitive, and each keyword can appear at most once. SHARDS takes one or more values after a single keyword.

Parameter	Type	Required	Description
bucket	string	Yes	Name of the bucket to create.
SHARDS	integer(s)	No	One or more shard IDs to assign the bucket to. If omitted, a shard is selected automatically.
INDEXES	JSON	No	Index schema defining secondary indexes to create alongside the bucket.
COLLATION	JSON	No	Bucket-level collation spec for locale-aware string ordering. See Collation.
IF-NOT-EXISTS	flag	No	When specified, the command returns OK instead of an error if the bucket already exists. See Removed buckets for the case where it still fails.

Return Value

Returns OK on success.

Shard Assignment

When the SHARDS parameter is omitted, Kronotop automatically assigns the bucket to a shard using round-robin selection across available shards. This ensures even distribution of buckets across the cluster. When multiple shard IDs are provided, the bucket is assigned to all specified shards.

Regardless of how shards are selected, every shard ID is validated before the bucket is created: the shard must have a known route. If a shard has no route, the command returns an error and the bucket is not created. A bucket can span shards across multiple nodes.

Removed buckets

BUCKET.REMOVE marks a bucket as removed but keeps its name reserved until BUCKET.PURGE frees it. Creating a bucket with that name before the purge always fails with BUCKETBEINGREMOVED, with or without IF-NOT-EXISTS. The flag does not hide this case, because returning OK would suggest a usable bucket when there is none.

Run BUCKET.PURGE first, then create the bucket again.

Index Schema Format

The INDEXES parameter accepts 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.

See BUCKET.INDEX CREATE for detailed examples of dot notation and array traversal.

Single-field indexes

Each top-level key (other than $compound) is a field selector (dot-notation path). 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" }
      ]
    }
  ]
}

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.

Each field in the fields array supports selector (required), bson_type (required), and multi_key (optional, default false).

Constraints: A compound index must have at least two fields, at most one field can have multi_key enabled, a unique compound index cannot contain a multi-key field, and each selector must appear exactly once. See Compound Indexes for detailed rules.

Every bucket automatically includes a primary index. The indexes defined here are secondary indexes created in the same transaction as the bucket itself.

Errors

Argument errors:

Error Code	Error message	Cause
ERR	Duplicate '<keyword>' argument	-
ERR	Unknown '<keyword>' argument	-
ERR	SHARDS argument must be followed by one or more shard ids	-
ERR	INDEXES argument must be followed by an index specification	-
ERR	COLLATION argument must be followed by a collation specification	-

Bucket errors:

Error Code	Error message	Cause
BUCKETALREADYEXISTS	Bucket already exists: <bucket>	A bucket with the same name already exists. Suppressed when IF-NOT-EXISTS is given.
BUCKETBEINGREMOVED	Bucket '<bucket>' is being removed	The bucket was removed but not yet purged. IF-NOT-EXISTS does not suppress this error.
ERR	No route found for Bucket shard: <shardId>	-

Index errors:

Error Code	Error message	Cause
ERR	Invalid index schema	-
ERR	'bson_type' cannot be null	-
ERR	Unknown BSON type: <type>	-

Examples

Create a bucket with the default shard assignment:

> BUCKET.CREATE users
OK

Create a bucket on specific shards:

> BUCKET.CREATE users SHARDS 0 1
OK

Create a bucket with secondary indexes:

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

Create a bucket on specific shards with indexes:

> BUCKET.CREATE users SHARDS 0 1 INDEXES '{
  "username": {"bson_type": "string"},
  "age": {"bson_type": "int32"}
}'
OK

Create a bucket with a named multi-key index:

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

Create a bucket with a unique index:

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

Create a bucket with a collated string index:

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

Create a bucket with bucket-level collation:

> BUCKET.CREATE users COLLATION '{"locale": "en", "strength": 2}'
OK

All string indexes in this bucket will use case-insensitive English collation by default, unless overridden at the index level.

Create a bucket with bucket-level collation and indexes:

> BUCKET.CREATE products SHARDS 0 1 COLLATION '{"locale": "tr"}' INDEXES '{"name": {"bson_type": "string"}}'
OK

The name index inherits the bucket’s Turkish collation.

Create a bucket with a compound index:

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

Create a bucket with single-field and compound indexes:

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

Idempotent creation:

> BUCKET.CREATE users IF-NOT-EXISTS
OK

> BUCKET.CREATE users IF-NOT-EXISTS
OK

Attempting to create a bucket that already exists:

> BUCKET.CREATE users
OK

> BUCKET.CREATE users
(error) BUCKETALREADYEXISTS Bucket already exists: users

Creating a bucket that is still being removed:

> BUCKET.REMOVE users
OK

> BUCKET.CREATE users
(error) BUCKETBEINGREMOVED Bucket 'users' is being removed

> BUCKET.CREATE users IF-NOT-EXISTS
(error) BUCKETBEINGREMOVED Bucket 'users' is being removed

> BUCKET.PURGE users
OK

> BUCKET.CREATE users
OK