QueryDocument v1

QueryDocumentV1 is the plain-data form of a Ramose query. It is accepted by MCP query and emitted by the TypeScript builder.

New here? Start with How queries work.

Top-level shape

interface QueryDocumentV1 {
  version: 1
  from: DefinitionRef
  where?: Predicate
  select: Record<string, Selection>
  order?: Order[]
  page: { first: number; after?: string }
}

All collections are bounded. Unknown keys, definitions, fields, operators, and incompatible values are rejected rather than ignored.

Definition references

{ "kind": "entity", "name": "task" }

from may reference a visible entity or trait returned by describe. References are catalog-scoped names, not internal ids.

Field paths

Paths are arrays of public field and relationship keys:

{ "path": ["assignee", "name"] }

Array paths avoid ambiguous string escaping and validate one segment at a time.

Predicates

Leaf predicates have an operator, path, and compatible value:

{ "op": "eq", "path": ["done"], "value": false }

Logical predicates nest explicit arguments:

{
  "op": "and",
  "args": [
    { "op": "eq", "path": ["done"], "value": false },
    { "op": "in", "path": ["priority"], "value": ["high", "urgent"] }
  ]
}

Supported leaf operators are catalog- and type-aware. They include equality, ordering comparisons, membership, presence, and bounded text predicates. Discovery describes the operators valid for a field.

Selection

Each result key maps to a field path or bounded nested selection:

{
  "select": {
    "id": { "path": ["id"] },
    "title": { "path": ["title"] },
    "assignee": {
      "select": { "name": { "path": ["name"] } }
    }
  }
}

Result keys are caller-chosen plain JSON keys. Selection does not grant access to a hidden field.

Ordering and pagination

{
  "order": [
    { "path": ["updatedAt"], "direction": "desc" },
    { "path": ["id"], "direction": "asc" }
  ],
  "page": { "first": 50, "after": "cursor_opaque" }
}

The response contains an opaque continuation cursor when another page is available. Do not decode, modify, cache across principals, or reuse it with a different database or query.

Validation errors

invalid_query: malformed grammar, bad operator, type mismatch, missing bound, or invalid cursor.
unknown_definition: the referenced public definition is not in the current visible catalog.
inaccessible: the requested capability cannot be revealed.
catalog_changed: ifCatalog does not match; rediscover and rebuild the query.
query_budget_exceeded: the valid query exceeds configured work limits; narrow it.