Skip to content

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) and GET /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.

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.

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:

Terminal window
NONODB_ALLOW_UNSAFE_WRITES=1

With 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.

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.

Requests against a vault collection must also send all three headers:

X-NonoDB-Tenant: acme
X-NonoDB-Key-Id: acme:v1
X-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.

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.

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

{
"op": "insert",
"coll": "users",
"doc": {"name": "Ada", "age": 36}
}

Response:

{"ok": true, "result": {"inserted_id": "4f0b5f6e-..."}}
  • The document must be a JSON object.
  • If _id is omitted, a UUID v4 string is generated.
  • If _id is 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 _id or a unique-index conflict fails with duplicate_key.
  • _id is the primary key. Treat it as immutable.
  • The reserved top-level _ttl field sets a per-document expiry in seconds. _ttl: 0 or null disables 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.
{
"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_ms is enforced during collection/index scans, including parallel scans, sorted scans, and $near candidates. When the budget expires, the request fails with error code timeout.
  • hint accepts "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 with invalid_query rather 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 _id order.
  • Without sort, results follow the cheapest scan order (index order or _id order), and execution stops after skip + limit matches.
  • Equality or range conditions on _id use the primary-key B+ tree directly. Sorting by a single _id field can stream that range forwards or backwards.
  • With sort, results are ordered by the requested fields. Missing values and null sort 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; _id is included by default and can be disabled with "_id": 0. Dotted paths create nested projection trees.
{
"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.

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:

  • by defaults to _id.

  • A non-_id lookup requires a unique index whose field order exactly matches by; otherwise the request returns invalid_query.

  • by may 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; found is the number of non-null results.

  • Duplicate input values produce duplicate result entries. Repeated keys are looked up only once internally.

  • values is limited to 10,000 entries per request.

  • fields is a top-level inclusive projection. If every requested field is available in a covering index created with include, the document is not read from the main collection. Otherwise the normal document fetch is used.

  • projection accepts a normal flat projection and allows excluding _id:

    {
    "op": "lookup",
    "coll": "users",
    "by": "email",
    "values": ["ada@example.com"],
    "projection": {"name": 1, "_id": 0}
    }

    fields and projection are mutually exclusive. A covering index is used only for an inclusive projection (or fields).

  • _id is included by default when using fields.

  • 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.

  • lookup does not accept filter, sort, skip, or limit. Use find for 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
}
  • after is optional. Omit it to start from the beginning of the collection.
  • limit defaults to 100; values are clamped to 1..=1000.
  • timeout_ms defaults to 1000; values are clamped to 0..=25000.
  • types filters event documents by their type field.
  • filter applies an additional MongoDB-style filter.
  • projection is optional; _id is always retained for the resume token.
  • next is the last returned _id, or after when no event arrived.
  • timed_out is true only when the timeout expired with no events.
  • has_more is true when another page is immediately available.
  • truncated is true when after is older than retained events; oldest is the oldest event id still available.
  • watch requires read scope on coll, is not cacheable, and is rejected inside a read batch. Vault collections are rejected.

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, default 15,000, range 100..60,000;
  • timeout_ms — maximum stream lifetime; absent or 0 means no limit;
  • overlap_ms — late-commit rescan window, default 2,000, max 60,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 over coll;
  • 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.

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.

{
"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

An update is either:

  1. an operator object — every top-level key starts with $; or
  2. 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.

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:

  • $push and $addToSet replace a non-array existing value with a new array. This is destructive; ensure the field is intended to be an array.
  • $addToSet uses the same equality semantics as filters. Numbers compare by value (1 == 1.0), and objects compare structurally.
  • $pull accepts either a value or a query predicate (for example $gte, $in, or a field condition for array elements that are objects).
  • $push modifier 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 with null; $unset on an array index sets that element to null.
  • _id is immutable. Do not use $set/$unset/array operators on _id.
  • $currentDate supports dates and BSON Timestamp ({"$type": "timestamp"}).
  • Update pipelines support the stages listed above; other stages return invalid_query.

When upsert=true and no document matches:

  1. Equality conditions from the filter become the seed document. Conditions inside $and and {"field": {"$eq": value}} are included. Range conditions and other operators are ignored.
  2. Operators are applied. $setOnInsert runs only for this insert.
  3. A filter _id is preserved.
  4. 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.

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.

{
"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: {} / null uses 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 count does not materialize results.
  • max_time_ms bounds index and collection scanning and returns the timeout error code when the budget expires. comment is accepted for request correlation but is not stored.
{
"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.

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.

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 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": "$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]]}

Joins documents from another collection:

{
"$lookup": {
"from": "items",
"localField": "sku",
"foreignField": "sku",
"as": "item"
}
}
  • localField may be an array; each element is matched against foreignField.
  • A missing local field is treated as null, matching foreign documents whose field is null or missing.
  • An optional pipeline runs on the matching foreign documents. A pipeline-only lookup (no localField/foreignField) scans the foreign collection and then applies the pipeline.
  • let binds per-input-document variables that the sub-pipeline can read as $$name, including inside $expr.
  • Nested $lookup stages are supported in the sub-pipeline.
  • Missing foreign collections produce empty arrays.
  • The result is written to as as an array. The aggregate intermediate-document limit still applies.

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.

Recursively traverses references in another collection:

{
"$graphLookup": {
"from": "employees",
"startWith": "$reportsTo",
"connectFromField": "reportsTo",
"connectToField": "_id",
"as": "managementChain",
"maxDepth": 5,
"depthField": "depth",
"restrictSearchWithMatch": {"active": true}
}
}
  • startWith is evaluated per input document and may produce a scalar or an array of starting values.
  • At each hop, documents where connectToField matches any current value are added to as; their connectFromField values become the next hop.
  • maxDepth limits the number of hop expansions. 0 returns only the initial matches; omit it to traverse until no new documents are found.
  • depthField adds the zero-based hop depth to each joined document.
  • restrictSearchWithMatch filters 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 as arrays.
  • The aggregate intermediate-document limit applies to each as result.

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}}
}
}
}
  • partitionBy is evaluated per document; omitted means one partition.
  • sortBy accepts 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.documents accepts unbounded, current, or integer offsets for both bounds.
  • window.range accepts unbounded, current, or numeric offsets. It requires exactly one sortBy field. Numeric sort fields use numeric offsets. Date sort fields require a unit (year, quarter, month, week, day, hour, minute, second, millisecond) and use calendar-aware offsets.
  • Advanced analytics: $expMovingAvg (input plus N or alpha), $derivative (input, optional unit), and $integral (input, optional unit). $expMovingAvg follows partition order; $derivative and $integral require exactly one sortBy field and accept a documents or range window.
  • Ranking operators: $rank, $denseRank, and $documentNumber, which require sortBy.
  • $shift supports output, integer by, and optional default.
  • The aggregate intermediate-document limit still applies.

Adds documents for missing values in a numeric or date field:

{
"$densify": {
"field": "ts",
"partitionByFields": ["sensor"],
"range": {"step": 1, "unit": "day", "bounds": "partition"}
}
}
  • field is a dotted path; partitionByFields is an optional array of paths.
  • Without unit, step is a positive number and the field values must be numeric.
  • With unit, step is a positive integer and the field values must be dates. Supported units are year, quarter, month, week, day, hour, minute, second, and millisecond.
  • bounds is partition (default), full, or an explicit [lower, upper] pair. Bounds are inclusive. full uses 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"}
}
}
}
  • partitionBy is an expression; partitionByFields is an optional array of paths. They cannot be combined.
  • sortBy uses the normal sort object. It is required for linear; locf uses the partition order when no sort is supplied.
  • value fills missing or null fields with the evaluated expression.
  • locf carries the previous non-null value forward. Values before the first non-null value are left unchanged.
  • linear interpolates numeric values between known points using the first sortBy field 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 linear output field return invalid_query.
  • Each output field is computed from the input documents before any $fill results are written, so output fields do not depend on each other.

Replaces the target collection contents with the pipeline result:

{
"$out": "daily_totals"
}
  • $out must 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 _events collection is rejected.
  • The response contains results: [], plus target, deleted, and inserted counters.

Merges the pipeline result into an existing or new collection:

{
"$merge": {
"into": "customers",
"on": "email",
"whenMatched": "merge",
"whenNotMatched": "insert"
}
}
  • $merge must be the last stage.
  • into accepts a collection name or {"coll": "...", "db": "..."} in the current database.
  • on is a field name or array of field names. It defaults to _id. Fields other than _id require an existing unique index on exactly those fields.
  • whenMatched defaults to merge:
    • 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 — return invalid_query.
  • whenNotMatched defaults to insert:
    • insert — insert the result document;
    • discard — skip it;
    • fail — return invalid_query.
  • A result document that contains _id must use the same _id as a matched target document. Changing _id is rejected.
  • whenMatched may be a pipeline. It runs on the existing target document as the root, with $$new bound to the incoming result document. Only $set/ $addFields, $project, $unset, and $replaceRoot/$replaceWith are allowed. The pipeline must produce one object and cannot change _id.
  • let defines variables available as $$name in a whenMatched pipeline. Values are evaluated against each incoming result document.
  • The response contains results: [], plus target, matched, modified, inserted, and skipped counters.
  • At most 100,000 documents may exist in an intermediate result. The call returns invalid_query if 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 $limit and $project for large collections.
  • Not supported: $redact and 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;
  • WHERE with comparisons, AND/OR/NOT, parentheses, IN, BETWEEN, IS NULL, and LIKE;
  • GROUP BY, HAVING, ORDER BY, LIMIT, and OFFSET;
  • aggregate functions COUNT, COUNT(DISTINCT field), SUM, AVG, MIN, and MAX;
  • 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.

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 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.

{
"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.

{
"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
}
{"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.

{"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.

A filter is a JSON object. Multiple fields are combined with AND. An empty object, null, or an omitted filter matches every document.

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

Field-condition matching treats a missing field as null for equality:

  • {"a": null} and {"a": {"$eq": null}} match when a is null or absent.
  • {"a": {"$ne": 1}} matches when a is absent, because a missing field is not equal to 1.
  • {"a": {"$ne": null}} does not match when a is absent or null; it only matches documents where a is present and non-null.
  • {"a": {"$nin": [1, 2]}} follows the same rule: missing fields match unless null is 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.

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)

$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 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.

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.

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.

$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.

$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.

  • Numbers compare by value and exactly. 30 equals 30.0; Decimal128 and other numeric types participate in the same bracket. Large integers are not rounded through f64.
  • Type-aware ranges. A numeric $gt does not match strings or booleans.
  • Dates compare by instant. Offsets are ignored after parsing; date and string values remain different types.
  • Missing fields are null for equality. {"missing": null} matches absent fields; $exists distinguishes present null from absent.
  • Array membership. {"tags": "rust"} matches a document where tags is ["rust", "lmdb"].
  • Nested paths. Dots traverse nested objects ({"a.b.c": 7}) and arrays of objects ({"items.price": {"$gte": 10}}).
  • No $where operator, and the HTTP/core query language has no $text operator. Full-text search is a separate operation. The optional MongoDB wire listener accepts $text with MongoDB-style text indexes.

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-_id field has a truthy value, the projection is inclusive.
  • Otherwise it is exclusive; listed paths are removed, including fields inside array elements.
  • _id is included by default. "_id": 0 excludes it.
  • $slice returns a prefix/suffix of an array or a window: {"tags": {"$slice": 3}}, {"tags": {"$slice": -2}}, and {"items.tags": {"$slice": [2, 3]}}.
  • $elemMatch projection 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.
  • $meta supports textScore/searchScore (from _score), indexKey (from _indexKey), and sortKey (from _sortKey). NonoDB does uses the _score produced by native search; documents without _score project textScore as 0.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.

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.


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"]
}
}

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) or fields (ordered list). fields is preferred for new code.
  • Without name, the index name is the fields joined by +. A supplied MongoDB-style name is stored and returned by list_indexes.
  • directions is optional; when present it must contain one 1 or -1 per 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.price indexes every price value.
  • 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.
  • include copies 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, and NumberDecimal("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. $all intersects one index range per value, and $elemMatch can use a dotted index on the matching element path. $size still requires a scan.

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.

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.

$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 Point documents are indexed. Polygon and MultiPolygon geometries 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.
  • $near cannot be combined with an explicit sort.
{"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.

{"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.

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.

{"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"]}}
{
"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.
  • filter is a residual document filter applied before pagination.
  • skip and limit apply after filtering and phrase checks.
  • limit defaults to 10 and is capped at 1,000.
  • _score is added to each result. Higher is better.
  • Tokenization lowercases and folds diacritics. zazolc matches zażółć.
{
"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_distance defaults to 2.
  • _distance is added to each result; lower is better.
  • There is no skip parameter for fuzzy search.
  • limit defaults 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.

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:

  • dims is required and must be between 1 and 65,536.
  • metric is cosine (default), dot, or l2.
  • The document field must be a JSON array of exactly dims finite 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.
{
"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.
  • _distance is 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.
  • filter is a normal document filter applied before final selection. If it is an exact _id or 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.
  • skip and limit apply after ranking. limit defaults to 10 and is capped at 1,000.
  • Vectors are stored in LMDB; no external vector service is used.

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.

{
"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.

{
"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.

{"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>.

{"op":"get_collection_history","coll":"users"}

Returns {"coll":"users","max_versions":50}. Requires read:<collection>.

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.

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.

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.

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:

  • _ttl overrides the collection default; _ttl: 0 or null disables expiry.
  • A missing _ttl inherits the collection default; without either, the document does not expire.
  • ttl_seconds must be positive. Negative, fractional, or non-numeric _ttl values return invalid_ttl.
  • Updates preserve the existing expiry unless the update result contains an explicit _ttl. Replacement updates and upserts follow the same rule.
  • $unset of _ttl does not clear an expiry; use $set with 0 or null.
  • 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.

{
"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 ok and either result or error.
  • A write operation is rejected per-operation with invalid_query and the message only read ops are allowed in batch.
  • There is no transaction or snapshot shared with later requests.
{
"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.
  • update supports multi and upsert inside 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_batch is 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.
{
"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).

{"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.

{"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.

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.


{"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.

{"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.

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.

Public, no authentication.

{"ok": true}

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/pause
POST /v1/replication/resume
POST /v1/replication/disconnect

pause 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.

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 { ... }"
}
}

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.

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.

Removes the dedicated managed table. Other host firewall rules are untouched.

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.

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

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:

Terminal window
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/principals

Mutations 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.

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.

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.

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 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.

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
Terminal window
S=/tmp/nonodb.sock
# insert
curl -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 query
curl -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 increment
curl -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 search
curl -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}'
# metrics
curl -s --unix-socket "$S" http://localhost/metrics

See the Python client for a higher-level interface and the Operations guide for deployment and security.