Struct DriveDocumentQuery 

pub struct DriveDocumentQuery<'a> {
    pub contract: &'a DataContract,
    pub document_type: DocumentTypeRef<'a>,
    pub internal_clauses: InternalClauses,
    pub offset: Option<u16>,
    pub limit: Option<u16>,
    pub order_by: IndexMap<String, OrderClause>,
    pub start_at: Option<[u8; 32]>,
    pub start_at_included: bool,
    pub block_time_ms: Option<u64>,
    pub resolved_time_ranges: Vec<ResolvedTimeRange>,
    pub sub_queries: Vec<DriveSubQuery<'a>>,
}

Drive query struct

Fields

contract: &'a DataContract

DataContract

document_type: DocumentTypeRef<'a>

Document type

internal_clauses: InternalClauses

Internal clauses

offset: Option<u16>

Offset

limit: Option<u16>

Limit

order_by: IndexMap<String, OrderClause>

Order by

start_at: Option<[u8; 32]>

Start at document id

start_at_included: bool

Start at included

block_time_ms: Option<u64>

Block time

resolved_time_ranges: Vec<ResolvedTimeRange>

The fields whose equality clause in internal_clauses was produced by IN_TIME_RANGE resolution — i.e. by resolve_time_range_bucket_clause, on the server from committed block time and in the verifier from the quorum-signed response metadata time.

Never parsed from the wire: every from_cbor / from_value / from_typed_clauses entry point leaves this empty, so a client cannot claim resolution it did not go through. It is what Self::find_best_index uses to pin index selection to the index that buckets the field (see index_admissible_for_resolved_time_range), which is required because the resolved clause is an ordinary equality and cannot be told apart from a raw-timestamp lookup once built.

Empty for every raw query.

sub_queries: Vec<DriveSubQuery<'a>>

The composite sub-queries: queries whose IN clauses are derived from this query’s proven results (by-id joins, indexed lookups, counts — see the composite_document_query module docs), listed in binding order (a sub-query may only bind an earlier one) and answered together with this query as ONE merged grovedb proof.

Empty for an ordinary documents query, which is what every plain entry point requires: a query carrying sub-queries is served by Drive::query_composite_documents / query_composite_documents_with_proof and verified by verify_composite_documents_proof, and the plain query/proof/verify surfaces refuse it rather than silently prove the page alone.

Never parsed from the wire: every from_cbor / from_value / from_typed_clauses entry point leaves this empty; composite requests are built programmatically (see Self::with_sub_queries).

Implementations

impl<'a> DriveDocumentQuery<'a>

pub fn validate_chained( &self, platform_version: &PlatformVersion, ) -> Result<(), Error>

Validates the chained shape: this query as the inner indexOnly half plus the single by-id join its sub_queries carry (see Self::chained_join). Called by the server before executing and by the verifier before verifying, so an invalid spec fails identically on both sides.

pub fn chained_join_values( &self, inner_documents: &[Document], ) -> Result<Vec<Identifier>, Error>

Extracts the join values from the inner documents in their proof order, deduplicated to first appearance. ONE extraction both the server and the verifier run — the single-builder rule that keeps the derived outer query identical on both sides.

pub fn derive_chained_outer_query( &self, join_values: &[Identifier], ) -> Result<DriveDocumentQuery<'a>, Error>

The derived outer query: a pure by-ids fetch of the join values from the outer type’s primary storage. No clauses, no limit, no cursor — completeness is set-equality against join_values, checked by the verifier.

pub fn assemble_chained_outer_documents( &self, join_values: &[Identifier], outer_documents: Vec<Document>, ) -> Result<Vec<Document>, Error>

Reorders the outer documents (returned in key order by the by-ids query) into first-appearance join order, and enforces EXACT set equality between the proven outer ids and the derived join values — both directions. Shared by the server (where a mismatch is corrupted state: permanentDocument references cannot dangle) and the verifier (where it is an invalid proof).

pub fn chained_proof_path_queries( &self, join_values: &[Identifier], platform_version: &PlatformVersion, ) -> Result<Vec<PathQuery>, Error>

The component path queries the chained proof covers: the inner query’s own path query, plus — for a non-empty join — the outer by-ids path query derived from join_values. ONE builder both the prover (prove_query_many merges these) and the verifier (PathQuery::merge on the same inputs at the same grove version) call, so the merged query is byte-identical on both sides. Grovedb’s merge lifts the inner query’s global SizedQuery::limit into its branch’s per-instance Query::limit, which is exact here: the branch instance executes once.

impl<'a> DriveDocumentQuery<'a>

pub fn validate_composite( &self, platform_version: &PlatformVersion, ) -> Result<(), Error>

Validates the composite shape: this query as the page plus its sub_queries. Called by the server before executing and by the verifier before verifying, so an invalid request fails identically on both sides.

Construction contract: every sub-query’s document_type MUST be a document type of its own contract. This validates everything derivable from the shapes themselves.

pub fn page_path_query( &self, platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

The page as a component of the proof, its limit carried as its root query’s per-instance cap (see Self::budget_as_instance_cap). A by-ids page is built WITHOUT its limit: its ids already bound it, and grovedb refuses a budget on a query that lands at the merged root (which a by-ids page shares with a join on the same type).

pub fn derive_values( &self, binding: &SubQueryBinding, source_documents: &[Document], ) -> Result<Vec<Identifier>, Error>

Extracts a binding’s values from its source documents in their order, deduplicated to first appearance. ONE extraction both the server and the verifier run — the single-builder rule that keeps every derived sub-query identical on both sides.

pub fn sub_query_document_query( &self, sub_query: &DriveSubQuery<'a>, values: &[Identifier], platform_version: &PlatformVersion, ) -> Result<DriveDocumentQuery<'a>, Error>

The concrete documents query of a sub-query for values: the fixed clauses plus the derived IN, or a pure by-ids fetch for a join. A sibling ignores values.

pub fn sub_query_count_query<'b>( &'b self, sub_query: &'b DriveSubQuery<'a>, values: &[Identifier], _platform_version: &PlatformVersion, ) -> Result<DriveDocumentCountQuery<'b>, Error>

The concrete count query of a bound count sub-query for values. Borrows the covering index through sub_query, so the count query lives as long as that reference.

pub fn sub_query_path_query( &self, sub_query: &DriveSubQuery<'a>, values: &[Identifier], platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

The path query of one sub-query for values.

pub fn proof_path_queries( &self, derived: &[Vec<Identifier>], platform_version: &PlatformVersion, ) -> Result<(PathQuery, Vec<Option<PathQuery>>), Error>

The component path queries the merged proof covers, in component order: the page, then one entry per sub-query — None for a bound sub-query whose binding derived nothing (it has no branch). Every sub-query walks in the page’s direction: documents must already agree, while counts and by-id joins may be aligned without changing their selected sets. ONE builder both the prover and the verifier feed into Self::merged_path_query, so the merged query is byte-identical on both sides.

pub fn merged_path_query( page: &PathQuery, sub_path_queries: &[Option<PathQuery>], platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Merges the component path queries into the one query the proof covers. Components carry their budgets as per-instance caps (see Self::budget_as_instance_cap), which the merge carries along on their branches, so a page alone is proven in the very form it would have inside a merge.

pub fn derive_all<'d>( &self, page_documents: &[Document], sub_documents: impl Fn(usize) -> Option<&'d [Document]>, ) -> Result<Vec<Vec<Identifier>>, Error>

Derives every sub-query’s values, in request order — see Self::derive_for.

impl<'a> DriveDocumentQuery<'a>

pub fn new_primary_key_single_item_query( contract: &'a DataContract, document_type: DocumentTypeRef<'a>, id: Identifier, ) -> Self

Gets a document by their primary key

pub fn any_item_query( contract: &'a DataContract, document_type: DocumentTypeRef<'a>, ) -> Self

Returns any item

pub fn all_items_query( contract: &'a DataContract, document_type: DocumentTypeRef<'a>, limit: Option<u16>, ) -> Self

Returns all items

pub fn with_sub_queries(self, sub_queries: Vec<DriveSubQuery<'a>>) -> Self

Extends this query into a composite one: self becomes the page and sub_queries are derived from its proven results — see Self::sub_queries and the composite_document_query module docs.

pub fn with_by_id_join( self, source_property: impl Into<String>, document_type: DocumentTypeRef<'a>, ) -> Self

Appends a by-id join sub-query: source_property’s values, read off this query’s proven documents, become the $ids of document_type documents fetched from the same contract. The property must carry a refersTo: permanentDocument declaration targeting document_type, so every derived id resolves.

This is the one shape the chained surface (Drive::query_chained_documents, verify_chained_documents_proof) requires exactly one of, and one of the composite sub-query shapes. A cross-contract by-id join (composite only) is built by pushing a DriveSubQuery with the target contract instead.

pub fn is_for_primary_key(&self) -> bool

Returns true if the query clause if for primary keys.

pub fn from_cbor( query_cbor: &[u8], contract: &'a DataContract, document_type: DocumentTypeRef<'a>, config: &DriveConfig, platform_version: &PlatformVersion, ) -> Result<Self, Error>

Converts a query CBOR to a DriveQuery.

pub fn from_value( query_value: Value, contract: &'a DataContract, document_type: DocumentTypeRef<'a>, config: &DriveConfig, platform_version: &PlatformVersion, ) -> Result<Self, Error>

Converts a query Value to a DriveQuery.

pub fn from_btree_map_value( query_document: BTreeMap<String, Value>, contract: &'a DataContract, document_type: DocumentTypeRef<'a>, config: &DriveConfig, platform_version: &PlatformVersion, ) -> Result<Self, Error>

Converts a query Value to a DriveQuery.

pub fn from_decomposed_values( where_clause: Value, order_by: Option<Value>, maybe_limit: Option<u16>, start_at: Option<[u8; 32]>, start_at_included: bool, block_time_ms: Option<u64>, contract: &'a DataContract, document_type: DocumentTypeRef<'a>, config: &DriveConfig, platform_version: &PlatformVersion, ) -> Result<Self, Error>

Converts a query Value to a DriveQuery.

pub fn from_typed_clauses( where_clauses: Vec<WhereClause>, order_by_clauses: Vec<OrderClause>, maybe_limit: Option<u16>, start_at: Option<[u8; 32]>, start_at_included: bool, block_time_ms: Option<u64>, contract: &'a DataContract, document_type: DocumentTypeRef<'a>, config: &DriveConfig, platform_version: &PlatformVersion, ) -> Result<Self, Error>

Build a DriveDocumentQuery from already-structured where / order_by clauses. This is the typed-input twin of Self::from_decomposed_values — same downstream shape, just without the Value::Array(...) parse step.

Used by the v1 getDocuments ABCI handler whose wire format carries repeated WhereClause / repeated OrderClause natively (no CBOR envelope). The v0 path keeps using from_decomposed_values so its CBOR-decoded inputs flow through the existing WhereClause::from_components parser for shape validation; the typed path expects that validation (or the equivalent proto→drive conversion) to have run upstream.

Limit semantics mirror from_decomposed_values: maybe_limit = None or Some(0) falls back to config.default_query_limit; Some(N) with N > config.default_query_limit is rejected as QuerySyntaxError::InvalidLimit.

pub fn from_sql_expr( sql_string: &str, contract: &'a DataContract, config: Option<&DriveConfig>, platform_version: &PlatformVersion, ) -> Result<Self, Error>

Converts a SQL expression to a DriveQuery.

pub fn to_cbor(&self) -> Result<Vec<u8>, Error>

Serialize drive query to CBOR format.

FIXME: The data contract is only referred as ID, and document type as its name. This can change in the future to include full data contract and document type.

pub fn start_at_document_path_and_key( &self, starts_at: &[u8; 32], ) -> (Vec<Vec<u8>>, Vec<u8>)

Operations to construct a path query.

pub fn validate_in_clause_shape( &self, platform_version: &PlatformVersion, ) -> Result<(), Error>

Versioned preflight over the non-primary-key In clause shape.

Runs before any cursor storage lookup or proof processing so the rejection precedence matches each protocol version’s contract: v0 rejects more than one In clause with MultipleInClauses before a startAt/startAfter document is ever fetched (matching the pre-protocol-version-14 parse-time rejection), and v1 rejects the unsupported multi-In + cursor combination with Unsupported before spending state or proof work on the cursor. The lowering keeps equivalent guards for callers that reach it directly.

pub fn construct_path_query_operations( &self, drive: &Drive, include_start_at_for_proof: bool, transaction: TransactionArg<'_, '_>, drive_operations: &mut Vec<LowLevelDriveOperation>, platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Operations to construct a path query.

pub fn construct_path_query( &self, starts_at_document: Option<Document>, platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Operations to construct a path query.

pub fn pads_cursor_page(&self, platform_version: &PlatformVersion) -> bool

Whether a startAfter cursor on this query is lowered as startAt with one extra result slot, the cursor document then being dropped from the page by Self::strip_cursor_from_page.

GroveDB charges a result slot for every visited subtree whose subquery yields nothing, and the prover accounts the same way. A lowering that visits the cursor’s branch or index key looking for rows after the cursor therefore pays that slot whenever nothing follows, which is nearly every page on unique-valued data: pages came back one row short, and a limit of one came back empty while later rows remained. Keeping the cursor document in the walk keeps every subtree on its path non-empty, and documents sharing its index key continue by document id. The primary-key path has no subtrees to charge and is left alone, as is the released (protocol version 13) lowering.

pub fn get_primary_key_path_query( &self, document_type_path: Vec<Vec<u8>>, starts_at_document: Option<(Document, bool)>, platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Returns a path query given a document type path and starting document.

pub fn find_best_index( &self, platform_version: &PlatformVersion, ) -> Result<&Index, Error>

Finds the best index for the query.

Queries with more than one In clause use their own selection (Self::find_best_index_for_multiple_in_clauses); they only reach it through the v1 (protocol version 14+) path-query lowering, since the v0 lowering rejects them first.

Selection is restricted to the indexes admissible for this query’s Self::resolved_time_ranges: a query carrying an IN_TIME_RANGE-resolved equality may only be served by the index that buckets that field, and a raw query may never be served by a bucketed index. See index_admissible_for_resolved_time_range for why either mismatch would produce a validly-proven wrong answer. The rule applies on both routes, including the multiple-In selection.

pub fn query_item_for_starts_at_key( starts_at_key: Vec<u8>, left_to_right: bool, ) -> QueryItem

Returns a QueryItem given a start key and query direction.

pub fn get_non_primary_key_path_query( &self, document_type_path: Vec<Vec<u8>>, starts_at_document: Option<(Document, bool)>, platform_version: &PlatformVersion, ) -> Result<PathQuery, Error>

Returns a path query for non-primary keys given a document type path and starting document.

Versioned because the set of accepted query shapes is part of the consensus query contract: v0 rejects more than one In clause per query, v1 (protocol version 14) lowers multiple In clauses on consecutive index properties to a multi-level key-set path query.

pub fn execute_with_proof( self, drive: &Drive, block_info: Option<BlockInfo>, transaction: TransactionArg<'_, '_>, platform_version: &PlatformVersion, ) -> Result<(Vec<u8>, u64), Error>

Executes a query with proof and returns the items and fee.

pub fn execute_with_proof_only_get_elements( self, drive: &Drive, block_info: Option<BlockInfo>, transaction: TransactionArg<'_, '_>, platform_version: &PlatformVersion, ) -> Result<(RootHash, Vec<Vec<u8>>, u64), Error>

Executes a query with proof and returns the root hash, items, and fee.

pub fn execute_raw_results_no_proof( &self, drive: &Drive, block_info: Option<BlockInfo>, transaction: TransactionArg<'_, '_>, platform_version: &PlatformVersion, ) -> Result<(Vec<Vec<u8>>, u16, u64), Error>

Executes a query with no proof and returns the items, skipped items, and fee.

impl DriveDocumentQuery<'_>

pub fn verify_chained_documents_proof( &self, proof: &[u8], platform_version: &PlatformVersion, ) -> Result<(RootHash, ChainedDocumentsResult), Error>

Verifies a chained query’s single merged proof — this query as the inner half plus the single by-id join its sub_queries carry — and returns (root_hash, result).

The verifier trusts nothing about the join, and needs nothing beyond the proof itself: a BOOTSTRAP subset pass runs the inner query alone against the merged proof and extracts candidate join values from its proven positions; the outer by-ids component is derived from those (exactly as the prover derived it from its materialization), the merged query is rebuilt, and the AUTHORITATIVE full pass verifies the whole composition — grovedb enforces the inner page’s lifted per-instance limit and range completeness — with the proven outer documents required to match the proven inner join values exactly. A missing referenced document is an invalid proof (refersTo: permanentDocument targets cannot dangle), and so is an extra one; a proof covering only the inner half (an old node serving the plain query) fails the full pass whenever the inner page is non-empty.

One proof means one root by construction; the caller combines the returned root hash with the surrounding tenderdash signature — see rs-drive-proof-verifier for the canonical composition.

impl DriveDocumentQuery<'_>

pub fn verify_composite_documents_proof( &self, proof: &[u8], platform_version: &PlatformVersion, ) -> Result<(RootHash, CompositeDocumentsResult), Error>

Verifies a composite query’s single merged proof — this query as the page plus its sub_queries — and returns (root_hash, result).

The verifier trusts nothing about the derivation, and needs nothing beyond the proof itself: a BOOTSTRAP subset pass runs the page query (and every sub-query that feeds a later binding) alone against the merged proof to extract candidate values; every sub-query is derived from those exactly as the prover derived it from its materialization, the merged query is rebuilt, and the AUTHORITATIVE full pass verifies the whole composition — grovedb enforces every component’s per-instance limit and range completeness. The proven results are then routed back to their components: an entry no derivation asked for is an invalid proof, so is a by-id join missing a referenced document (a permanentDocument reference cannot dangle), and so is any divergence between the values the proven page derives and the candidates the query was built from. A proof covering only the page (an old node serving the plain query) fails the full pass whenever a sub-query derived anything.

One proof means one root by construction; the caller combines the returned root hash with the surrounding tenderdash signature — see rs-drive-proof-verifier for the canonical composition.

impl DriveDocumentQuery<'_>

pub fn verify_proof( &self, proof: &[u8], platform_version: &PlatformVersion, ) -> Result<(RootHash, Vec<Document>), Error>

Verifies a proof for a collection of documents.

This function takes a byte slice representing the serialized proof, verifies it, and returns a tuple consisting of the root hash and a vector of deserialized documents.

Arguments

• proof - A byte slice representing the proof to be verified.
• platform_version - The platform version against which to verify the proof.

Returns

A Result containing:

• A tuple with the root hash and a vector of deserialized Documents if the proof is valid.
• An Error variant, in case the proof verification fails or a deserialization error occurs.

Errors

This function will return an Error variant if:

1. The proof verification fails.
2. A deserialization error occurs when parsing the serialized document(s).

impl DriveDocumentQuery<'_>

pub fn verify_proof_keep_serialized( &self, proof: &[u8], platform_version: &PlatformVersion, ) -> Result<(RootHash, Vec<Vec<u8>>), Error>

Verifies the given proof and returns the root hash of the GroveDB tree and a vector of serialized documents if the verification is successful.

Arguments

• proof - A byte slice representing the proof to be verified.
• platform_version - The platform version against which to verify the proof.

Returns

• On success, returns a tuple containing the root hash of the GroveDB tree and a vector of serialized documents.
• On failure, returns an Error.

Errors

This function will return an Error if:

1. The start at document is not present in proof and it is expected to be.
2. The path query fails to verify against the given proof.
3. Converting the element into bytes fails.

impl DriveDocumentQuery<'_>

pub fn verify_start_at_document_in_proof( &self, proof: &[u8], is_proof_subset: bool, document_id: [u8; 32], platform_version: &PlatformVersion, ) -> Result<(RootHash, Option<Document>), Error>

Verifies if a document exists at the beginning of a proof, and returns the root hash and the optionally found document.

Arguments

• proof - A byte slice containing the proof data.
• is_proof_subset - A boolean indicating whether the proof is a subset query or not.
• document_id - A byte_32 array, representing the ID of the document to start at.
• platform_version - The platform version against which to verify the proof.

Returns

A Result with a tuple containing:

• The root hash of the verified proof.
• An Option<Document> containing the found document if available.

Errors

This function returns an Error in the following cases:

• If the proof is corrupted (wrong path, wrong key, etc.).
• If the provided proof has an incorrect number of elements.

Trait Implementations

impl<'a> Clone for DriveDocumentQuery<'a>

fn clone(&self) -> DriveDocumentQuery<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for DriveDocumentQuery<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> From<&DriveDocumentQuery<'a>> for BTreeMap<String, Value>

Convert DriveQuery to a BTreeMap of values

fn from(query: &DriveDocumentQuery<'a>) -> Self

Converts to this type from the input type.

impl<'a> PartialEq for DriveDocumentQuery<'a>

fn eq(&self, other: &DriveDocumentQuery<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> StructuralPartialEq for DriveDocumentQuery<'a>