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, the inner limit carried as a per-instance cap on its root query (the form grovedb’s merge lifts a global limit into), 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. When 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. A moderatedDocument target leaves state only through a moderator’s recorded removal, so the merged proof also covers the removal records of the join values (see moderated_join): a join value with no outer document is reported with its proven record, and one with neither is an invalid proof. A deletableDocument target promises only that the document existed when the inner one was written, so there a join value with no outer document is left out. That omission is proven, not trusted: every derived $id is a queried key of the merged query, and grovedb refuses a proof without the coverage to show a queried key present or absent, so a prover cannot pass an existing document off as deleted.

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, refersTo: moderatedDocument or refersTo: deletableDocument 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.

ChainedOuterDocuments

The outer half of a chained query, assembled against its join values by DriveDocumentQuery::assemble_chained_outer_documents.

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.