Query language¶

JSON query DSL, v1

Every read surface (REST /v1/query, /v1/snapshot, gRPC Query/Snapshot, and the MCP findRecords/semanticSearch tools) compiles the same JSON document into one logical plan. This page is the field-by-field grammar; the fixture corpus is the grammar of record.

Shape at a glance¶

{
  "v": 1,
  "find": "RISK",
  "where": {
    "severity": { "$gte": 7 },
    "$or": [
      { "status": { "$eq": "open" } },
      { "$and": [{ "owner": { "$exists": true } }] }
    ]
  },
  "atValidTime": "2025-05-01T00:00:00Z",
  "atTxTime": "2025-06-01T00:00:00Z",
  "expand": [{ "type": "OWNED_BY", "direction": "out", "depth": 1 }],
  "vector": { "text": "supply chain delays", "model": "m1", "k": 20, "minScore": 0.5 },
  "limit": 100,
  "cursor": "opaque",
  "trace": false
}

Deserialization is strict (deny_unknown_fields): an unknown top-level field, an unknown operator, or the wrong type at any position is rejected with a JSON pointer to the exact spot, not a generic 400.

Top-level fields¶

The executor's logical plan runs the stages in a fixed order: TemporalResolve → Scan|IndexScan → Filter → Expand → VectorScore → Paginate → Trace.

Predicates (where)¶

Every predicate is an operator object keyed by property path, never a bare scalar:

{ "find": "RISK", "where": { "severity": { "$gte": 5 } } }

{ "find": "RISK", "where": { "severity": 5 } }

{
  "code": "QUERY_INVALID",
  "message": "/where/severity: expected an operator object like {\"$eq\": ...}",
  "request_id": "..."
}

Operators¶

A property may carry multiple operators in one object (implicit AND): {"severity": {"$gte": 3, "$lte": 8}}.

Logical blocks: $and / $or¶

$and and $or take an array of predicate objects, non-empty, and nest up to depth 8:

{
  "find": "RISK",
  "where": {
    "$or": [
      { "status": { "$eq": "open" } },
      { "$and": [{ "sev": { "$gte": 7 } }, { "owner": { "$exists": true } }] }
    ]
  }
}

Only $and and $or are recognized logical keys; anything else starting with $ at that position (e.g. $nor) is unknown operator at that pointer.

Dotted paths¶

v1 supports one level of dotted-path predicates into Object values: "data.owner". Deeper paths are deferred (spec OQ-1) until schema inference tracks nested shapes.

{ "find": "RISK", "where": { "data.owner": { "$eq": "kim" } } }

Type semantics¶

Comparisons are type-strict against the engine's Value enum: Int and Float coerce against each other; comparing Str against Int is a validation error when the label's inferred schema knows the type, otherwise it is a runtime type mismatch that skips the row (and is counted in stats.typeMismatches, visible when trace: true).

Temporal coordinates¶

atValidTime and atTxTime each accept either a unix-microseconds integer or an RFC3339 string:

{ "find": "RISK", "atValidTime": 1750000000000000 }

{ "find": "RISK", "atValidTime": "2025-05-01T00:00:00Z" }

Omitting both means "current state." See The tritemporal model for what each axis means and worked examples of pinning one or both. An unparseable RFC3339 string is rejected at the field's pointer:

{ "code": "QUERY_INVALID", "message": "/atValidTime: invalid RFC3339 timestamp: ...", "request_id": "..." }

Expand¶

expand walks the graph from each primary result. Two forms:

{ "find": "RISK", "expand": ["OWNED_BY"] }

{
  "find": "RISK",
  "expand": [{ "type": "OWNED_BY", "direction": "out", "depth": 1 }]
}

Ceilings: at most 4 expand entries per query; depth outside 1..=3 is rejected at /expand/{i}/depth; more than 4 entries is rejected at /expand ("at most 4 expand entries allowed"). An unrecognized shape (bad direction value, or a stray field like dpeth) fails serde's untagged-enum match and reports /expand/{i}: data did not match any variant.

Expanded neighbors come back in the response's related array, grouped by which expand entry produced them, they are never merged into the primary records list.

Vector¶

vector adds semantic scoring, fused with any structured filter:

{ "find": "RISK", "vector": { "text": "supply chain delays", "model": "m1", "k": 20, "minScore": 0.5 } }

Validation:

• Supplying both text and near → QUERY_INVALID at /vector ("not both").
• Supplying neither → QUERY_INVALID at /vector ("required").
• k: 0 → /vector/k ("at least 1").
• minScore or alpha outside [0, 1] → /vector/minScore or /vector/alpha.
• An unknown field (e.g. temperature) → /vector/temperature: unknown field.

Scores surface as score on each primary record and each related node when a vector clause is present. Primary results are then ordered by score descending rather than key order.

Limit and cursor¶

• limit: integer, 1..=1000, default 100. Outside range → QUERY_INVALID at /limit ("limit must be 1..=1000").
• cursor: an opaque, HMAC-signed continuation token from a previous page's nextCursor. It encodes the scan position, a scope hash (tenant-checked on resume), and a plan hash (the resumed query must be identical apart from the cursor). A tampered, foreign-tenant, or mismatched-plan cursor is rejected as BAD_CURSOR.

Trace¶

"trace": true asks the executor to attach a per-stage execution trace to the response (see stats in the REST API response shape: path, bitmapCandidates, rowsScanned, rowsFilteredOut, typeMismatches, rowsReturned, durationUs).

Ceilings reference¶

These are server ceilings, not tenant-configurable in v1. The MCP tool surface layers its own, tighter ceilings on top (findRecords clamps expand depth to 2 and limit to the server's row cap, and drops cursor entirely), see MCP tools.

Worked examples from the corpus¶

{ "find": "RISK" }

{ "find": "RISK", "where": { "severity": { "$gte": 3, "$lte": 8 } } }

{
  "find": "RISK",
  "where": {
    "$or": [
      { "status": { "$eq": "open" } },
      { "$and": [{ "sev": { "$gte": 7 } }, { "owner": { "$exists": true } }] }
    ]
  }
}

{ "find": "RISK", "atValidTime": 1750000000000000, "atTxTime": 1750000100000000 }

{ "find": "RISK", "expand": ["A", "B", "C", "D"] }

{ "find": "RISK", "vector": { "near": [0.1, 0.2, 0.3], "model": "m1", "k": 5, "minScore": 0.5 } }

Query DSL by transport¶

Related¶

• REST API - /v1/query, /v1/snapshot, /v1/compare endpoints
• gRPC API - Query/Snapshot RPCs carrying this DSL as bytes
• MCP tools - findRecords/semanticSearch subset and ceilings
• The tritemporal model - what atValidTime/atTxTime mean
• Error reference - the full error code table