BUCKET.INSERT

Inserts one or more documents into a bucket.

Syntax

BUCKET.INSERT <bucket> DOCS <document> [document ...]

Parameters

Parameter	Type	Required	Description
bucket	string	Yes	Name of the target bucket. The bucket must already exist (see BUCKET.CREATE).
DOCS	JSON or BSON	Yes	One or more documents to insert. Documents can be in JSON or BSON format depending on the session’s input type setting.

The DOCS keyword is not case-sensitive. Every argument after it is read as a document.

Return Value

Returns an array of ObjectIds, one for each inserted document. ObjectIds are returned in both auto-commit mode and within explicit transactions.

An ObjectId is a 12-byte unique identifier. The encoding format of returned ObjectIds depends on the session’s object_id_format setting:

Format	Response Type	Description
hex	String	24-character hex-encoded string (default)
bytes	Binary	Raw 12-byte array

To change the format:

SESSION.ATTRIBUTE SET object_id_format hex
SESSION.ATTRIBUTE SET object_id_format bytes

Example response with hex format:

1) "6835a1c0e4b0f72a3c000001"
2) "6835a1c0e4b0f72a3c000002"

Example response with bytes format:

1) "\x68\x35\xa1\xc0\xe4\xb0\xf7\x2a\x3c\x00\x00\x01"
2) "\x68\x35\xa1\xc0\xe4\xb0\xf7\x2a\x3c\x00\x00\x02"

The _id Field

Each document stored in a bucket has an _id field that serves as its primary key.

• Auto-generated: If a document does not contain an _id field, Kronotop automatically generates an ObjectId and injects it into the document before storage.
• User-provided: If a document already contains an _id field, it must be of type ObjectId. Any other type causes an error.
• Duplicate detection: When user-provided _id values are used, Kronotop checks the primary index for duplicates. If an _id already exists in the bucket, a DUPLICATEKEY error is returned.

Document Format

Documents must be valid JSON or BSON objects. The input format is determined by the session’s input_type setting, which can be configured via SESSION.ATTRIBUTE SET input_type <format>.

Format	Description
JSON	Standard JSON format. Useful for debugging and human-readable input.
BSON	Binary JSON format. Recommended for production use.

Internal storage: Kronotop always stores documents in BSON format regardless of the input format. JSON documents are automatically converted to BSON before storage.

Production recommendation: Use BSON as the input format in production environments. BSON avoids the conversion overhead on every insert, reducing CPU usage and latency. BSON also supports richer data types (such as DateTime, Int64, Decimal128) that cannot be natively represented in JSON.

Routing

The command must be sent to a node that owns at least one shard assigned to the bucket. If the bucket’s shards are all hosted on other nodes, the server rejects the request with a redirect to the appropriate node.

Errors

Argument errors:

Error Code	Error message	Cause
ERR	Unknown '<keyword>' argument	-
ERR	DOCS argument must be followed by one or more documents	-
ERR	_id field must be of type ObjectId	-

Namespace errors:

Error Code	Error message	Cause
NOSUCHNAMESPACE	No such namespace: '<path>'	-
NAMESPACEBEINGREMOVED	Namespace '<path>' is being removed	-

Bucket errors:

Error Code	Error message	Cause
BUCKETBEINGREMOVED	Bucket '<bucket>' is being removed	-
REJECT	<shardId> <host>:<port>	The bucket’s shards are hosted on another member. The message carries the target address.
DUPLICATEKEY	Duplicate key: _id '<hex>'	-

Index errors:

Error Code	Error message	Cause
INDEXTYPE_MISMATCH	Index type mismatch: index '<index>' expects '<type>', but selector '<selector>' matched a value of type '<actual>'	The value type does not match the index type. Only when strict_types is enabled.
VECTORINDEXNOTREADY	Vector index '<namespace>/<bucket>/<indexId>' is not ready yet	The vector index is still being built or recovered. Retry after the background build completes.

Examples

The following examples assume input_type is set to json and object_id_format is set to hex.

Insert a single document:

BUCKET.INSERT users DOCS '{"name": "Alice", "age": 30}'

Response:

1) "6835a1c0e4b0f72a3c000001"

Insert multiple documents:

BUCKET.INSERT users DOCS '{"name": "Alice", "age": 30}' '{"name": "Bob", "age": 25}'

Response:

1) "6835a1c0e4b0f72a3c000001"
2) "6835a1c0e4b0f72a3c000002"

Insert within a transaction:

BEGIN
BUCKET.INSERT users DOCS '{"name": "Alice"}' '{"name": "Bob"}'
COMMIT

Response from BUCKET.INSERT:

1) "6835a1c0e4b0f72a3c000001"
2) "6835a1c0e4b0f72a3c000002"

Insert with a user-provided _id:

BUCKET.INSERT users DOCS '{"_id": {"$oid": "507f1f77bcf86cd799439011"}, "name": "Alice"}'

Response:

1) "507f1f77bcf86cd799439011"