Module chained_document_query 

Chained document queries — a provable semi-join: an inner indexOnly DriveDocumentQuery whose proven refersTo values become the outer query’s primary keys (carried as a single by-id join in DriveDocumentQuery::sub_queries), proven against one state root. See the module docs. Chained document queries: a provable semi-join.

SELECT * FROM post WHERE $id IN (SELECT postId FROM like WHERE $ownerId = <me>) — the INNER query runs against an indexOnly document type and projects a refersTo: permanentDocument property (the JOIN property); its proven values are reinjected as the OUTER query’s primary keys. Both halves are proven as ONE merged grovedb proof — prove_query_many merges the limited inner query with the derived outer by-ids query (grovedb merge slot 2 lifts the inner limit into a per-instance branch limit), so a single root binds the whole composition by construction; the surrounding tenderdash layer then binds that root to the quorum-signed app hash (see rs-drive-proof-verifier).

There is no separate chained query type: a chained query is a DriveDocumentQuery — the inner half — whose sub_queries carry exactly one by-id join bound to it, the shape DriveDocumentQuery::with_by_id_join builds (the same shape the composite surface generalizes). This module holds the chained behaviour of DriveDocumentQuery: shape validation, join-value derivation, the outer by-ids builder, proof merging, and the server-side executors behind Drive::query_chained_documents / query_chained_documents_with_proof (the verifier half lives in verify::chained_document).

Soundness never rests on the server’s join: the verifier re-derives the outer query from the INNER proof’s results (DriveDocumentQuery::chained_join_values → DriveDocumentQuery::derive_chained_outer_query, the same functions the server executes), so a server cannot substitute, omit, or inject outer documents. Because the join property’s refersTo targets a permanentDocument type (non-deletable, enforced at write time), every proven join value MUST resolve to a document — a missing outer document is an invalid proof, not an absence.

Guardrails (v1): the inner query must resolve to an indexOnly index that carries the join property (as terminal or prefix property, so every synthesized projection provably carries its value); the join edge must be a same-contract refersTo: permanentDocument whose target is the outer type; the inner limit is required (it is what bounds the outer fan-out); the outer half takes no clauses, no limit and no cursor — it is purely the derived by-ids fetch, and pagination lives on the inner query alone.

Structs

ChainedDocumentsResult

The materialized result of a chained query, in inner-proof order.

Constants

MAX_CHAINED_JOIN_VALUES

The most join values one chained query can carry — the derived outer query is a single $id IN [...] clause, and in clauses admit at most 100 values (WhereClause::in_values). DriveDocumentQuery::validate_chained caps the inner limit here so every reachable page fits, and DriveDocumentQuery::chained_proof_path_queries enforces it on the (untrusted, verifier-supplied) join-value list itself.