Queries and graphs
Filter documents, follow meaningful relationships and preserve the context of an answer.
Status: Design. RURAL's public query, schema-aware predicate and graph layers are planned. Ordered byte-map iteration exists as a foundation; it is not a query planner.
Ask for the records you need
The intended query interface combines filters, selected fields, ordering, limits and a consistent snapshot. Typical requests should be straightforward: open tasks for a project, decisions that reference an older governance version, or events associated with a deployment.
Initial predicate requirements include equality, inequality, ordered comparison, membership and existence, combined with AND/OR. Nested paths identify fields without requiring the engine to execute user-supplied code.
| Case | Intended meaning |
|---|---|
| Missing field compared with null | Different values; inequality is true. |
| Existence check | Reports whether a field is present, including when its value is null. |
| Ordering | Missing sorts before null; comparable non-null values use their declared type. |
| Strings | Unicode code-point ordering, with no implicit locale collation or normalization. |
| Numbers | Exact supported comparisons or an explicit unsupported-domain error. |
| Registered fields | Validate both the field name/path and the operand type. |
These semantics are design commitments, not a released query-language specification. Broad SQL syntax and SurrealQL compatibility are outside the initial contract.
Give relationships their own identity
A property edge can connect a task to a project, a decision to evidence, or a deployment to the repository record it changed. An edge has a declared relation type and may carry properties such as when a relationship became effective.
Traversal should answer a bounded question: follow a named relation in a direction, to a limited depth, with explicit node/edge/work budgets. Cycles are ordinary graph data; they must not create unbounded execution.
Endpoint deletion, cardinality and uniqueness need defined transactional behavior. Adding an edge to a deleted endpoint or merging two individually valid branches can violate a graph invariant, so validation belongs at the candidate-state boundary.
Keep an answer in one world
A query must identify its branch and snapshot. Stable pagination requires either a retained snapshot or an explicit error when the requested view is no longer available. Quietly continuing over a changed dataset is not stable pagination.
Indexes are an execution tool. Their state must correspond to the same committed root as the documents they describe. A plan that exceeds its admitted work budget must fail visibly rather than silently omit records.
Worlds and branches explains the visibility model. Oracle and MCP shows how computed results become concise, inspectable answers.