QQL reference

Use bound values, nested fields, joins and conditional writes through the common transaction engine.

On this page

Filter, sort and page

Submit QQL with op: "query" and a bindings object. Bind values instead of interpolating strings. LIMIT defaults to 100; LIMIT plus OFFSET must fit the current 10,000-row working window. Separate page requests do not pin a common snapshot.

sql

SELECT title, status FROM projects
WHERE workspace = :workspace AND status = "active"
SORT title ASC
LIMIT :pageSize OFFSET :offset

Join related collections

Joined fields live under the joined collection name. Declared right-side indexes are probed once per distinct left key; otherwise one keyed join map is built. Only safe base predicates move before the join. Search syntax does not imply a persisted BM25 index.

sql

SELECT title, categories.meta.region FROM items
JOIN categories ON category = categories.id
WHERE enabled = true AND categories.meta.region = :region
SEARCH categories.label MATCH :term
SORT categories.label ASC
LIMIT 20

Query arrays and nested fields

CONTAINS_ALL and CONTAINS_ANY require an array on both sides. Duplicate members do not imply multiplicity. An empty right array satisfies ALL for an actual array field and never satisfies ANY. Expanded index paths such as passkeys[*].credentialId have bounded traversal and key expansion.

sql

SELECT _key FROM roles
WHERE capabilities CONTAINS_ALL :routes
LIMIT 100

Nested indexes and planner behavior →

Change records conditionally

Update expressions read the pre-update row and support literals, bindings, fields, addition and COALESCE. Numeric addition preserves the exact number model and rejects nonnumeric operands. Set expectedCount on the enclosing query operation for a transactional precondition. DELETE follows the same predicate and mutation pipeline.

sql

UPDATE projects
SET title = :title, edits = COALESCE(edits, 0) + 1
WHERE _key = :key AND _revision = :revision

Inspect access behavior

Primary keys are indexed. Declared secondary equality, safe prefixes and dense scalar ranges can narrow candidates. Every candidate still passes the residual predicate. OR requires a complete candidate source for both branches before using an index union.

Sorting and operator work remain bounded. A complete cost-based optimizer, universal index-order streaming, persisted BM25/HNSW and all-query performance superiority are not completed features.