BUCKET.QUERY

Queries documents from a bucket using a filter expression.

Syntax

BUCKET.QUERY <bucket> <query> [SORTBY <field> <ASC|DESC>] [RESULTSORT <field> <ASC|DESC>] [PROJECTION <spec>] [BATCH <n>] [LIMIT <n>] [COLLATION <spec>]

Parameters

Keyword names are not case-sensitive, and each keyword can appear at most once.

Parameter	Type	Required	Description
bucket	string	Yes	Name of the bucket to query.
query	JSON or BSON	Yes	Filter expression to match documents. Use {} to match all documents.
SORTBY	string + direction	No	Sort results by a field. Requires field name followed by ASC or DESC.
RESULTSORT	string + direction	No	Sort each result batch in memory by any field (indexed or not). Requires field name followed by ASC or DESC. Does not guarantee global ordering across BUCKET.ADVANCE calls. See RESULTSORT.
PROJECTION	JSON or BSON	No	Projection specification that controls which fields appear in returned documents. Use {"field": 1} for inclusion or {"field": 0} for exclusion. See Projection.
BATCH	integer	No	Maximum number of documents to return per batch. Must be non-negative. It does not cap the total number of results, use LIMIT for that. Use BUCKET.ADVANCE to get the next batch. When not specified, the session’s default batch size is used (default: 100, configurable via SESSION.ATTRIBUTE SET BATCH <n>).
LIMIT	integer	No	Maximum total number of documents the cursor returns across the first call and all BUCKET.ADVANCE calls. Must be non-negative. 0 means no limit (default). When the limit is reached, the response carries cursor_id -1 and the cursor is removed.
COLLATION	JSON	No	Query-level collation spec for locale-aware string comparison. Overrides index collation for this query.

Return Value

The command returns a cursor ID and matching documents. The format depends on the protocol version.

Each returned document includes an _id field (ObjectId) that serves as the document’s primary key.

The encoding format of returned documents depends on the session’s reply_type setting:

Format	Response Type	Description
bson	Binary	BSON-encoded document (default)
json	String	JSON-encoded document

To change the format:

SESSION.ATTRIBUTE SET reply_type bson
SESSION.ATTRIBUTE SET reply_type json

RESP3 (map format):

The response is a map with two keys: cursor_id (integer) and entries (array of documents).

1# "cursor_id" => (integer) <cursor-id>
2# "entries" => [<document-1>, <document-2>, ...]

RESP2 (array format):

The response is an array with two elements: the cursor ID and a nested array of documents.

1) (integer) <cursor-id>
2) 1) <document-1>
   2) <document-2>
   ...

Cursor ID:

The cursor ID is used to fetch more results with BUCKET.ADVANCE. Each query creates a new cursor that stores the query context in the session. The cursor tracks the position in the result set for pagination.

A cursor_id of -1 means the LIMIT was reached. The cursor no longer exists and cannot be advanced.

Pagination

Results are returned in batches. Use the cursor ID with BUCKET.ADVANCE to get more results:

BUCKET.ADVANCE QUERY <cursor-id>

When there are no more results, the command returns an empty result set.

BATCH caps a single call, LIMIT caps the whole cursor. Each call returns at most the smaller of BATCH and the remaining LIMIT. The call that reaches the limit returns cursor_id -1 and removes the cursor from the session. There is no need to call BUCKET.CLOSE on it. Without LIMIT, the cursor stays open until you close it.

The cursor maintains its state across calls:

• Query context (filter, sort, batch size, limit)
• Current position in the result set
• Transaction context (if within an explicit transaction)

Snapshot Reads

BUCKET.QUERY honors the session’s SNAPSHOTREAD setting. When SNAPSHOTREAD ON is active, index scans use snapshot isolation, so they will not cause transactions to conflict with concurrent writes. See SNAPSHOTREAD for details.

Routing

BUCKET.QUERY can be executed from any node. When the query is sent to a node that does not own the bucket’s shards, it still returns correct results, but with higher latency because the data is read from the owning nodes. For best performance, use BUCKET.LOCATE to find the node that owns the bucket’s shards and send the query there.

Errors

Argument errors:

Error Code	Error message	Cause
ERR	BATCH argument must be followed by a non-negative integer	-
ERR	LIMIT argument must be followed by a non-negative integer	-
ERR	Unknown sort direction: '<value>'	The SORTBY direction is not ASC or DESC.
ERR	Unknown '<keyword>' argument	-
ERR	Duplicate '<keyword>' argument	-

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
NOSUCHBUCKET	No such bucket: '<bucket>'	-
BUCKETBEINGREMOVED	Bucket '<bucket>' is being removed	-

Examples

The following examples assume reply_type is set to json.

Query all documents:

BUCKET.QUERY users '{}'

Response (RESP3):

1# "cursor_id" => (integer) 1
2# "entries" =>
   1) {"_id": "6a240c7b5da17d872dc0e102", "name": "Bob", "age": 25, "status": "active"}
   2) {"_id": "6a240c7b5da17d872dc0e103", "name": "Carol", "age": 35, "status": "inactive"}
   3) {"_id": "6a240c875da17d872dc0e104", "name": "Henry", "age": 31, "scores": [75, 100, 100]}

Query with filter:

BUCKET.QUERY users '{"name": "Alice"}'

Query with sorting:

BUCKET.QUERY users '{}' SORTBY age DESC

Query with a batch size:

BUCKET.QUERY users '{"status": "active"}' BATCH 10

Query with sorting and a batch size:

BUCKET.QUERY users '{"status": "active"}' SORTBY age ASC BATCH 5

Query with a total limit:

BUCKET.QUERY users '{"status": "active"}' BATCH 10 LIMIT 25

Returns at most 25 documents in total. The first two calls return 10 documents each, the third returns 5 with cursor_id -1.

Query with projection:

BUCKET.QUERY users '{"status": "active"}' PROJECTION '{"name": 1, "email": 1}'

Query with in-memory result sort (no index required):

BUCKET.QUERY users '{"status": "active"}' RESULTSORT score ASC BATCH 10

Query with collation override:

BUCKET.QUERY users '{"name": "alice"}' COLLATION '{"locale": "en", "strength": 2}'

This performs a case-insensitive match using English locale rules, regardless of the index’s collation setting.

Pagination:

> BUCKET.QUERY users '{}' BATCH 100
1# "cursor_id" => (integer) 1
2# "entries" => [...] (first 100 documents)

> BUCKET.ADVANCE QUERY 1
1# "cursor_id" => (integer) 1
2# "entries" =>  [...] (next batch of documents)

Pagination with a limit:

> BUCKET.QUERY users '{}' BATCH 2 LIMIT 3
1# "cursor_id" => (integer) 2
2# "entries" => [...] (2 documents)

> BUCKET.ADVANCE QUERY 2
1# "cursor_id" => (integer) -1
2# "entries" => [...] (1 document)

> BUCKET.ADVANCE QUERY 2
(error) ERR No previous query context found for 'query' operation with the given cursor id