Reference
Queries
Reading ontology and runtime state — requests, paging, errors.
Queries read state without changing it: ontology entities and relationships, or worker runtime records. Writes go through Write policies; reads come here.
Ontology read queries
Named, versioned queries against ontology state — published once, run many times with different inputs.
| Request field | Meaning |
|---|---|
| Inputs | Named values the query binds (ids, filters, ranges) |
| Cursor | Page token for large result sets |
| Job id | Long-running execution to poll instead of waiting |
| Offset / limit | Simple paging — never combined with cursor or job |
{
"input": { "account_id": "cust-acme", "since": "2026-01-01" },
"options": { "limit": 50, "offset": 0 }
}A second example — resuming a large export:
{
"input": { "account_id": "cust-acme" },
"options": { "cursor": "eyJwYWdlIjoyfQ" }
}| Rule | Why |
|---|---|
| Cursor or job, never both | Two continuation mechanisms conflict |
| No offset with cursor/job | Offsets only make sense from the start |
| Published queries only | Unpublished definitions cannot execute |
Query errors
| Code family | Meaning | First action |
|---|---|---|
| Forbidden / caller required | Permissions | Check access, not syntax |
| Invalid request / input / definition / output | Shape problems | Read the message, fix the named field |
| Not found / not published / retired | Lifecycle | Publish or pick the live release |
| Execution failed / downstream unavailable | Runtime | Retry transients, investigate persistents |
| Expired / canceled / concurrency limit | Operations | Re-run, narrow scope, stagger load |
| Ambiguous value | Semantics | Disambiguate the binding |
Worker runtime queries
Direct reads over runtime records — select, filter, order, page:
{
"select": ["run_id", "status", "finished_at"],
"where": [{ "field": "status", "op": "eq", "value": "failed" }],
"orderBy": [{ "field": "finished_at", "dir": "desc" }],
"limit": 25
}| Field | Meaning |
|---|---|
| Select | Columns to return — narrow is faster |
| Where | Filter predicates |
| Order by | Sort for review queues (newest failures first) |
| Limit / offset | Page size up to 10k, position |
Targets name the store: table, database, collection, path, or schema — the same vocabulary as Data endpoints.
Image: query with bindings, paged results, and an error message naming the offending field.
Choosing well
- Published ontology queries for repeated questions; worker reads for investigation and review queues.
- Cursor through large results; never offset from a cursor.
- Read error codes as categories first, messages second.