HTTP API
nonodb exposes one JSON operation endpoint per database, plus health, metrics, and authorization-management endpoints.
- Base URL over a Unix socket:
http://localhost - Default socket:
/run/nonodb.sock - Data endpoint:
POST /v1/exec(alias for/default/v1/exec) - Database-scoped endpoint:
POST /{database}/v1/exec - Stream endpoint:
POST /v1/watch(alias for/default/v1/watch) - Database-scoped stream:
POST /{database}/v1/watch - Health:
GET /healthz - Metrics:
GET /metrics(JSON) andGET /metrics/prometheus(Prometheus text) - Readiness:
GET /readyz - Authorization management:
/v1/auth,/v1/auth/principals,/v1/auth/tokens,/v1/auth/certificates
The API is JSON over HTTP/1.1. It is not the MongoDB wire protocol. An
optional MongoDB-compatible wire listener can be
enabled with NONODB_MONGO_ADDR for official MongoDB drivers. See Multiple databases for
database routing and list_databases, create_database, and drop_database.
Envelope
Section titled “Envelope”Every request to /v1/exec or /{database}/v1/exec is a JSON object with an
op field. A successful call returns:
{"ok": true, "result": ...}A failed call returns:
{ "ok": false, "error": { "code": "invalid_query", "message": "unsupported update operator $rename" }}The HTTP status is usually 200 for success and one of 400, 401, 403,
413, 429, or 500 for errors, but clients should rely on the JSON envelope.
Write durability
Section titled “Write durability”Every write is always atomic: the document, indexes, history, events, TTL
metadata, and subscriptions in one write commit or roll back together.
insert, insert_many, update, find_and_modify, delete, sql writes,
and write_batch accept an optional durability field:
{"op":"insert_many","coll":"imports","docs":[...],"durability":"relaxed"}| Mode | Behavior | Guarantee |
|---|---|---|
full |
Default. Force data and metadata to stable storage before replying | Acknowledged writes survive a crash |
relaxed |
Commit with LMDB NO_META_SYNC; data is flushed, metadata is not forced every commit |
Database stays consistent, but the last commits can be lost after a power failure |
unsafe |
Skip the extra sync. Requires daemon opt-in | Fastest; recent writes can be lost on a crash/power failure |
unsafe is rejected unless the daemon is started with:
NONODB_ALLOW_UNSAFE_WRITES=1With that opt-in the LMDB environment uses MDB_NOSYNC; in that mode both
relaxed and unsafe skip the forced sync. Without it, the environment uses
MDB_NOMETASYNC, so relaxed still flushes data but not the metadata page.
full calls mdb_env_sync after the writer transaction commits.
When the writer groups several requests into one commit, the strictest mode in
the group wins: a single full request forces an fsync for the whole group.
Background maintenance, auto-index builds, TTL expiry, and event writes always
use full durability.
Force a checkpoint after a relaxed batch or import:
{"op":"sync"}{"ok":true,"result":{"synced":true}}sync requires database-admin scope. Do not use relaxed or unsafe for
payments, audit records, authentication state, vault material, or any data whose
loss is unacceptable.
Authentication
Section titled “Authentication”The Unix socket is a trusted local channel and uses the local principal with
full access.
TCP always requires NONODB_AUTH_FILE. Every data request (/v1/exec or
/{database}/v1/exec) and every /metrics request must use either a registered
bearer token:
Authorization: Bearer nodb_<kid>_<secret>or a registered client certificate (mTLS). If both are supplied, they must resolve to the same principal.
GET /healthz and GET /readyz are public. /metrics and
/metrics/prometheus require metrics:read, admin:db, or *:*. Authorization is
deny-by-default and checked per database/collection; write_batch is checked
per operation. Scopes may be database-qualified, for example
read:app1/orders. Missing credentials return 401; insufficient scope returns 403 with error
code forbidden. Repeated failed authentication can lock the peer IP and return
429 with error code rate_limited.
See Authentication and authorization for the registry format, scopes, CLI management, mTLS mapping, reload behavior, and audit logging.
Vault headers
Section titled “Vault headers”Requests against a vault collection must also send all three headers:
X-NonoDB-Tenant: acmeX-NonoDB-Key-Id: acme:v1X-NonoDB-Key: <base64-32-byte-key>The key is sent only in the header, never in the JSON body. Vault collections support only a restricted subset of operations. See Vault collections for the full contract.
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| Request body | 4 MiB (413 when exceeded) |
| Server-side request timeout | 30 s (timeout error) |
| Document size | 1 MiB (document_too_large, HTTP 413) |
Search/fuzzy/vector limit |
default 10, maximum 1000 |
lookup values |
maximum 10,000 |
lookup result budget |
64 MiB (result_too_large) |
| Fuzzy candidates | 5,000 per query |
| Vector dimensions | 1–65,536 |
write_batch operations |
bounded by request size |
| LMDB named databases | 1024 (MDB_DBS_FULL when exhausted) |
The server timeout can be raised with NONODB_REQUEST_TIMEOUT; the Python
client timeout with NONODB_TIMEOUT or the timeout= argument.
Operations
Section titled “Operations”op |
Purpose |
|---|---|
list_databases |
List databases |
create_database |
Create a database |
drop_database |
Drop a non-default database |
sync |
Force an fsync of the selected database |
insert |
Insert one document |
insert_many |
Insert multiple documents |
find |
Query documents |
find_one |
Return one document |
lookup |
Ordered point lookups by _id or a unique index |
watch |
Long-poll append-only events by sortable _id |
explain |
Show the selected plan, bounds, and actual counts |
update |
Update or upsert documents |
find_and_modify |
Atomically update/remove one document and return it |
delete |
Delete documents |
count |
Count matching documents |
aggregate |
Read-only aggregation pipeline |
sql |
SQL SELECT, INSERT, UPDATE, or DELETE over one collection |
explain_sql |
Show the plan for a SQL SELECT |
create_index |
Create a secondary index |
create_indexes |
Create several indexes in one scan |
drop_index |
Drop a secondary index |
list_indexes |
List secondary indexes |
create_text_index |
Create a BM25 index |
drop_text_index |
Drop a BM25 index |
list_text_indexes |
List BM25 indexes |
create_fuzzy_index |
Create a fuzzy index |
drop_fuzzy_index |
Drop a fuzzy index |
list_fuzzy_indexes |
List fuzzy indexes |
create_vector_index |
Create an exact vector index |
drop_vector_index |
Drop a vector index |
list_vector_indexes |
List vector indexes |
reindex |
Rebuild every index on a collection |
search |
BM25 full-text query |
fuzzy |
Approximate string query |
vector_search |
Exact top-K vector query |
batch |
Multiple read operations, one snapshot |
write_batch |
Atomic group of writes |
history |
List revisions of one document |
get_version |
Read one exact document revision |
list_collections |
List known collections |
database_stats |
Record counts and storage estimates per collection |
create_collection |
Create a standard or vault collection |
set_collection_ttl |
Set or clear the default document TTL |
get_collection_ttl |
Read the default document TTL |
set_collection_history |
Set per-collection history retention (0 disables) |
get_collection_history |
Read per-collection history retention |
set_collection_events |
Enable/disable automatic collection change events |
get_collection_events |
Read automatic change-event settings |
get_collection_metrics |
Read runtime counters for one collection |
create_subscription |
Create/replace a conditional collection subscription |
renew_subscription |
Renew a subscription client lease |
delete_subscription |
Delete a conditional subscription |
list_subscriptions |
List conditional subscriptions |
map_info |
Read map size and high-water mark |
resize_map |
Grow the LMDB map online |
insert
Section titled “insert”{ "op": "insert", "coll": "users", "doc": {"name": "Ada", "age": 36}}Response:
{"ok": true, "result": {"inserted_id": "4f0b5f6e-..."}}- The document must be a JSON object.
- If
_idis omitted, a UUID v4 string is generated. - If
_idis present it must be a string or an Extended JSON ObjectId ({"$oid": "..."}). String IDs keep their existing format; ObjectId IDs are returned as Extended JSON. - A duplicate
_idor a unique-index conflict fails withduplicate_key. _idis the primary key. Treat it as immutable.- The reserved top-level
_ttlfield sets a per-document expiry in seconds._ttl: 0ornulldisables the collection default. The field is removed before storage. See Document TTL. - Extended JSON
{"$date": ...}values are normalized to canonical UTC milliseconds before storage. See Dates and time zones. - Extended JSON numeric objects are validated and stored in canonical form:
$numberInt,$numberLong,$numberDouble, and$numberDecimal. See Numbers and decimals. {"$binary": ...}/{"$uuid": ...}and{"$oid": ...}are normalized to canonical Extended JSON. See BSON scalar types.
insert_many
Section titled “insert_many”{ "op": "insert_many", "coll": "users", "docs": [ {"name": "Ada"}, {"name": "Grace"} ]}Response:
{"ok": true, "result": {"inserted_ids": ["...", "..."]}}insert_many is a single write request, but it is not the API for guaranteed
all-or-nothing groups. Use write_batch when a group of
inserts must commit or roll back together.
Requests are limited to 4 MiB. For large imports, send chunks of roughly 500–1,000 documents and keep each request below the limit.
{ "op": "find", "coll": "users", "filter": {"age": {"$gte": 18}}, "projection": {"name": 1, "age": 1, "_id": 0}, "sort": [["age", -1], ["name", 1]], "skip": 0, "limit": 20}Response: a JSON array of documents.
Fields:
| Field | Default | Meaning |
|---|---|---|
filter |
{} |
Query predicate; missing/null/empty means match all |
projection |
none | Include or exclude projection; dotted paths are supported |
sort |
none | Array of [field, direction]; 1 ascending, -1 descending |
skip |
0 |
Number of matching documents to skip |
limit |
none | Maximum number of results; unlimited when omitted |
comment |
none | Optional application comment; echoed by explain |
max_time_ms |
none | Server-side execution budget in milliseconds; 0 or omitted means no limit |
hint |
none | Force an index by name or key object, or use {"$natural": 1} for a collection scan |
Behavior:
max_time_msis enforced during collection/index scans, including parallel scans, sorted scans, and$nearcandidates. When the budget expires, the request fails with error codetimeout.hintaccepts"index_name"(the logical name, for example"age"or"group+age") or a key object such as{"age": 1, "name": -1}. The hinted index must exist and be usable for the filter; otherwise the request fails withinvalid_queryrather than silently choosing another plan. For compound indexes, prefer the logical name ("group+age") so field order is explicit.{"$natural": 1}forces a collection scan. A sort by[("$natural", 1)]or[("$natural", -1)]uses the collection’s natural_idorder.- Without
sort, results follow the cheapest scan order (index order or_idorder), and execution stops afterskip + limitmatches. - Equality or range conditions on
_iduse the primary-key B+ tree directly. Sorting by a single_idfield can stream that range forwards or backwards. - With
sort, results are ordered by the requested fields. Missing values andnullsort last. Ties are broken deterministically by_id. - An index can serve the sort when its full field order and per-field directions match the requested sort, or when every direction is inverted (reverse index traversal). Mixed-direction compound indexes are supported. Otherwise a full scan and top-K sort are used.
- Nested paths use dots:
{"user.address.city": "London"}. - Projection is either inclusive or exclusive;
_idis included by default and can be disabled with"_id": 0. Dotted paths create nested projection trees.
find_one
Section titled “find_one”{ "op": "find_one", "coll": "users", "filter": {"email": "ada@example.com"}, "projection": {"name": 1}}Response: the document or null.
find_one is find with limit=1 and no sort. It stops as soon as a match is
found. An exact _id filter uses a direct primary-key lookup. It accepts the
same optional comment, max_time_ms, and hint fields as find.
lookup
Section titled “lookup”Ordered point lookups by _id or a unique index. This is the efficient batch
alternative to N separate find_one calls.
{ "op": "lookup", "coll": "users", "by": "email", "values": ["ada@example.com", "missing@example.com", "grace@example.com"], "fields": ["name", "status"]}Response:
{ "ok": true, "result": { "results": [ {"_id": "u1", "name": "Ada", "status": "active"}, null, {"_id": "u2", "name": "Grace", "status": "inactive"} ], "found": 2 }}Semantics:
-
bydefaults to_id. -
A non-
_idlookup requires a unique index whose field order exactly matchesby; otherwise the request returnsinvalid_query. -
bymay be an array for a compound unique index. Each input value must then be an array with the same number of elements, in the same order:{"op": "lookup","coll": "users","by": ["tenant_id", "email"],"values": [["acme", "ada@example.com"],["other", "ada@example.com"],["acme", "missing@example.com"]]}Compound values with the wrong shape return
null. -
Results are returned in input order. Missing values and values that cannot be encoded return
null;foundis the number of non-null results. -
Duplicate input values produce duplicate result entries. Repeated keys are looked up only once internally.
-
valuesis limited to 10,000 entries per request. -
fieldsis a top-level inclusive projection. If every requested field is available in a covering index created withinclude, the document is not read from the main collection. Otherwise the normal document fetch is used. -
projectionaccepts a normal flat projection and allows excluding_id:{"op": "lookup","coll": "users","by": "email","values": ["ada@example.com"],"projection": {"name": 1, "_id": 0}}fieldsandprojectionare mutually exclusive. A covering index is used only for an inclusiveprojection(orfields). -
_idis included by default when usingfields. -
The result budget is 64 MiB, measured from stored document/index bytes before JSON encoding. Larger responses return
result_too_large; request fewer keys or use a smaller projection. -
lookupdoes not acceptfilter,sort,skip, orlimit. Usefindfor arbitrary predicates. -
Non-unique lookups and lookups without a matching index are not supported yet.
-
Vault collections reject
lookup.
Long-polls an append-only event collection by sortable _id. Use it for outbox
event collections such as _events; the long-poll form is not an automatic
change stream. Streaming mode:"live" provides connection-scoped change
notifications, including updates and deletes.
{ "op": "watch", "coll": "_events", "after": "01J...", "limit": 100, "timeout_ms": 1000, "types": ["order.paid"], "filter": {"payload.total": {"$gte": 1000}}, "projection": {"type": 1, "payload": 1}}Response:
{ "events": [ {"_id": "01J...", "type": "order.paid", "payload": {"total": 1200}} ], "next": "01J...", "timed_out": false, "has_more": false, "truncated": false, "oldest": null}afteris optional. Omit it to start from the beginning of the collection.limitdefaults to100; values are clamped to1..=1000.timeout_msdefaults to1000; values are clamped to0..=25000.typesfilters event documents by theirtypefield.filterapplies an additional MongoDB-style filter.projectionis optional;_idis always retained for the resume token.nextis the last returned_id, orafterwhen no event arrived.timed_outis true only when the timeout expired with no events.has_moreis true when another page is immediately available.truncatedis true whenafteris older than retained events;oldestis the oldest event id still available.watchrequires read scope oncoll, is not cacheable, and is rejected inside a readbatch. Vault collections are rejected.
Continuous stream
Section titled “Continuous stream”POST /v1/watch accepts the same body and streams events continuously. The
default response is application/x-ndjson; Accept: text/event-stream selects
SSE. Optional fields:
heartbeat_ms— keepalive interval, default15,000, range100..60,000;timeout_ms— maximum stream lifetime; absent or0means no limit;overlap_ms— late-commit rescan window, default2,000, max60,000;threshold— optional server-side event count threshold:{"count":100,"window_ms":60000,"group_by":["payload.tenant"]};mode— set to"live"for a connection-scoped condition overcoll;ops,count,once,name,event_type— live-mode condition fields.
Live mode does not tail _events. It registers an in-memory subscription for the
connection, evaluates filter/count in the writer, and pushes matching events
directly. Closing the stream removes it; half-open connections are cleaned up
after 30 seconds without a heartbeat. Live events are not stored in _events.
after, types, and threshold are rejected in live mode, and vault
collections are not supported. See
Streaming outbox events.
NDJSON starts with {"stream":{"truncated":false,"oldest":null}}, then sends one
event per line and periodic {"heartbeat":true,"ts_ms":...} frames. SSE emits
ready, message, heartbeat, and error events. See
Streaming outbox events for full client examples, reconnect
handling, and checkpoint guidance.
explain
Section titled “explain”Returns the access path chosen for a find-shaped query, index and bounds
information, and exact document counts.
{ "op": "explain", "coll": "users", "filter": {"age": {"$gte": 18}}, "sort": [["age", 1]], "skip": 0, "limit": 20, "comment": "nightly report", "max_time_ms": 5000}Example result:
{ "collection": "users", "access_path": "index_scan", "index_used": true, "index": {"fields": ["age"], "unique": false, "include": []}, "bounds": { "lower": {"value": "06...", "inclusive": true}, "upper": null }, "candidates": 42, "estimated_documents": 42, "actual_matched": 40, "actual_returned": 20, "sort_covered": true, "filter": {"age": {"$gte": 18}}, "sort": [["age", 1]], "skip": 0, "limit": 20, "comment": "nightly report", "maxTimeMS": 5000}Fields:
| Field | Meaning |
|---|---|
access_path |
id_lookup, id_range, index_scan, or collection_scan |
index_used |
Whether a primary/secondary index supplies candidates |
index |
Index fields, uniqueness, and included fields (null for scans) |
bounds |
Encoded lower/upper index keys; _id bounds are literal strings |
candidates |
Index entries or documents considered before filtering |
estimated_documents |
Same candidate count, provided as an estimate field |
actual_matched |
Documents matching the filter |
actual_returned |
Documents returned after skip/limit |
sort_covered |
Whether the access path already provides the requested order |
comment |
Present when the request supplied comment |
maxTimeMS |
Present when the request supplied a non-zero max_time_ms |
hint |
Present when the request supplied hint |
explain executes the query to produce exact actual_* counts. Use a small
limit when explaining a broad query. It is read-only and does not create or
modify indexes. Vault collections do not support explain.
update
Section titled “update”{ "op": "update", "coll": "users", "filter": {"_id": "..."}, "update": {"$set": {"active": true}, "$inc": {"logins": 1}}, "multi": false, "upsert": false}Response:
{ "ok": true, "result": { "matched": 1, "modified": 1, "upserted_id": null }}| Field | Default | Meaning |
|---|---|---|
multi |
false |
Update every match instead of only the first |
upsert |
false |
Insert a new document when nothing matches |
Update forms
Section titled “Update forms”An update is either:
- an operator object — every top-level key starts with
$; or - a replacement document — no top-level keys start with
$.
Mixing operators and plain fields is an error. A replacement document keeps the
existing _id; the _id in the replacement (if any) does not replace the
stored key.
Supported operators
Section titled “Supported operators”| Operator | Behavior |
|---|---|
$set |
Set one or more paths; creates intermediate objects |
$unset |
Remove one or more paths; no error if absent |
$inc |
Add a number; missing field is treated as 0 |
$mul |
Multiply a number; missing field becomes 0 |
$min |
Set the field only if the new value is lower, or the field is missing |
$max |
Set the field only if the new value is higher, or the field is missing |
$rename |
Move a field to a new name |
$currentDate |
Set the current UTC date or BSON Timestamp; true, {"$type": "date"}, or {"$type": "timestamp"} |
$bit |
Bitwise and, or, or xor on an integer field |
$pop |
Remove the first (-1) or last (1) array element |
$push |
Append one value or {"$each": [...]}; supports $position, $slice, $sort |
$pull |
Remove array elements matching a value or query predicate |
$pullAll |
Remove all occurrences of the listed values |
$addToSet |
Append values that are not already present; supports $each |
$setOnInsert |
Apply only when an upsert inserts a new document |
Examples:
{"$set": {"profile.theme": "dark"}}{"$inc": {"counters.requests": 1}}{"$mul": {"prices.total": 1.2}}{"$min": {"lowest": 12}}{"$max": {"highest": 99}}{"$rename": {"old_name": "new_name"}}{"$currentDate": {"updated_at": true}}{"$bit": {"flags": {"or": 4}}}{"$pop": {"queue": -1}}{"$push": {"tags": "rust"}}{"$push": {"ports": {"$each": [25, 587]}}}{"$push": {"top": {"$each": [9, 3, 7], "$sort": 1, "$slice": 2}}}{"$push": {"queue": {"$each": ["high"], "$position": 0}}}{"$addToSet": {"roles": {"$each": ["admin", "editor", "admin"]}}}{"$pull": {"tags": "deprecated"}}{"$pull": {"scores": {"$gte": 90}}}{"$pullAll": {"tags": ["draft", "obsolete"]}}Updates can also be an aggregation pipeline. Only stages that produce one
document per input are allowed: $set/$addFields, $unset, $project,
$replaceRoot, and $replaceWith. Pipeline updates cannot change or remove
_id, and unsupported stages such as $match, $group, or $limit are
rejected.
[ {"$set": {"total": {"$add": ["$subtotal", "$tax"]}}}, {"$unset": "temporary"}, {"$project": {"_id": 1, "total": 1}}]Array paths support numeric indexes and positional updates:
{"$set": {"items.0.qty": 5}}{"$set": {"items.$.qty": 5}}{"$inc": {"items.$[].qty": 1}}{"$set": {"items.$[i].checked": true}}The positional $ uses the first array element matching the update filter.
Use $elemMatch on the array field so the filter can select an element:
filter: {"items": {"$elemMatch": {"sku": "y"}}}update: {"$set": {"items.$.qty": 5}}$[identifier] requires a matching entry in arrayFilters. Via the Python
client:
coll.update( {"_id": "a"}, {"$set": {"items.$[i].checked": True}}, array_filters=[{"i.sku": "x", "i.qty": {"$lt": 5}}],)Raw protocol updates accept an optional array_filters array. Each entry is
an object using exactly one identifier; keys are either the identifier itself
or identifier.path. Malformed placeholders, missing identifiers, mixed
identifiers, and invalid $push modifiers return invalid_query before any
write.
Notes:
$pushand$addToSetreplace a non-array existing value with a new array. This is destructive; ensure the field is intended to be an array.$addToSetuses the same equality semantics as filters. Numbers compare by value (1 == 1.0), and objects compare structurally.$pullaccepts either a value or a query predicate (for example$gte,$in, or a field condition for array elements that are objects).$pushmodifier ordering follows MongoDB: insert at$position, then apply$sort, then apply$slice(positive keeps the first N, negative keeps the last N, zero empties the array).- Nested paths (
a.b.c), numeric array indexes (a.0.b), positional$,$[], and$[identifier]work with the update operators above. Assigning beyond the end of an array pads it withnull;$unseton an array index sets that element tonull. _idis immutable. Do not use$set/$unset/array operators on_id.$currentDatesupports dates and BSON Timestamp ({"$type": "timestamp"}).- Update pipelines support the stages listed above; other stages return
invalid_query.
Upsert
Section titled “Upsert”When upsert=true and no document matches:
- Equality conditions from the filter become the seed document.
Conditions inside
$andand{"field": {"$eq": value}}are included. Range conditions and other operators are ignored. - Operators are applied.
$setOnInsertruns only for this insert. - A filter
_idis preserved. - The new document is inserted and its id is returned in
upserted_id.
For a replacement upsert, equality fields from the filter are merged into the replacement document unless the replacement already defines them.
Example:
{ "op": "update", "coll": "settings", "filter": {"tenant": "acme", "key": "smtp"}, "update": { "$set": {"host": "smtp.example.com"}, "$setOnInsert": {"created_at": "2026-11-09T00:00:00Z"} }, "upsert": true}Result when inserting:
{"matched": 0, "modified": 0, "upserted_id": "..."}The inserted document contains tenant, key, host, and created_at.
find_and_modify
Section titled “find_and_modify”Atomically selects one document, updates or removes it, and returns its old or new image in the same write transaction.
{ "op": "find_and_modify", "coll": "jobs", "filter": {"state": "queued"}, "update": {"$set": {"state": "running"}, "$inc": {"attempts": 1}}, "sort": [["priority", -1], ["_id", 1]], "new": true, "array_filters": [{"i.ready": true}], "projection": {"_id": 1, "state": 1, "attempts": 1}}Response:
{ "value": {"_id": "job-1", "state": "running", "attempts": 1}, "matched": 1, "modified": 1, "upserted_id": null}Fields:
| Field | Behavior |
|---|---|
filter |
Selects the candidate document |
update |
Update document; required unless remove=true |
sort |
Chooses the first matching document by sort order |
new |
Return the post-image instead of the pre-image |
upsert |
Insert a filter-seeded document when nothing matches |
remove |
Remove the selected document instead of updating it |
array_filters |
MongoDB-style filters for $[identifier] update paths |
projection |
Projection applied to the returned image; nested paths are supported |
With upsert=true and no match, the default (new=false) response has
"value": null; with new=true it returns the inserted document. For an
insert, matched and modified are 0 and upserted_id is set.
remove=true cannot be combined with update, upsert, or new. Invalid
combinations and malformed array filters return invalid_query without
changing the document.
Vault collections support the same operation with their normal restriction:
the filter must identify exactly one _id and projection is not supported.
delete
Section titled “delete”{ "op": "delete", "coll": "sessions", "filter": {"expires_at": {"$lt": "2026-01-01T00:00:00Z"}}, "multi": true}Response:
{"ok": true, "result": {"deleted": 42}}multi defaults to false, which deletes only the first match. Deletion
removes secondary, text, fuzzy, and vector index entries in the same write transaction.
{ "op": "count", "coll": "users", "filter": {"active": true}, "comment": "dashboard", "max_time_ms": 5000}Response:
{"ok": true, "result": {"count": 120}}Optimizations:
filter: {}/nulluses LMDB’s entry count in O(1).- A filter exactly matching the fields of an index can be counted from the index range without reading documents.
- Other filters perform a full scan, but
countdoes not materialize results. max_time_msbounds index and collection scanning and returns thetimeouterror code when the budget expires.commentis accepted for request correlation but is not stored.
aggregate
Section titled “aggregate”{ "op": "aggregate", "coll": "orders", "pipeline": [ {"$match": {"status": "paid"}}, {"$group": { "_id": "$tenant", "total": {"$sum": "$amount"}, "n": {"$sum": 1} }}, {"$sort": {"total": -1}}, {"$limit": 10} ], "comment": "monthly report", "max_time_ms": 5000}A terminal $out or $merge stage turns the request into a write. Such a
request is routed through the single writer, requires write:<target>, and may
include durability (full, relaxed, or unsafe).
Response:
{ "ok": true, "result": { "results": [ {"_id": "acme", "total": 4200, "n": 37} ] }}Read-only aggregation runs in one LMDB read snapshot and is allowed in the
read-only batch operation. A missing collection produces an empty results
array. max_time_ms bounds the pushed-down find/count phase and is
rechecked before and after the remaining pipeline; expiry returns the timeout
error code. comment is accepted for correlation but is not stored.
Pipelines ending in $out or $merge run in one writer transaction. The read
part of the pipeline is evaluated first, then the target writes are applied.
Any validation, uniqueness, or size error aborts the whole transaction. Write
stages are not allowed in a read batch or in a cursor aggregation.
Supported stages
Section titled “Supported stages”| Stage | Description |
|---|---|
$match |
Filter documents with the same filter language as find |
$project |
Include/exclude fields, rename fields, or compute expressions |
$addFields / $set |
Add or replace fields with expression results |
$unset |
Remove one field or an array of fields |
$unwind |
Expand an array into one document per element |
$group |
Group by an expression and compute accumulators |
$bucket |
Group values into explicit boundary buckets |
$bucketAuto |
Group values into a requested number of buckets |
$sortByCount |
Group by an expression and sort by descending count |
$replaceRoot / $replaceWith |
Replace each document with an evaluated object |
$sample |
Return a random sample of the requested size |
$facet |
Run multiple sub-pipelines over the same input documents |
$lookup |
Join documents from another collection |
$unionWith |
Append the result of another collection or sub-pipeline |
$graphLookup |
Recursively traverse references across a collection |
$setWindowFields |
Partition, sort, rank, window, and compute analytics |
$densify |
Generate missing values in a numeric or date range |
$fill |
Fill missing or null values with a value, locf, or linear interpolation |
$out |
Replace a collection with the pipeline result (terminal only) |
$merge |
Insert, merge, replace, or skip matching target documents (terminal only) |
$sort |
Sort by one or more fields |
$skip |
Skip documents |
$limit |
Limit documents |
$count |
Replace the stream with one document containing the row count |
A leading $match is pushed into the normal read path, so indexes and _id
ranges can be used before the remaining pipeline runs. The daemon also pushes
a contiguous prefix of $sort+$skip/$limit, simple $project, and $skip
into the query planner when stage order makes that safe. A lone $count after
$match is executed as a count instead of materializing documents.
$sort without a following $limit stays in the in-memory path, where the
plain sort is cheaper than a full-size TopK heap.
Expressions
Section titled “Expressions”Field references use "$field" or "$nested.path". $$ROOT / $$CURRENT
refer to the current document. Literals can be wrapped in {"$literal": ...}.
Supported operators:
$ifNull,$cond$add,$subtract,$multiply,$divide$concat$eq,$ne,$gt,$gte,$lt,$lte
Projection follows MongoDB-style include/exclude rules. {"_id": 0} removes
_id; {"alias": "$field"} renames a field; {"total": {"$sum": ...}} is not
valid in $project (use $group for accumulators).
Group accumulators
Section titled “Group accumulators”$group requires _id and accepts one accumulator per output field:
{ "$group": { "_id": "$tenant", "total": {"$sum": "$amount"}, "average": {"$avg": "$amount"}, "first": {"$first": "$created_at"}, "last": {"$last": "$created_at"}, "min": {"$min": "$amount"}, "max": {"$max": "$amount"}, "all_ids": {"$push": "$_id"}, "unique_ids": {"$addToSet": "$_id"}, "rows": {"$count": {}} }}$sum and $avg ignore non-numeric values. $addToSet deduplicates by JSON
value equality.
$unwind
Section titled “$unwind”{"$unwind": "$tags"}{"$unwind": {"path": "$tags", "preserveNullAndEmptyArrays": true, "includeArrayIndex": "tag_index"}}The object form is accepted:
{"$sort": {"total": -1, "tenant": 1}}Because JSON object key order is not guaranteed by all clients, the array form preserves explicit multi-field order:
{"$sort": [["total", -1], ["tenant", 1]]}$lookup
Section titled “$lookup”Joins documents from another collection:
{ "$lookup": { "from": "items", "localField": "sku", "foreignField": "sku", "as": "item" }}localFieldmay be an array; each element is matched againstforeignField.- A missing local field is treated as
null, matching foreign documents whose field isnullor missing. - An optional
pipelineruns on the matching foreign documents. A pipeline-only lookup (nolocalField/foreignField) scans the foreign collection and then applies the pipeline. letbinds per-input-document variables that the sub-pipeline can read as$$name, including inside$expr.- Nested
$lookupstages are supported in the sub-pipeline. - Missing foreign collections produce empty arrays.
- The result is written to
asas an array. The aggregate intermediate-document limit still applies.
$unionWith
Section titled “$unionWith”Appends documents from another collection to the current pipeline result:
{ "$unionWith": { "coll": "archived_orders", "pipeline": [ {"$match": {"status": "paid"}}, {"$project": {"tenant": 1, "total": 1}} ] }}The shorthand form {"$unionWith": "archived_orders"} appends the whole
collection. Duplicates are preserved, and the union result is appended after
the current documents. A missing collection contributes no documents.
Sub-pipelines support the same read-only stages, including nested $lookup and
$unionWith; the intermediate-document limit applies to the combined result.
$graphLookup
Section titled “$graphLookup”Recursively traverses references in another collection:
{ "$graphLookup": { "from": "employees", "startWith": "$reportsTo", "connectFromField": "reportsTo", "connectToField": "_id", "as": "managementChain", "maxDepth": 5, "depthField": "depth", "restrictSearchWithMatch": {"active": true} }}startWithis evaluated per input document and may produce a scalar or an array of starting values.- At each hop, documents where
connectToFieldmatches any current value are added toas; theirconnectFromFieldvalues become the next hop. maxDepthlimits the number of hop expansions.0returns only the initial matches; omit it to traverse until no new documents are found.depthFieldadds the zero-based hop depth to each joined document.restrictSearchWithMatchfilters candidates at every hop.- Cycles are detected by joined document
_id, so self-references and loops do not run forever. - A missing foreign collection produces empty
asarrays. - The aggregate intermediate-document limit applies to each
asresult.
$setWindowFields
Section titled “$setWindowFields”Adds partitioned, sorted window calculations without collapsing documents:
{ "$setWindowFields": { "partitionBy": "$region", "sortBy": {"day": 1}, "output": { "running": {"$sum": "$amount"}, "sum3": {"$sum": "$amount", "window": {"documents": [-1, 1]}}, "rank": {"$rank": {}}, "dense": {"$denseRank": {}}, "row": {"$documentNumber": {}}, "previous": {"$shift": {"output": "$amount", "by": -1, "default": 0}} } }}partitionByis evaluated per document; omitted means one partition.sortByaccepts the normal sort object or[field, direction]pair array.- Accumulators:
$sum,$avg,$min,$max,$first,$last,$push,$addToSet, and$count. The default frame is["unbounded", "unbounded"](the whole partition); specify["unbounded", "current"]for a running total. window.documentsacceptsunbounded,current, or integer offsets for both bounds.window.rangeacceptsunbounded,current, or numeric offsets. It requires exactly onesortByfield. Numeric sort fields use numeric offsets. Date sort fields require aunit(year,quarter,month,week,day,hour,minute,second,millisecond) and use calendar-aware offsets.- Advanced analytics:
$expMovingAvg(inputplusNoralpha),$derivative(input, optionalunit), and$integral(input, optionalunit).$expMovingAvgfollows partition order;$derivativeand$integralrequire exactly onesortByfield and accept adocumentsorrangewindow. - Ranking operators:
$rank,$denseRank, and$documentNumber, which requiresortBy. $shiftsupportsoutput, integerby, and optionaldefault.- The aggregate intermediate-document limit still applies.
$densify
Section titled “$densify”Adds documents for missing values in a numeric or date field:
{ "$densify": { "field": "ts", "partitionByFields": ["sensor"], "range": {"step": 1, "unit": "day", "bounds": "partition"} }}fieldis a dotted path;partitionByFieldsis an optional array of paths.- Without
unit,stepis a positive number and the field values must be numeric. - With
unit,stepis a positive integer and the field values must be dates. Supported units areyear,quarter,month,week,day,hour,minute,second, andmillisecond. boundsispartition(default),full, or an explicit[lower, upper]pair. Bounds are inclusive.fulluses the global minimum and maximum across all partitions.- Generated documents contain the densified field and the partition fields. Existing documents are preserved, and existing values are not duplicated.
- A partition with no non-null values does not generate documents.
- The result must stay within the aggregate intermediate-document limit.
Fills missing and null values within partitions:
{ "$fill": { "partitionBy": "$sensor", "sortBy": {"ts": 1}, "output": { "status": {"value": "unknown"}, "temperature": {"method": "linear"}, "mode": {"method": "locf"} } }}partitionByis an expression;partitionByFieldsis an optional array of paths. They cannot be combined.sortByuses the normal sort object. It is required forlinear;locfuses the partition order when no sort is supplied.valuefills missing or null fields with the evaluated expression.locfcarries the previous non-null value forward. Values before the first non-null value are left unchanged.linearinterpolates numeric values between known points using the firstsortByfield as the x-axis. It supports numeric and date sort fields. Values before the first or after the last known point are not extrapolated.- Non-null, non-numeric values in a
linearoutput field returninvalid_query. - Each output field is computed from the input documents before any
$fillresults are written, so output fields do not depend on each other.
Replaces the target collection contents with the pipeline result:
{ "$out": "daily_totals"}$outmust be the last stage.- The target may be a string or
{"coll": "...", "db": "..."}. The database must be the current database; cross-database writes are not supported. - The target documents are deleted and the new result documents are inserted in the same writer transaction. Existing indexes and collection settings are preserved.
- If the target does not exist, it is created as a standard collection.
- The source and target must be standard collections. Writing to the internal
_eventscollection is rejected. - The response contains
results: [], plustarget,deleted, andinsertedcounters.
$merge
Section titled “$merge”Merges the pipeline result into an existing or new collection:
{ "$merge": { "into": "customers", "on": "email", "whenMatched": "merge", "whenNotMatched": "insert" }}$mergemust be the last stage.intoaccepts a collection name or{"coll": "...", "db": "..."}in the current database.onis a field name or array of field names. It defaults to_id. Fields other than_idrequire an existing unique index on exactly those fields.whenMatcheddefaults tomerge:merge— add or overwrite the result’s top-level fields, preserving other existing fields;replace— replace the matched document, preserving its_id;keepExisting— leave the matched document unchanged;fail— returninvalid_query.
whenNotMatcheddefaults toinsert:insert— insert the result document;discard— skip it;fail— returninvalid_query.
- A result document that contains
_idmust use the same_idas a matched target document. Changing_idis rejected. whenMatchedmay be a pipeline. It runs on the existing target document as the root, with$$newbound to the incoming result document. Only$set/$addFields,$project,$unset, and$replaceRoot/$replaceWithare allowed. The pipeline must produce one object and cannot change_id.letdefines variables available as$$namein awhenMatchedpipeline. Values are evaluated against each incoming result document.- The response contains
results: [], plustarget,matched,modified,inserted, andskippedcounters.
Limits
Section titled “Limits”- At most 100,000 documents may exist in an intermediate result. The call
returns
invalid_queryif the limit is exceeded. - The normal request timeout (30 seconds by default) applies.
- Response size is still limited by the HTTP response path and the client’s
practical memory; use
$limitand$projectfor large collections. - Not supported:
$redactand arbitrary JavaScript.
Runs a SQL SELECT, INSERT, UPDATE, or DELETE over one collection. The
collection name is parsed from the statement for authorization.
{ "op": "sql", "query": "SELECT team, COUNT(*) AS n, SUM(score) AS total FROM users WHERE age >= $1 GROUP BY team ORDER BY total DESC LIMIT 10", "params": [18]}Response:
{ "ok": true, "result": { "results": [ {"team": "core", "n": 3, "total": 60}, {"team": "kernel", "n": 2, "total": 30} ] }}Supported clauses and limitations are documented in SQL queries:
SELECT [DISTINCT],*, aliases,CASE, scalar functions, and arithmetic;WHEREwith comparisons,AND/OR/NOT, parentheses,IN,BETWEEN,IS NULL, andLIKE;GROUP BY,HAVING,ORDER BY,LIMIT, andOFFSET;- aggregate functions
COUNT,COUNT(DISTINCT field),SUM,AVG,MIN, andMAX; - positional parameters with
?or$1; - one collection, no joins or subqueries;
INSERT INTO collection (columns...) VALUES (...)with one or more rows;UPDATE collection SET column = value... [WHERE ...], including expressions;DELETE FROM collection [WHERE ...].
Simple field-only selects use the normal find path. Grouping, DISTINCT,
computed expressions, and HAVING use the aggregation pipeline. INSERT, UPDATE, and
DELETE run through the single writer in one isolated LMDB transaction and
return inserted/inserted_ids, matched/modified, or deleted inside
results.
SELECT is read-only and can be used in a read batch; write statements are
rejected there. SELECT requires read:<collection>, while INSERT, UPDATE, and DELETE
require write:<collection>. Parse and planning errors return
invalid_sql (HTTP 400). A missing collection returns an empty results
array for SELECT.
explain_sql
Section titled “explain_sql”Returns the selected plan for a SQL SELECT.
{ "op": "explain_sql", "query": "SELECT team, COUNT(*) AS n FROM users GROUP BY team HAVING COUNT(*) > 1", "params": []}For simple field-only selects this is the normal find explain object, including
access_path, index, bounds, candidates, actual_matched, and
actual_returned. For grouped, distinct, or computed queries it returns
access_path (aggregation_group, aggregation_distinct, or aggregation)
and the generated pipeline.
explain_sql accepts only SELECT, is available in read batch, cacheable,
and requires read:<collection>.
Cursors
Section titled “Cursors”Cursors page large result sets through _id keyset pagination. They keep
server memory bounded and do not hold an LMDB read transaction between requests.
Batch size defaults to 500 and is clamped to 1–1000.
cursor_find
Section titled “cursor_find”{ "op": "cursor_find", "coll": "events", "filter": {"tenant": "acme"}, "projection": {"type": 1, "at": 1}, "sort": [["_id", 1]], "skip": 0, "limit": 100000, "batch_size": 500, "comment": "export", "max_time_ms": 5000, "hint": "tenant"}sort must be omitted/empty or contain exactly one _id/$natural field with
1 or -1. Use a regular find for arbitrary sorts. limit is the total number of
documents the cursor may return, not a batch size. comment, max_time_ms, and
hint are stored with the cursor and applied to every page request.
cursor_aggregate
Section titled “cursor_aggregate”{ "op": "cursor_aggregate", "coll": "events", "pipeline": [ {"$match": {"tenant": "acme"}}, {"$project": {"type": 1, "at": 1}} ], "batch_size": 500, "comment": "export", "max_time_ms": 5000}Cursor aggregation supports an optional leading $match, then only
document-local stages that preserve one output per input: $project,
$addFields/$set, and $unset. Blocking stages ($group, $unwind,
$sort, $count, $skip, $limit, $setWindowFields, $densify, $fill,
$out, $merge) require a regular aggregate.
comment and max_time_ms are stored with the cursor and applied to every
page request. The deadline covers the $match/page find and is checked after
the document-local stages.
$facet accepts an object whose values are sub-pipelines and returns one
document containing an array of results for each name. $sample is random and
does not have a deterministic order. $replaceRoot/$replaceWith fail if the
expression does not evaluate to an object. $bucket requires strictly ascending
boundaries and an optional default for values outside them. $bucketAuto
supports groupBy, buckets, and output; the granularity option is not
implemented.
Both cursor operations return the first page:
{ "cursor_id": 7, "docs": [{"_id": "a", "type": "login"}], "has_more": true}get_more
Section titled “get_more”{"op": "get_more", "cursor_id": 7, "batch_size": 500}Returns {cursor_id, docs, has_more}. A cursor is single-consumer: concurrent
get_more calls return cursor_busy. Idle cursors expire after five minutes.
close_cursor
Section titled “close_cursor”{"op": "close_cursor", "cursor_id": 7}Returns {cursor_id, closed}. Closing an unknown or already-closed cursor is
not an error. Cursors are isolated by principal and are not supported for vault
collections.
Filters
Section titled “Filters”A filter is a JSON object. Multiple fields are combined with AND. An empty
object, null, or an omitted filter matches every document.
Field conditions
Section titled “Field conditions”| Condition | Meaning |
|---|---|
{"a": 1} |
Equality |
{"a": null} |
Field is null or missing |
{"a": {"$eq": 1}} |
Equality |
{"a": {"$ne": 1}} |
Not equal |
{"a": {"$gt": 1}} |
Greater than |
{"a": {"$gte": 1}} |
Greater than or equal |
{"a": {"$lt": 1}} |
Less than |
{"a": {"$lte": 1}} |
Less than or equal |
{"a": {"$in": [1, 2]}} |
Equal to one of the values |
{"a": {"$nin": [1, 2]}} |
Equal to none of the values |
{"a": {"$exists": true}} |
Field is present |
{"a": {"$all": [1, 2]}} |
Array contains all listed values |
{"a": {"$size": 2}} |
Array has exactly this length |
{"a": {"$elemMatch": {...}}} |
At least one array element matches |
{"a": {"$regex": "^foo", "$options": "i"}} |
String matches a regular expression |
{"a": {"$type": "string"}} |
Value has a BSON type |
{"a": {"$not": {...}}} |
Negate a field condition |
{"a": {"$mod": [4, 1]}} |
Numeric remainder |
{"a": {"$bitsAllSet": [1, 3]}} |
All listed bits are set |
{"a": {"$bitsAnySet": 1}} |
At least one mask bit is set |
{"$expr": {"$gt": ["$a", "$b"]}} |
Evaluate an aggregation expression |
{"$jsonSchema": {...}} |
Validate the document against a JSON Schema subset |
Missing fields and negation
Section titled “Missing fields and negation”Field-condition matching treats a missing field as null for equality:
{"a": null}and{"a": {"$eq": null}}match whenaisnullor absent.{"a": {"$ne": 1}}matches whenais absent, because a missing field is not equal to1.{"a": {"$ne": null}}does not match whenais absent ornull; it only matches documents whereais present and non-null.{"a": {"$nin": [1, 2]}}follows the same rule: missing fields match unlessnullis one of the listed values.
Use $exists when presence itself matters:
{"a": {"$exists": true}, "a": {"$ne": null}}This matches only documents where a is present and non-null. Use
{"a": {"$exists": false}} to match documents where a is absent.
Logical operators
Section titled “Logical operators”| Operator | Meaning |
|---|---|
{"$and": [f1, f2]} |
All filters match |
{"$or": [f1, f2]} |
At least one filter matches |
{"$nor": [f1, f2]} |
None of the filters match |
{"$not": f} |
Negate a filter (top level) |
Expressions with $expr
Section titled “Expressions with $expr”$expr evaluates the aggregation expression language against the current
document, so filters can compare fields or compute values:
{"$expr": {"$gt": ["$spent", "$budget"]}}{"$expr": {"$eq": [{"$add": ["$subtotal", "$tax"]}, "$total"]}}Missing fields evaluate to null. Invalid expressions and runtime errors (for
example division by zero) do not match the document. $expr conditions are
always applied by the matcher; indexes may still narrow the candidates using
ordinary field conditions in the same filter.
The expression evaluator supports comparison and boolean operators, arithmetic
($add, $subtract, $multiply, $divide, $mod, $pow, $abs, $ceil,
$floor, $round), $cond, $switch, $ifNull, $let, $map, $filter,
$reduce, $in, $isArray, $arrayElemAt, $slice, $concatArrays,
$objectToArray, $arrayToObject, $mergeObjects, string operators
($concat, $toLower, $toUpper, $substr, $substrCP, $strLenCP,
$split, $indexOfCP, $trim/$ltrim/$rtrim), $regexMatch, $min,
$max, $type, and $literal. Date operators are $dateAdd,
$dateSubtract, $dateDiff, $dateTrunc, $dateToString, $dateFromString,
$dateFromParts, and $dateToParts; time zones use UTC or fixed offsets such
as +02:00. Variables use $$name or $$name.path syntax inside $let,
$map, $filter, and $reduce.
$dateFromString accepts RFC 3339, custom formats such as %d/%m/%Y %H:%M:%S,
and naive input when timezone is provided. IANA time zone identifiers are not
supported.
Regex operands are accepted inside $in, $nin, and $all:
{"name": {"$in": [{"$regex": "^Al"}]}}{"tags": {"$all": [{"$regex": "^prod-"}]}}$jsonSchema
Section titled “$jsonSchema”$jsonSchema filters documents using a JSON Schema subset. Missing fields only
fail when listed in required; property schemas apply when the field exists.
{"$jsonSchema": { "bsonType": "object", "required": ["name", "age"], "properties": { "name": {"bsonType": "string", "minLength": 2, "pattern": "^A"}, "age": {"bsonType": "number", "minimum": 18}, "tags": {"bsonType": "array", "items": {"bsonType": "string"}} }}}Supported keywords: bsonType, required, properties, patternProperties,
additionalProperties, items, enum, const, minLength, maxLength,
pattern, minimum, maximum, exclusiveMinimum, exclusiveMaximum,
multipleOf, minItems, maxItems, uniqueItems, minProperties,
maxProperties, allOf, anyOf, oneOf, and not. Invalid schema shapes,
type names, and regexes are rejected before the query runs. Unknown JSON Schema
keywords are ignored.
Dates are values, not strings. Use Extended JSON in the document and in the filter operand:
{ "op": "find", "coll": "events", "filter": { "created_at": { "$gte": {"$date": "2026-01-01T00:00:00Z"}, "$lt": {"$date": "2026-02-01T00:00:00+01:00"} } }}Standard $eq, $gt, $gte, $lt, $lte, $in, and $nin compare dates
by instant. Different RFC 3339 offsets for the same instant are equal. Date
values do not match string values. See Dates and time zones.
Numbers and decimals
Section titled “Numbers and decimals”Ordinary JSON numbers, Decimal128, and special doubles share one numeric type bracket. Use Extended JSON for decimals:
{ "op": "find", "coll": "products", "filter": { "price": { "$gte": {"$numberDecimal": "10.00"}, "$lt": {"$numberDecimal": "100.00"} } }}{"$numberDecimal": "199.99"} is a Decimal128 value; NaN, Infinity, and
-Infinity are also accepted. {"$numberDouble": "NaN"}, "Infinity", and
"-Infinity" represent non-finite double values that JSON numbers cannot
express. {"$numberInt": "42"} and
{"$numberLong": "9007199254740993"} preserve their BSON integer type.
Integer comparison and index keys are exact, including values above 2^53.
See Numbers and decimals.
BSON scalar types and $type
Section titled “BSON scalar types and $type”Use Extended JSON for binary, UUID, ObjectId, Timestamp, and key sentinel values:
{"payload": {"$binary": {"base64": "YQ==", "subType": "00"}}}{"payload": {"$uuid": "00112233-4455-6677-8899-aabbccddeeff"}}{"ref": {"$oid": "000000000000000000000001"}}{"at": {"$timestamp": {"t": 1700000000, "i": 7}}}{"low": {"$minKey": 1}, "high": {"$maxKey": 1}}$uuid is normalized to binary subtype 04. ObjectId values are accepted both
as ordinary fields and as _id.
The $type operator accepts names, numeric BSON codes, or an array:
{"op": "find", "coll": "items", "filter": {"payload": {"$type": "binData"}}}{"op": "find", "coll": "items", "filter": {"ref": {"$type": ["objectId", 2]}}}Type names include double, string, object, array, binData,
objectId, bool, date, null, int, timestamp, long, decimal,
minKey, and maxKey; number matches any numeric type. Arrays match when the array itself or any element has
the requested type. See BSON scalar types.
Regular expressions
Section titled “Regular expressions”$regex accepts a pattern string and optional $options:
{"name": {"$regex": "^ada", "$options": "i"}}{"tags": {"$regex": "^rus"}}Supported options are i (case-insensitive), m (multiline), s (dot
matches newline), x (ignore whitespace), and u (Unicode; already the
default). Arrays match when any string element matches. Only string values can
match; missing fields, numbers, booleans, dates, binary, and ObjectId values do
not.
The compiled-pattern form is also accepted:
{"name": {"$regex": {"$regularExpression": {"pattern": "^ada", "options": "i"}}}}Patterns use Rust’s non-backtracking regex engine and are limited to 4 KiB.
Invalid patterns or options return invalid_query. Case-sensitive patterns
anchored with ^ can use a string-index prefix range; the residual matcher
still verifies every candidate.
Arrays
Section titled “Arrays”$all requires the field to contain every listed value:
{"tags": {"$all": ["rust", "lmdb"]}}$all is equivalent to equality for a single value, so a scalar field also
matches. An empty $all matches nothing.
$size requires an exact array length:
{"tags": {"$size": 2}}$elemMatch requires at least one array element to satisfy all conditions.
For scalar elements, use field operators; for object elements, use a normal
filter:
{"scores": {"$elemMatch": {"$gte": 8, "$lt": 10}}}{"items": {"$elemMatch": {"sku": "x", "qty": {"$gt": 5}}}}Malformed arguments return invalid_query: $all must be an array, $size a
non-negative integer, and $elemMatch an object. Multikey indexes serve array
equality, $all, ranges, and simple $elemMatch conditions; $size still
requires a scan. Regex values inside $all/$elemMatch are not supported.
Semantics
Section titled “Semantics”- Numbers compare by value and exactly.
30equals30.0; Decimal128 and other numeric types participate in the same bracket. Large integers are not rounded throughf64. - Type-aware ranges. A numeric
$gtdoes not match strings or booleans. - Dates compare by instant. Offsets are ignored after parsing; date and string values remain different types.
- Missing fields are
nullfor equality.{"missing": null}matches absent fields;$existsdistinguishes presentnullfrom absent. - Array membership.
{"tags": "rust"}matches a document wheretagsis["rust", "lmdb"]. - Nested paths. Dots traverse nested objects (
{"a.b.c": 7}) and arrays of objects ({"items.price": {"$gte": 10}}). - No
$whereoperator, and the HTTP/core query language has no$textoperator. Full-text search is a separate operation. The optional MongoDB wire listener accepts$textwith MongoDB-style text indexes.
Projection
Section titled “Projection”Projection is an include/exclude map. Dotted paths build nested output and traverse arrays of objects:
{ "user.name": 1, "items.sku": 1, "_id": 0}- If any non-
_idfield has a truthy value, the projection is inclusive. - Otherwise it is exclusive; listed paths are removed, including fields inside array elements.
_idis included by default."_id": 0excludes it.$slicereturns a prefix/suffix of an array or a window:{"tags": {"$slice": 3}},{"tags": {"$slice": -2}}, and{"items.tags": {"$slice": [2, 3]}}.$elemMatchprojection returns the first array element matching the condition:{"items": {"$elemMatch": {"qty": {"$gt": 5}}}}.- Positional
$returns the first array element selected by the query filter:{"items.$": 1}with{"items.qty": {"$gt": 5}}. The positional path must be the final path segment. $metasupportstextScore/searchScore(from_score),indexKey(from_indexKey), andsortKey(from_sortKey). NonoDB does uses the_scoreproduced by native search; documents without_scoreprojecttextScoreas0.0.- Covering indexes can satisfy a top-level inclusive projection using indexed
and
included fields without fetching the document. Nested and positional projections fetch the full document.
Sorting
Section titled “Sorting”sort is an array of pairs:
"sort": [["priority", -1], ["created_at", 1]]Directions: 1 ascending, -1 descending. Missing values and null sort
last. Equal keys are ordered deterministically by _id.
An index can serve the sort when the requested sort matches the full index field order and its per-field directions, or when every direction is inverted for a reverse index scan. Mixed-direction compound indexes therefore sort without a top-K fallback. A multikey sort uses the lowest array element for ascending order and the highest for descending order, with same-document duplicates removed. Otherwise nonodb performs a scan and bounded top-K sort. Full-collection sorts and selective unsorted scans are parallelized for shallow queries.
create_index
Section titled “create_index”Single-field index:
{"op": "create_index", "coll": "users", "field": "email", "unique": true}Compound index with covering fields:
{ "op": "create_index", "coll": "events", "fields": ["tenant", "kind", "created_at"], "unique": false, "include": ["payload", "status"]}Response:
{ "ok": true, "result": { "created": "tenant+kind+created_at", "fields": ["tenant", "kind", "created_at"], "unique": false, "include": ["payload", "status"] }}create_indexes
Section titled “create_indexes”Creates several indexes in one collection scan. Parsing and key encoding run in parallel; all index writes still happen in one LMDB write transaction.
{ "op": "create_indexes", "coll": "events", "indexes": [ {"field": "tenant", "unique": false}, {"fields": ["tenant", "created_at"], "unique": false}, {"field": "tags", "include": ["status"]} ]}Response:
{"ok": true, "result": {"created": ["tenant", "tenant+created_at", "tags"]}}Each entry accepts either field or fields, plus optional name,
directions, unique, and include. Use this for migrations that add
multiple indexes at once; it avoids re-reading and re-parsing the whole
collection for every index.
Rules:
- Provide either
field(single) orfields(ordered list).fieldsis preferred for new code. - Without
name, the index name is the fields joined by+. A supplied MongoDB-style name is stored and returned bylist_indexes. directionsis optional; when present it must contain one1or-1per field. Newly created and reindexed indexes encode descending fields into key order, so mixed-direction compound indexes can serve matching sorts. Indexes created by older versions keep valid ascending storage and can be rebuilt with the reindex operation to gain direction-aware ordering.- Indexable values are string, number, Decimal128, special doubles, boolean,
Extended JSON dates, binary/UUID, and ObjectId. Ordinary objects remain
unindexed, but arrays create multikey entries: one key per scalar element.
Dotted fields expand arrays of objects, so an index on
items.priceindexes everypricevalue. - A compound index may contain at most one array field. Parallel arrays are
rejected during index creation or write with
invalid_query. - A unique index enforces uniqueness of the full key. For compound indexes,
that means the combination, not each field individually. A unique multikey
index accepts repeated elements within the same document (
tags: ["x","x"]) but rejects the same key in another document. - Creating an index on an existing collection performs a synchronous backfill. Writers are blocked while the backfill write transaction is active.
includecopies extra fields into index values for covering projections. Included fields are not part of the index key or uniqueness constraint.- Indexes are maintained transactionally on insert, update, and delete.
- Dates are indexed by instant and support normal range plans, sorting, and unique constraints. No index type annotation is required.
- Numbers use an exact, order-preserving decimal encoding. Decimal128 shares
the numeric type tag, so
1,1.0, andNumberDecimal("1")share a key. - Index format version 5 adds multikey array entries. Older indexes do not contain array documents and are not used for planning; recreate them after upgrading. See BSON scalar types.
- Multikey filter ranges deduplicate document ids.
$allintersects one index range per value, and$elemMatchcan use a dotted index on the matching element path.$sizestill requires a scan.
reindex
Section titled “reindex”Rebuild every secondary, text, fuzzy, and vector index on one collection from the current documents:
{"op": "reindex", "coll": "events"}Response:
{ "ok": true, "result": { "reindexed": "events", "secondary": ["tenant", "tenant+created_at"], "text": ["body"], "fuzzy": ["name"], "vector": ["embedding"] }}reindex drops and recreates each existing index definition in a single write
transaction. It is the one-click migration path after an index-format upgrade or
when index data is suspected to be incomplete. The text and fuzzy arrays
contain search-index names; native single-field helpers name the index after the
field, while MongoDB-style text indexes keep their declared name and fields.
The operation scans every
document and blocks writers for the duration; it does not change index
definitions, uniqueness, include, geo, vector dimensions, or metrics. If the
rebuild fails, the transaction rolls back and the previous indexes remain
usable.
Use create_indexes when adding new indexes, and reindex when rebuilding the
existing set.
Geo index
Section titled “Geo index”Create a single-field GeoJSON point index:
{"op": "create_index", "coll": "places", "field": "loc", "geo": true}Documents use a GeoJSON Point:
{"_id": "waw", "loc": {"type": "Point", "coordinates": [21.01, 52.23]}}The create_indexes form accepts the same geo flag:
{"op": "create_indexes", "coll": "places", "indexes": [{"field": "loc", "geo": true}]}Geo indexes must have exactly one field and cannot be unique or covering. They are maintained transactionally on insert, update, and delete.
Geospatial queries
Section titled “Geospatial queries”$near / $nearSphere returns matches ordered by distance. Distances are in
meters and use a spherical Earth model:
{ "op": "find", "coll": "places", "filter": { "loc": { "$near": { "$geometry": {"type": "Point", "coordinates": [21.01, 52.23]}, "$minDistance": 0, "$maxDistance": 5000 } } }, "limit": 20}With $maxDistance, a matching geo index narrows the candidate cells. Without
$maxDistance, the query still returns distance order but falls back to a
collection scan.
$geoWithin accepts:
{"loc": {"$geoWithin": {"$box": [[20.0, 51.0], [22.0, 53.0]]}}}{"loc": {"$geoWithin": {"$centerSphere": [[21.01, 52.23], 0.01]}}}{"loc": {"$geoWithin": {"$polygon": [[20, 51], [22, 51], [22, 53], [20, 53]]}}}{"loc": {"$geoWithin": {"$geometry": {"type": "Polygon", "coordinates": [[[20,51],[22,51],[22,53],[20,53],[20,51]]]}}}}$centerSphere uses radians for its radius. $geoIntersects accepts
{"$geometry": ...} and matches point documents against the supplied geometry.
Geo index rules and limitations:
- Only GeoJSON
Pointdocuments are indexed.PolygonandMultiPolygongeometries are supported in query arguments. - Point-in-polygon checks use lon/lat planar geometry; distance checks use haversine meters. This is accurate for ordinary city/region queries but is not a full spherical topology engine.
- A geo index uses a hierarchy of lon/lat grid cells. Large queries may choose a coarser level, so the residual filter always verifies the exact result.
$nearcannot be combined with an explicitsort.
drop_index
Section titled “drop_index”{"op": "drop_index", "coll": "users", "field": "email"}For a compound index, pass the generated name ("grp+age"). Response:
{"ok": true, "result": {"dropped": true}}dropped is false if the index did not exist. The index contents are
removed and its reusable LMDB slot is returned to the pool.
list_indexes
Section titled “list_indexes”{"op": "list_indexes", "coll": "users"}Response:
{ "ok": true, "result": { "indexes": [ { "field": "email", "fields": ["email"], "unique": true, "include": [], "format": 5, "geo": false, "multikey_fields": [], "multikey_all_docs": true } ] }}multikey_fields lists indexed fields that produced array entries.
multikey_all_docs is true only while every document has at least one entry,
which is required for an index to provide multikey sort order.
Full-text indexes
Section titled “Full-text indexes”Create, drop, and list:
{"op": "create_text_index", "coll": "articles", "field": "body"}{"op": "drop_text_index", "coll": "articles", "field": "body"}{"op": "list_text_indexes", "coll": "articles"}Responses:
{"ok": true, "result": {"created": "body", "kind": "text"}}{"ok": true, "result": {"dropped": true, "kind": "text"}}{"ok": true, "result": {"text_indexes": ["body"]}}The index is maintained in the same transaction as document writes. Creation backfills existing documents synchronously.
Fuzzy indexes
Section titled “Fuzzy indexes”{"op": "create_fuzzy_index", "coll": "articles", "field": "title"}{"op": "drop_fuzzy_index", "coll": "articles", "field": "title"}{"op": "list_fuzzy_indexes", "coll": "articles"}Responses mirror text indexes:
{"ok": true, "result": {"created": "title", "kind": "fuzzy"}}{"ok": true, "result": {"fuzzy_indexes": ["title"]}}search
Section titled “search”{ "op": "search", "coll": "articles", "field": "body", "query": "rust async \"zero copy\"", "filter": {"published": true}, "skip": 0, "limit": 10}Response:
{ "ok": true, "result": { "results": [ {"_id": "...", "body": "...", "_score": 4.82} ] }}Semantics:
- The text index must exist; otherwise
invalid_query. - Terms are ORed. BM25 ranks documents by relevance.
- Duplicate terms in the query are removed.
- Quoted phrases must occur as contiguous token sequences.
filteris a residual document filter applied before pagination.skipandlimitapply after filtering and phrase checks.limitdefaults to 10 and is capped at 1,000._scoreis added to each result. Higher is better.- Tokenization lowercases and folds diacritics.
zazolcmatcheszażółć.
{ "op": "fuzzy", "coll": "articles", "field": "title", "query": "postgress", "max_distance": 2, "filter": {"published": true}, "limit": 10}Response:
{ "ok": true, "result": { "results": [ {"_id": "...", "title": "PostgreSQL", "_distance": 1} ] }}Semantics:
- The fuzzy index must exist; otherwise
invalid_query. - Candidate generation uses shared trigrams; final ranking uses bounded Levenshtein distance.
- Distance is measured against the whole normalized field value or the closest token.
max_distancedefaults to 2._distanceis added to each result; lower is better.- There is no
skipparameter for fuzzy search. limitdefaults to 10 and is capped at 1,000.- At most 5,000 candidates are scored per query.
- String, boolean, and all numeric scalar values are searched, including
$numberInt,$numberLong,$numberDouble, and$numberDecimal. Arrays, objects, dates, binary/UUID, and ObjectId values are skipped.
Vector indexes
Section titled “Vector indexes”Create, drop, and list:
{"op": "create_vector_index", "coll": "articles", "field": "embedding", "dims": 384, "metric": "cosine"}{"op": "drop_vector_index", "coll": "articles", "field": "embedding"}{"op": "list_vector_indexes", "coll": "articles"}Responses:
{"ok": true, "result": {"created": "embedding", "kind": "vector", "dims": 384, "metric": "cosine"}}{"ok": true, "result": {"dropped": true, "kind": "vector"}}{"ok": true, "result": {"vector_indexes": [{"field": "embedding", "dims": 384, "metric": "cosine", "format": 1}]}}Semantics:
dimsis required and must be between 1 and 65,536.metriciscosine(default),dot, orl2.- The document field must be a JSON array of exactly
dimsfinite numbers. Missing, malformed, or wrong-length vectors are not indexed; writes still succeed. - One vector per document per index is supported.
- The index is maintained in the same transaction as document inserts, updates, deletes, TTL expiry, and restores.
- Creating the index backfills existing documents synchronously.
vector_search
Section titled “vector_search”{ "op": "vector_search", "coll": "articles", "field": "embedding", "vector": [0.12, -0.03, 0.44], "filter": {"published": true}, "skip": 0, "limit": 10}Response:
{ "ok": true, "result": { "results": [ {"_id": "...", "title": "...", "embedding": [0.12, -0.03, 0.44], "_distance": 0.08} ] }}Semantics:
- The vector index must exist; otherwise
invalid_query. - The query vector must have exactly the indexed
dims. - Search is exact and scans the whole index:
O(N × dims)per query. There is no approximate index or recall loss. _distanceis added to each result; lower is better:cosine:1 - cosine_similarity(0 is identical),dot: negative dot product,l2: squared Euclidean distance.
- Results are sorted by
_distance, then_id. filteris a normal document filter applied before final selection. If it is an exact_idor can use a secondary index with at most 50,000 candidates, the matching documents are checked first. Otherwise the vector index is scanned and candidates are checked until enough matches are found.- A highly selective filter on an unindexed field can inspect most documents and approach a full collection scan. Create a secondary index for selective filters.
skipandlimitapply after ranking.limitdefaults to 10 and is capped at 1,000.- Vectors are stored in LMDB; no external vector service is used.
Document history
Section titled “Document history”History is configured per collection and is stored separately from the current
collection. Searches, indexes, find, count, update, and
delete always operate on current documents only. Every write receives a
global monotonic rev; revisions for one document are therefore ordered but
not necessarily consecutive.
For a history-enabled collection, inserts, updates, and deletes record revisions or delete tombstones. The history append is atomic with the current-document change.
history
Section titled “history”{ "op": "history", "coll": "users", "id": "0b7f...", "limit": 50, "include_docs": true}Result, newest first:
{ "revisions": [ { "rev": 1042, "op": "update", "at": 1710000000123, "deleted": false, "doc": {"_id": "0b7f...", "name": "Ala"} }, { "rev": 1001, "op": "insert", "at": 1710000000000, "deleted": false, "doc": {"_id": "0b7f...", "name": "Alicja"} } ]}limit defaults to 50 and is capped at 1000. With include_docs: false,
metadata is returned without full documents.
get_version
Section titled “get_version”{ "op": "get_version", "coll": "users", "id": "0b7f...", "version": 1001}rev is accepted as an alias for version. The result is one revision object,
or null if that revision no longer exists. A deleted document has a tombstone
with "deleted": true and no document body.
History retention is configured per collection with set_collection_history.
0 disables new history writes. The daemon maintenance worker submits bounded
pruning jobs to the single writer; pruning never scans history on the hot write
path.
set_collection_history
Section titled “set_collection_history”{"op":"set_collection_history","coll":"users","max_versions":50}Sets how many revisions are retained per document in that collection. 0
disables new history writes. Requires admin:<collection>.
get_collection_history
Section titled “get_collection_history”{"op":"get_collection_history","coll":"users"}Returns {"coll":"users","max_versions":50}. Requires
read:<collection>.
Automatic collection events
Section titled “Automatic collection events”set_collection_events
Section titled “set_collection_events”Configure automatic insert/update/delete events for a standard collection:
{ "op": "set_collection_events", "coll": "orders", "enabled": true, "ops": ["insert", "update"], "fields": ["status", "total"], "filter": {"payload.after.status": "paid"}, "include_before": false, "include_after": true, "projection": {"status": 1, "total": 1}}fields=[] means any changed top-level field. With a non-empty list, update
events are emitted only when at least one listed field changed. ops=[] means
all operations. filter suppresses non-matching events before they are stored.
include_before/include_after and projection control the stored payload. Events are written atomically to _events as
<collection>.<insert|update|delete> documents. Vault collections are not
auto-evented.
get_collection_events
Section titled “get_collection_events”Read the setting:
{"op":"get_collection_events","coll":"orders"}Response:
{"coll":"orders","enabled":true,"fields":["status","total"]}set_collection_events requires admin:<collection>;
get_collection_events requires read:<collection>. See
Outbox events.
Conditional subscriptions
Section titled “Conditional subscriptions”Persistent subscriptions evaluate a client-defined condition over collection state on every write. They are different from event-count stream thresholds and from automatic events.
{"op":"create_subscription","coll":"orders","name":"paid","ops":["insert","update","delete"],"filter":{"status":"paid"},"lease_seconds":600}{"op":"renew_subscription","coll":"orders","name":"paid","lease_seconds":600}{"op":"create_subscription","coll":"orders","name":"many","count":{"filter":{"total":{"$gt":100}},"gt":100}}{"op":"create_subscription","coll":"orders","name":"high_once","filter":{"total":{"$gt":100}},"once":true}{"op":"list_subscriptions","coll":"orders"}{"op":"delete_subscription","coll":"orders","name":"paid"}By default every write whose condition is true emits an event. The optional
once:true flag changes this to edge-triggered (false -> true). ops=[] means
all operations. filter applies to the after document for insert/update and the
before document for delete. count is evaluated over current collection state
after the write; support comparisons gt, gte, lt, lte, eq, default
gt:0.
Events are stored in _events with default type subscription.<name> (or the
optional event_type) and payload fields subscription, coll, op, before,
after, and count. They commit atomically with the write and can be consumed
with watch, /v1/watch, or EventConsumer.
Persistent subscriptions are leased. lease_seconds defaults to 600; the
client must call renew_subscription before expiry. Expired subscriptions stop
evaluating conditions and are removed by the writer or the maintenance sweep.
Expiry removes the subscription only, not existing _events documents.
create_subscription, renew_subscription, and delete_subscription require
admin:<collection>; list_subscriptions requires read:<collection>. See
Conditional subscriptions.
Document TTL
Section titled “Document TTL”TTL is optional and eventual. A document may remain readable briefly after its expiry until the maintenance sweeper commits the delete.
Collection default:
{"op":"create_collection","coll":"sessions","ttl_seconds":86400}{"op":"set_collection_ttl","coll":"sessions","ttl_seconds":3600}{"op":"set_collection_ttl","coll":"sessions","ttl_seconds":null}{"op":"set_collection_ttl","coll":"sessions","ttl_seconds":3600,"purge_history":true}{"op":"get_collection_ttl","coll":"sessions"}set_collection_ttl response:
{"ok":true,"result":{"coll":"sessions","ttl_seconds":3600,"purge_history":false}}get_collection_ttl response:
{"ok":true,"result":{"coll":"sessions","ttl_seconds":3600,"purge_history":false}}Per-document override:
{"op":"insert","coll":"sessions","doc":{"_id":"s1","user":7,"_ttl":300}}Rules:
_ttloverrides the collection default;_ttl: 0ornulldisables expiry.- A missing
_ttlinherits the collection default; without either, the document does not expire. ttl_secondsmust be positive. Negative, fractional, or non-numeric_ttlvalues returninvalid_ttl.- Updates preserve the existing expiry unless the update result contains an
explicit
_ttl. Replacement updates and upserts follow the same rule. $unsetof_ttldoes not clear an expiry; use$setwith0ornull.- Expiry deletes the document through the normal write path and appends a
history tombstone when history is enabled. With
purge_history: true, stored revisions are deleted instead of adding a tombstone. - TTL works for vault collections; the sweeper deletes the ciphertext without decrypting it.
See Document TTL for maintenance, metrics, and operational details.
Read batch
Section titled “Read batch”{ "op": "batch", "ops": [ {"op": "find_one", "coll": "users", "filter": {"_id": "..."}}, {"op": "count", "coll": "users", "filter": {"active": true}}, {"op": "list_indexes", "coll": "users"} ]}Response:
{ "ok": true, "result": { "results": [ {"ok": true, "result": {"_id": "...", "name": "Ada"}}, {"ok": true, "result": {"count": 12}}, {"ok": true, "result": {"indexes": []}} ] }}Rules:
- Allowed operations:
find,find_one,lookup,count,list_indexes,list_text_indexes,list_fuzzy_indexes,list_vector_indexes,list_collections,history,get_version,search,fuzzy,vector_search. - Every operation executes against one
RoTxn, so the batch sees a single consistent snapshot. - An error in one operation does not stop the others. Each result has its own
okand eitherresultorerror. - A write operation is rejected per-operation with
invalid_queryand the messageonly read ops are allowed in batch. - There is no transaction or snapshot shared with later requests.
Atomic write batch
Section titled “Atomic write batch”{ "op": "write_batch", "ops": [ {"op": "insert", "coll": "users", "doc": {"_id": "u1", "name": "Ada"}}, {"op": "update", "coll": "counters", "filter": {"_id": "hits"}, "update": {"$inc": {"n": 1}}}, {"op": "delete", "coll": "sessions", "filter": {"_id": "s1"}} ]}Response:
{ "ok": true, "result": { "results": [ {"inserted_id": "u1"}, {"matched": 1, "modified": 1, "upserted_id": null}, {"deleted": 1} ] }}Rules:
- Allowed operations:
insert,insert_many,update,delete. updatesupportsmultiandupsertinside the batch.- The whole batch is executed in one LMDB write transaction. If any operation fails, the transaction is rolled back and no operation in the batch is visible.
- The error message identifies the failing operation by index:
write_batch operation 1 failed: .... write_batchis isolated from group commit. It does not share a transaction with unrelated requests, because its rollback must not affect them.- Operations execute in order, and later operations in the same batch see earlier uncommitted changes. Use a read batch for independent reads.
create_collection
Section titled “create_collection”{ "op": "create_collection", "coll": "vault", "profile": "vault"}Response:
{"ok": true, "result": {"created": "vault", "profile": "vault", "ttl_seconds": null, "purge_history": false}}profile is standard (default) or vault. An existing collection cannot be
converted between profiles; the request fails with
vault_profile_immutable.
An optional ttl_seconds sets the default document TTL for new inserts.
ttl_purge_history controls whether TTL expiry deletes stored history:
{ "op": "create_collection", "coll": "sessions", "profile": "standard", "ttl_seconds": 86400, "ttl_purge_history": false}History is configured separately per collection with set_collection_history;
new collections start with retention 0 (disabled).
list_collections
Section titled “list_collections”{"op": "list_collections"}Response:
{"ok": true, "result": {"collections": ["users", "settings"]}}Standard collections are created on first write. Vault collections should be
created explicitly with create_collection.
database_stats
Section titled “database_stats”{"op": "database_stats"}Returns record counts and storage estimates for every collection visible to the caller. It requires no database-admin scope; collections outside the caller’s scopes are omitted and the totals are recalculated.
{ "ok": true, "result": { "database": "default", "map_size": 1073741824, "used_bytes": 734003200, "free_bytes": 339738624, "page_size": 4096, "total_records": 1000000, "collection_bytes": 612000000, "collections": [ { "collection": "records", "records": 1000000, "data_bytes": 512000000, "index_bytes": 96000000, "indexes": 7, "history_bytes": 0, "ttl_bytes": 0, "total_bytes": 608000000, "requests_last_minute": 240, "avg_requests_per_second": 4.0 } ] }}data_bytes and index_bytes are allocated LMDB B-tree pages
((branch + leaf + overflow) * page_size). history_bytes and ttl_bytes are
estimated from shared history/TTL keys and values. requests_last_minute is a
rolling 60-second request count and avg_requests_per_second is that count
divided by 60. used_bytes is the LMDB file high-water mark and can exceed the
sum of collection totals because LMDB keeps freed pages and does not shrink the
file.
Vault operation summary
Section titled “Vault operation summary”For a vault collection, insert, insert_many, find, find_one, count,
update, delete, history, and get_version require the vault headers.
Only exact _id / tenant_id filters are accepted, update/delete require one
exact _id, and sort is limited to _id. Search, fuzzy search, aggregation,
indexes, batch, and write_batch are rejected with
unsupported_encrypted_operation.
See Vault collections.
LMDB map size
Section titled “LMDB map size”map_info
Section titled “map_info”{"op": "map_info"}Response:
{"ok": true, "result": { "map_size": 1073741824, "used_bytes": 7340032, "free_bytes": 1066401792, "page_size": 4096}}map_size is the address-space limit, not disk or RAM usage. used_bytes is
the LMDB high-water mark.
resize_map
Section titled “resize_map”{"op": "resize_map", "size": 4294967296}Response:
{"ok": true, "result": {"old_size": 1073741824, "map_size": 4294967296}}size is in bytes and must be a multiple of page_size and at least the
current map size. The operation waits for active transactions and temporarily
blocks new ones. It only grows the map; shrinking requires an offline restart.
See Operations.
Health and metrics
Section titled “Health and metrics”GET /v1/server
Section titled “GET /v1/server”Authenticated admin endpoint. Returns the daemon’s real listener state:
{ "ok": true, "result": { "version": "0.26.0", "tcp": {"configured": "0.0.0.0:7902", "bound": "0.0.0.0:7902", "tls": false}, "unix": "/run/nonodb.sock", "advertise_url": "http://10.0.0.10:7902" }}bound is the resolved socket address. Use it to verify that a remote replica
can reach this node before generating a pairing code.
GET /healthz
Section titled “GET /healthz”Public, no authentication.
{"ok": true}DELETE /v1/replication/acks/{node}
Section titled “DELETE /v1/replication/acks/{node}”Removes the stored acknowledgement and remembered URL for one replica from the
selected database (default database when unscoped), and blocks further ACKs from
that node id. A live replica receives 403 replica_removed. Redeeming a new
pairing code for the same node id clears the block. This does not stop the
remote process or delete its data.
POST /v1/replication/pause / resume / disconnect
Section titled “POST /v1/replication/pause / resume / disconnect”Admin-only replica controls:
POST /v1/replication/pausePOST /v1/replication/resumePOST /v1/replication/disconnectpause sets a persisted paused flag; the source and token remain. resume
clears it and the pull loop continues from the stored source. disconnect
removes the source and token from the hidden node state, stops pulling, and
keeps the node read-only. None of these operations delete local data or promote
the node.
GET /v1/network
Section titled “GET /v1/network”Authenticated admin endpoint. Returns listener state, firewall backend status, saved allow-list/ports, and generated nftables rules:
{ "ok": true, "result": { "listeners": {"tcp": {"configured": "0.0.0.0:7902", "bound": "0.0.0.0:7902", "tls": false}}, "firewall": {"available": true, "backend": "nftables", "apply_enabled": false, "managed": false}, "allowed": ["10.0.0.0/24"], "ports": [7902], "preview": "table inet nonodb_firewall { ... }" }}PUT /v1/network/firewall
Section titled “PUT /v1/network/firewall”Validates and saves the allow-list and ports, then returns the updated
/v1/network view. Body:
{"allowed": ["10.0.0.0/24", "192.168.1.20"], "ports": [7902, 7912]}Bare addresses are normalized to /32 or /128. Invalid CIDRs, ports, or an
unreasonably large list return 400 invalid_firewall.
POST /v1/network/firewall/apply
Section titled “POST /v1/network/firewall/apply”Applies the saved rules to the dedicated inet nonodb_firewall table. Requires
NONODB_FIREWALL_MANAGE=1 on the daemon and nftables privileges. The daemon
validates the rules with nft --check before replacing the table.
DELETE /v1/network/firewall
Section titled “DELETE /v1/network/firewall”Removes the dedicated managed table. Other host firewall rules are untouched.
Per-collection metrics
Section titled “Per-collection metrics”Runtime counters are tracked separately for every database/collection pair.
Collection-level reads require only read:<collection>; the full daemon-wide
snapshot at GET /metrics still requires admin:db.
{"op":"get_collection_metrics","coll":"orders"}{ "ok": true, "result": { "database": "default", "collection": "orders", "requests_total": 1200, "read_ops_total": 900, "write_requests_total": 300, "cache_hits_total": 540, "cache_misses_total": 360, "errors_total": 2, "request_ns_total": 1840000000, "last_request_us": 620.4, "avg_request_us": 1533.3 }}requests_total counts requests that touched the collection. Batch requests
count once per collection. read_ops_total and write_requests_total count
successful read and write requests; errors_total counts failed requests.
avg_request_us and last_request_us are wall-clock request durations.
Counters reset when the daemon restarts and are capped at 4096 distinct
collection series to bound memory; collection_metrics_overflow_total reports
requests for series beyond the cap.
GET /metrics
Section titled “GET /metrics”Requires metrics:read, admin:db, or *:*. The Unix socket authenticates as
the local administrator; TCP requires a bearer token or registered client
certificate. GET /metrics/prometheus exposes the same counters in Prometheus
text format and uses the same scopes. See Monitoring.
{ "requests_total": 12345, "errors_total": 2, "read_ops_total": 10000, "batch_ops_total": 3000, "write_ops_total": 2000, "write_batches_total": 250, "queue_len": 0, "queue_peak": 80, "commit_ns_total": 182000000, "avg_batch_size": 8.0, "avg_commit_us": 728.0, "collection_metrics": [ { "database": "default", "collection": "orders", "requests_total": 1200, "read_ops_total": 900, "write_requests_total": 300, "cache_hits_total": 540, "cache_misses_total": 360, "errors_total": 2, "avg_request_us": 1533.3 } ], "collection_metrics_overflow_total": 0, "latency": [ { "operation": "find", "buckets_ns": [100000, 500000, 1000000], "buckets": [0, 2, 4], "count": 7, "sum_ns": 8123000 } ], "latency_series_overflow_total": 0}| Metric | Meaning |
|---|---|
requests_total |
HTTP /v1/exec and /v1/watch requests |
errors_total |
Error responses |
read_ops_total |
Read operations handled |
batch_ops_total |
Operations inside read batches |
write_ops_total |
Write operations executed |
write_batches_total |
Write transactions committed |
queue_len |
Current writer queue length |
queue_peak |
Peak writer queue length since start |
commit_ns_total |
Cumulative commit time in nanoseconds |
ttl_sweeps_total |
TTL sweeps performed |
ttl_expired_total |
Documents deleted by TTL |
ttl_sweep_errors_total |
Failed TTL sweeps |
ttl_backlog |
Due entries observed by the last sweep |
index_builds |
Active/recent index, text, fuzzy, and vector backfills with processed/total/elapsed |
collection_metrics |
Per-database/collection requests, reads, writes, cache, errors, and latency |
collection_metrics_overflow_total |
Requests omitted after the 4096-series cap |
latency |
Per-operation end-to-end latency buckets, count, and total duration |
latency_series_overflow_total |
Latency series omitted after the operation-series cap |
avg_batch_size |
Write ops per committed write transaction |
avg_commit_us |
Average commit time in microseconds |
Authorization management API
Section titled “Authorization management API”These endpoints manage the same NONODB_AUTH_FILE used by nonodb-cli auth.
They require an enabled admin:db principal. Plaintext bearer tokens are
returned only once by POST /v1/auth/tokens; the registry stores only their
SHA-256 hashes. The daemon never logs token bodies.
| Method | Path | Purpose |
|---|---|---|
GET |
/v1/auth |
Registry generation, principals, token metadata, certificate metadata |
POST |
/v1/auth/principals |
Create a principal ({"name","scopes"}) |
PUT |
/v1/auth/principals/{name} |
Replace a principal’s scopes ({"scopes"}) |
DELETE |
/v1/auth/principals/{name} |
Delete an unreferenced principal |
POST |
/v1/auth/tokens |
Create a token ({"principal","kid"?}); returns plaintext once |
PATCH |
/v1/auth/tokens/{kid} |
Enable/disable a token (`{“disabled”:true |
POST |
/v1/auth/certificates |
Register a client certificate ({"sha256","principal"}) |
PATCH |
/v1/auth/certificates/{sha256} |
Enable/disable a certificate (`{“disabled”:true |
Example:
curl -s -H "Authorization: Bearer $NONODB_TOKEN" \ -H 'content-type: application/json' \ -d '{"name":"reporting","scopes":["read:app1/orders"]}' \ http://127.0.0.1:7878/v1/auth/principalsMutations are validated and written atomically under the auth-file lock, then reloaded immediately. The API refuses changes that would leave no enabled administrator credential. A principal still referenced by a token or certificate cannot be deleted. All successful and failed mutations are written to the audit log when audit logging is enabled.
GET /readyz
Section titled “GET /readyz”Public. Checks the writer thread and a real LMDB read transaction.
{"ok":true,"checks":{"writer":true,"storage":true,"storage_error":null}}Returns HTTP 503 with the same shape when the writer has stopped or LMDB
cannot serve a read transaction.
Backup jobs API
Section titled “Backup jobs API”Scheduled backup jobs are managed under /v1/backups. All routes require
admin:db or *:* because backup configuration can expose data and paths.
| Method | Path | Purpose |
|---|---|---|
GET |
/v1/backups |
Configured jobs plus last/next run, status, size, and errors |
POST |
/v1/backups/jobs |
Create or replace a job (BackupJob JSON) |
DELETE |
/v1/backups/jobs/{id} |
Delete a job and its state entry |
POST |
/v1/backups/jobs/{id}/run |
Start a job asynchronously |
POST |
/v1/backups/keygen |
Write a new age identity/recipient pair; returns only the public recipient |
POST |
/v1/backups/secret |
Write a generated restic password file with mode 0600 |
GET /v1/backups also returns key_dir, default_identity_file,
default_recipient_file, and default_restic_password_file. Key files default
to <NONODB_DATA>/backup-keys, overridable with NONODB_BACKUP_KEY_DIR.
Example job:
{ "id": "nightly-default", "databases": ["default", "app1"], "enabled": true, "every_minutes": 1440, "destination": { "kind": "local", "path": "/var/backups/nonodb" }, "encryption": { "kind": "age", "recipient_file": "/etc/nonodb/backup-recipient.txt" }, "keep_last": 14, "verify": true, "compression": "gzip", "exclude_collections": ["audit_scratch"]}compression may be none (default) or gzip. It applies to native local/S3
jobs and runs before optional age encryption. Restic manages its own
compression. databases selects one or more databases for the job. The legacy database
field is still accepted for existing configs; when both are present, databases
wins. exclude_collections removes those collections from every selected
database copy, including their indexes, history, TTL, events, and subscription
metadata. The live databases are unchanged.
destination.kind may be local, s3, or restic:
{ "kind": "s3", "endpoint": "https://<account>.r2.cloudflarestorage.com", "bucket": "nonodb-backups", "region": "auto", "prefix": "prod/nonodb", "access_key_env": "AWS_ACCESS_KEY_ID", "secret_key_env": "AWS_SECRET_ACCESS_KEY", "session_token_env": "AWS_SESSION_TOKEN"}Restic destination:
{ "kind": "restic", "repository": "s3:https://<account>.r2.cloudflarestorage.com/bucket/prefix", "password_file": "/etc/nonodb/restic-password", "binary": "restic"}Restic jobs must not also set encryption; restic handles encryption itself.
Key generation:
POST /v1/backups/keygen{"identity_file":"/etc/nonodb/backup-identity.txt","recipient_file":"/etc/nonodb/backup-recipient.txt"}Returns identity_file, recipient_file, and the public recipient. Both files
must not already exist. The identity is written with mode 0600 and is never
returned.
POST /v1/backups/secret{"path":"/etc/nonodb/restic-password"}Writes a random restic password with mode 0600 and returns only the path.
See Backup and restore for encryption keys, layouts, retention, and restore.
Import API
Section titled “Import API”Admin-only staged import of native backups into a new database. The live database is never replaced.
| Method | Path | Purpose |
|---|---|---|
GET |
/v1/import |
Allowed local roots and recent import jobs |
POST |
/v1/import/browse |
Discover backups in a local folder or S3/R2 prefix |
POST |
/v1/import/run |
Start a staged import into a new database |
GET |
/v1/import/status/{id} |
Import status and error |
Browse example:
POST /v1/import/browse{ "source": { "kind": "s3", "endpoint": "https://<account>.r2.cloudflarestorage.com", "bucket": "nonodb-backups", "region": "auto", "prefix": "prod/nonodb", "access_key_env": "AWS_ACCESS_KEY_ID", "secret_key_env": "AWS_SECRET_ACCESS_KEY" }}Run example:
POST /v1/import/run{ "source": {"kind": "local", "path": "/var/lib/nonodb/backups"}, "location": "/var/lib/nonodb/backups/nightly-default/1794599334414/default", "target_database": "restored-default"}Local locations must be under NONODB_IMPORT_ROOTS (default
<NONODB_DATA>/backups). Encrypted imports require
NONODB_BACKUP_IDENTITY_FILE in the daemon environment. The importer verifies
the manifest checksum, decrypts/decompresses, runs deep LMDB verification, and
refuses to overwrite an existing database.
Replication API
Section titled “Replication API”Replication is built in. A primary captures one ordered record per committed write transaction; replicas pull over HTTP, TLS, or mutual TLS and stay read-only until promoted. These endpoints expose the log, source management, pause/resume/disconnect controls, bootstrap, promotion, and cluster status.
| Method | Path | Purpose |
|---|---|---|
GET |
/v1/replication/status |
Replication role, epoch, origin, head, applied sources, acks, and write_url |
GET |
/v1/replication/primary |
Admin-only current write endpoint and role |
GET |
/readyz/write |
Unauthenticated write-routing health check; 200 only on a writable primary |
GET |
/v1/replication/changes?after=0&limit=100 |
Read committed replication transactions after a sequence |
GET |
/{database}/v1/replication/status |
Same status for a selected database |
GET |
/{database}/v1/replication/changes |
Changes for a selected database |
GET |
/v1/replication/snapshot |
Stream a consistent compacted LMDB snapshot |
POST |
/v1/replication/prune |
Delete log entries through { "through": N } |
GET |
/{database}/v1/replication/snapshot |
Snapshot for a selected database |
POST |
/{database}/v1/replication/prune |
Prune a selected database |
POST |
/v1/replication/ack |
Record a replica applied-sequence acknowledgement |
GET |
/v1/replication/acks |
List replica acknowledgements, ages, and the minimum safe sequence |
POST |
/v1/replication/promote |
Promote to primary using expected_epoch; optionally fence the old source, or force |
POST |
/v1/replication/demote |
Manually demote with expected_epoch, optional role, and optional successor URL |
PUT |
/v1/replication/source |
Persist a new pull source and reload the loop |
POST |
/v1/replication/pause |
Pause pulling while keeping the source and token |
POST |
/v1/replication/resume |
Resume pulling from the stored source |
POST |
/v1/replication/disconnect |
Remove source/token, stop pulling, keep the node read-only |
POST |
/v1/replication/vote |
Cast or inspect a quorum vote for (epoch, candidate) |
POST |
/v1/replication/lease |
Renew a candidate’s quorum lease |
GET |
/v1/replication/pairings |
List pending one-time replica pairing codes (admin) |
POST |
/v1/replication/pairings |
Create an 8-character pairing code for a replica (admin) |
DELETE |
/v1/replication/pairings/{code} |
Revoke a pending pairing code (admin) |
POST |
/v1/replication/pair |
Redeem a one-time pairing code and issue a cluster credential |
POST |
/v1/replication/join |
Local admin endpoint used by nonodb-cli replication join |
All routes require admin:db or *:*. Snapshot and prune are intended for
replica bootstrap and controlled retention. Prune accepts
{"through": N, "require_acks": true} and refuses to advance past the minimum
acknowledged replica sequence. Promote/demote are instance-wide
role changes persisted in the hidden node metadata collection
<NONODB_DATA>/.node. The pull source, vote, lease, and peer token are stored
there as well.
The primary publishes a hidden __nonodb_control document through the durable
replication log. It contains the auth registry snapshot (token hashes and
certificate fingerprints), backup jobs/state, database catalog, and cluster peer
token. Replicas apply it immediately but only run write-side services after
promotion. A primary with configured voters is read-only until it acquires a
quorum lease. A change transaction contains an
origin, seq, epoch, created_at_ms, and grouped changes with
collection, op, id, and before/after documents. Replicas reject stale epochs. Replication is disabled unless
NONODB_REPLICATION_ENABLED=1.
Error codes
Section titled “Error codes”| Code | HTTP | Meaning |
|---|---|---|
invalid_query |
400 | Invalid filter/update/index/query shape, write in a read batch, unsupported operator |
unsafe_durability_disabled |
400 | durability:"unsafe" without NONODB_ALLOW_UNSAFE_WRITES=1 |
database_limit |
503 | Too many open databases and no idle environment can be evicted |
invalid_sql |
400 | SQL parse/planning error or unsupported SQL clause |
invalid_json |
400 | Malformed JSON document or value |
invalid_collection |
400 | Invalid collection name |
invalid_id |
400 | _id is not a string or ObjectId |
duplicate_key |
400 | Duplicate _id or unique-index conflict |
document_too_large |
413 | Document exceeds 1 MiB |
result_too_large |
413 | lookup result budget exceeds 64 MiB |
invalid_ttl |
400 | Invalid collection default or document _ttl value |
invalid_date |
400 | Invalid $date payload, RFC 3339 string, or missing timezone |
invalid_numeric |
400 | Invalid Extended JSON number or decimal arithmetic overflow |
invalid_binary |
400 | Invalid $binary/$uuid payload or base64 |
invalid_object_id |
400 | $oid is not 24 hexadecimal characters |
invalid_auth_request |
400/409 | Invalid auth mutation, referenced principal, or last-admin protection |
auth_disabled |
400 | Authorization registry is not configured |
unauthorized |
401 | Missing/invalid/disabled credential |
forbidden |
403 | Principal lacks the required scope |
read_only |
403 | Replica/standby rejected a write; response includes Location and error.write_url for the primary |
rate_limited |
429 | Too many failed logins from this IP; wait and retry |
timeout |
500 | Request exceeded the server timeout |
cursor_not_found |
400 | Cursor is unknown, expired, closed, or belongs to another principal |
cursor_busy |
400 | Another get_more is already reading this cursor |
storage |
500 | LMDB/storage error |
io |
500 | Filesystem or I/O error |
internal |
500 | Internal daemon error |
vault_key_required |
400 | Vault headers are missing |
vault_key_unexpected |
400 | Vault headers sent to a standard collection |
invalid_vault_key |
400 | Invalid or wrong-length vault key |
tenant_mismatch |
400 | Tenant/document/filter mismatch |
decryption_failed |
400 | Wrong key, tenant, key id, or corrupted envelope |
unsupported_encrypted_operation |
400 | Operation not available for vault collections |
invalid_vault_filter |
400 | Vault filter or multi update/delete is not allowed |
invalid_vault_document |
400 | Invalid vault document shape |
vault_profile_immutable |
400 | Collection profile cannot be changed |
invalid_collection_profile |
400 | Unknown collection profile |
not_a_vault_collection |
400 | Collection does not exist or is not a vault collection |
curl examples
Section titled “curl examples”S=/tmp/nonodb.sock
# insertcurl -s --unix-socket "$S" -H 'content-type: application/json' \ -X POST http://localhost/v1/exec \ -d '{"op":"insert","coll":"users","doc":{"name":"Ada","age":36}}'
# indexed range querycurl -s --unix-socket "$S" -H 'content-type: application/json' \ -X POST http://localhost/v1/exec \ -d '{"op":"find","coll":"users","filter":{"age":{"$gte":18,"$lt":65}}, "sort":[["age",1]],"limit":10}'
# atomic incrementcurl -s --unix-socket "$S" -H 'content-type: application/json' \ -X POST http://localhost/v1/exec \ -d '{"op":"update","coll":"counters","filter":{"_id":"hits"}, "update":{"$inc":{"n":1}}}'
# full-text searchcurl -s --unix-socket "$S" -H 'content-type: application/json' \ -X POST http://localhost/v1/exec \ -d '{"op":"search","coll":"articles","field":"body", "query":"rust async","limit":5}'
# metricscurl -s --unix-socket "$S" http://localhost/metricsSee the Python client for a higher-level interface and the Operations guide for deployment and security.