Struct PathQuery 

pub struct PathQuery {
    pub path: Vec<Vec<u8>>,
    pub query: SizedQuery,
}

Path query

Represents a path to a specific GroveDB tree and a corresponding query to apply to the given tree.

Fields

path: Vec<Vec<u8>>

Path

query: SizedQuery

Query

Implementations

impl PathQuery

pub fn classify(&self) -> Result<PathQueryShape<'_>, Error>

Classifies this query into the single [PathQueryShape] it describes, running the same validators the prove/verify entry points run today, in the same order.

A malformed query — an aggregate item in a non-canonical position, a non-zero offset over anything but a single plain range, pagination on an aggregate — returns the exact error the corresponding validator returns, so callers that migrate from direct validator calls to classify keep their error surface.

The aggregate families are checked before pagination because a well-formed aggregate query can never carry a non-zero offset (both the leaf and carrier size-constraint rules reject it), and validate_count_offset_paginated in turn rejects aggregate wrappers — the shapes are mutually exclusive, and this order reproduces which of the two rejection messages a mixed query gets from the prover today.

impl PathQuery

pub const fn new(path: Vec<Vec<u8>>, query: SizedQuery) -> PathQuery

New path query

pub fn new_single_key(path: Vec<Vec<u8>>, key: Vec<u8>) -> PathQuery

New path query with a single key

pub fn new_single_query_item( path: Vec<Vec<u8>>, query_item: QueryItem, ) -> PathQuery

New path query with a single query item

pub const fn new_unsized(path: Vec<Vec<u8>>, query: Query) -> PathQuery

New unsized path query

pub fn new_bulk_position_range( path: Vec<Vec<u8>>, key: Vec<u8>, start: u64, limit: u16, ) -> PathQuery

Canonical PathQuery for a paginated position-range read of an append-only, BulkAppendTree-backed element (BulkAppendTree or CommitmentTree) at path/key.

Selects the element at key and subqueries positions [start, start + limit), encoded as 8-byte big-endian keys (start + limit saturates at u64::MAX). Prover and verifier both derive this query from (start, limit), so a scanning client only needs its cursor and page size — see GroveDb::prove_bulk_position_range and GroveDb::verify_bulk_position_range_proof.

pub fn new_aggregate_count_on_range( path: Vec<Vec<u8>>, range: QueryItem, ) -> PathQuery

Construct a PathQuery for an aggregate-count-on-range query against the subtree at path. range is the inner QueryItem describing the keys to count over; see Query::new_aggregate_count_on_range for the allowed range variants.

pub fn new_aggregate_sum_on_range( path: Vec<Vec<u8>>, range: QueryItem, ) -> PathQuery

Mirror of Self::new_aggregate_count_on_range for AggregateSumOnRange. Builds a PathQuery whose underlying query asks for the cryptographically-verifiable sum of children with keys in range against the ProvableSumTree rooted at path.

pub fn new_aggregate_count_and_sum_on_range( path: Vec<Vec<u8>>, range: QueryItem, ) -> PathQuery

Mirror of Self::new_aggregate_count_on_range / Self::new_aggregate_sum_on_range for the combined AggregateCountAndSumOnRange variant. Builds a PathQuery whose underlying query asks for BOTH the count AND the signed sum of children with keys in range against the ProvableCountProvableSumTree (PCPS) rooted at path — both values come from a single proof.

pub fn new_axis(path: Vec<Vec<u8>>, axis_query: AxisQuery) -> PathQuery

An axis-ordered read of the indexed tree at path, from an already-built [AxisQuery] — use it to set a non-default projection (AxisQuery::keys_only); the typed constructors below cover the default cases.

pub fn new_axis_top_k( path: Vec<Vec<u8>>, axis: IndexAxis, k: u16, offset: u64, descending: bool, ) -> PathQuery

An axis-ordered read of the indexed tree at path: a page of k entries on axis, starting at rank offset (0 = first page).

descending chooses which end the ranking starts from: true gives the k largest by aggregate (top-k), false the k smallest (bottom-k).

pub fn new_axis_bounded( path: Vec<Vec<u8>>, axis: IndexAxis, lo: i128, hi: i128, limit: u16, descending: bool, ) -> PathQuery

An axis-ordered read of the indexed tree at path: every entry whose axis aggregate is in the inclusive [lo, hi], up to limit entries.

pub fn new_axis_rank_of_key( path: Vec<Vec<u8>>, axis: IndexAxis, key: Vec<u8>, descending: bool, ) -> PathQuery

The rank of key in the directional walk over axis of the indexed tree at path.

pub fn new_axis_aggregate_over_value_range( path: Vec<Vec<u8>>, axis: IndexAxis, lo: i128, hi: i128, fold: AggregateFold, ) -> PathQuery

[lo, hi] selects the entries of the indexed tree at path by their own axis value; fold says which scalar over exactly those entries is the answer. Count and Sum axes only.

The fold is explicit because both readings are meaningful on both axes and the “obvious” one flips per axis. Over counts [3, 1, 5], the band [2, 10] selects the 3 and the 5: AggregateFold::Population answers 2, AggregateFold::Total answers 8. See AxisTraversal::AggregateOverValueRange for the full matrix; every (Count/Sum, fold) cell is served.

pub fn new_branched_axis( prefix: Vec<Vec<u8>>, branch_keys: Vec<Vec<u8>>, suffix: Vec<Vec<u8>>, axis_query: AxisQuery, ) -> PathQuery

The same axis read fanned over N sibling branches: for each key in branch_keys (selected under prefix), descend the shared suffix to an indexed tree and perform axis_query on it.

This is the query form of the branched indexed-axis proof: prefix / branch_key_i / suffix -> axis read.

pub fn new_sum_budget( path: Vec<Vec<u8>>, items: Vec<QueryItem>, left_to_right: bool, sum_limit: u64, match_limit: Option<u16>, ) -> PathQuery

A key-ordered read of items under path that stops once the running sum of matched sum-item values reaches sum_limit — the unified form of AggregateSumPathQuery.

pub fn has_read_mode(&self) -> bool

Whether this query — at any nesting level — carries a [ReadMode]. Entry points that don’t serve read modes use this to fail closed instead of silently running a read-mode query as plain key selection.

pub fn validate_aggregate_count_on_range(&self) -> Result<&QueryItem, Error>

Validates that this PathQuery is a well-formed AggregateCountOnRange query in either the leaf or carrier shape. On success, returns a reference to the leaf inner range item.

Empty-path handling is shape-aware. The GroveDB root merk is always a NormalTree by API construction (never a ProvableCountTree), so a leaf aggregate-count query at the root has no valid target and is rejected up front. A carrier query, by contrast, may legitimately fan out across the root’s top-level keys and descend (via subquery_path or directly) to leaf count merks at lower depths; empty-path carriers are permitted and the per-key verifier handles depth-0 execution.

Forwards to SizedQuery::validate_aggregate_count_on_range.

pub fn validate_aggregate_sum_on_range(&self) -> Result<&QueryItem, Error>

Validates that this PathQuery is a well-formed AggregateSumOnRange query in either the leaf or carrier shape. On success, returns a reference to the leaf inner range item.

Empty-path handling is shape-aware. The GroveDB root merk is always a NormalTree, never a ProvableSumTree, so a leaf aggregate-sum query at the root has no valid target and is rejected up front. A carrier query may legitimately fan out across the root’s top-level keys and descend (via subquery_path or directly) to leaf sum merks at lower depths; empty-path carriers are permitted and the per-key verifier handles depth-0 execution. Forwards to SizedQuery::validate_aggregate_sum_on_range.

pub fn validate_aggregate_count_and_sum_on_range( &self, ) -> Result<&QueryItem, Error>

Validates that this PathQuery is a well-formed AggregateCountAndSumOnRange query in either the leaf or carrier shape. On success, returns a reference to the leaf inner range item.

Empty-path handling is shape-aware. The GroveDB root merk is always a NormalTree, never a ProvableCountProvableSumTree, so a leaf combined aggregate at the root has no valid target and is rejected up front. A carrier query may legitimately fan out across the root’s top-level keys and descend (via subquery_path or directly) to a PCPS leaf merk at a lower depth; empty-path carriers are permitted and the per-key verifier handles depth-0 execution. Forwards to SizedQuery::validate_aggregate_count_and_sum_on_range.

pub fn validate_leaf_aggregate_count_on_range( &self, ) -> Result<&QueryItem, Error>

Strict variant of Self::validate_aggregate_count_on_range that only accepts the leaf shape (single AggregateCountOnRange(_) item, no subqueries). Always rejects empty paths — the GroveDB root is always a NormalTree, never a count tree.

pub fn validate_leaf_aggregate_sum_on_range(&self) -> Result<&QueryItem, Error>

Strict variant of Self::validate_aggregate_sum_on_range that only accepts the leaf shape (single AggregateSumOnRange(_) item, no subqueries). Used by [crate::GroveDb::verify_aggregate_sum_query] which produces a single i64 and needs to reject the carrier shape up front. Always rejects empty paths.

pub fn validate_leaf_aggregate_count_and_sum_on_range( &self, ) -> Result<&QueryItem, Error>

Strict variant of Self::validate_aggregate_count_and_sum_on_range that only accepts the leaf shape (single AggregateCountAndSumOnRange(_) item, no subqueries). Used by [crate::GroveDb::verify_aggregate_count_and_sum_query] which produces a single (u64, i64) and needs to reject the carrier shape up front. Always rejects empty paths.

pub fn validate_count_offset_paginated(&self) -> Result<&QueryItem, Error>

Validates that this PathQuery is an offset-paginated range query against a ProvableCountTree / ProvableCountSumTree / ProvableCountProvableSumTree. Returns the single range QueryItem on success.

The tree-type check happens later when the leaf merk is opened. This function is purely syntactic — it gates the query shape (single range, no subqueries, offset > 0). Forwards to SizedQuery::validate_count_offset_paginated.

Rejects empty paths up-front for the same reason as Self::validate_aggregate_count_on_range: the GroveDB root merk is always a NormalTree, never a count tree, so a root-level offset-paginated query has no valid target.

pub fn has_non_zero_offset(&self) -> bool

Returns true if this PathQuery has a non-zero offset set. Used to detect “the caller wants pagination” before deciding whether the query is eligible for the count-offset paginated proof flow.

pub fn has_aggregate_count_on_range(&self) -> bool

Returns true if this PathQuery’s underlying query carries an AggregateCountOnRange item (whether well-formed or not). Use Self::validate_aggregate_count_on_range when you also need well-formedness.

pub fn has_aggregate_sum_on_range(&self) -> bool

Mirror of Self::has_aggregate_count_on_range for the sum variant.

pub fn has_aggregate_count_and_sum_on_range(&self) -> bool

Mirror of Self::has_aggregate_count_on_range for the combined AggregateCountAndSumOnRange variant.

pub fn max_depth(&self) -> Option<u16>

The max depth of the query, this is the maximum layers we could get back from grovedb If the max depth can not be calculated we get None This would occur if the recursion level was too high

pub fn terminal_keys( &self, max_results: usize, grove_version: &GroveVersion, ) -> Result<Vec<(Vec<Vec<u8>>, Vec<u8>)>, Error>

Gets the path of all terminal keys

Version dispatch — see the terminal_keys module in grovedb-query: v0 is the legacy walk frozen for GROVE_V1..GROVE_V3; v1 (GROVE_V4+) resolves conditional subquery branches per queried item (issue #689).

pub fn merge( path_queries: Vec<&PathQuery>, grove_version: &GroveVersion, ) -> Result<PathQuery, Error>

Combines multiple path queries into one equivalent path query

pub fn should_add_parent_tree_at_path( &self, path: &[&[u8]], grove_version: &GroveVersion, ) -> Result<bool, Error>

Returns whether the parent tree element should be included in results at the given path.

pub fn axis_read_at_path(&self, path: &[&[u8]]) -> Option<&AxisQuery>

Returns the axis read governing the subtree at path, if the query node resolved at exactly that path carries [ReadMode::Axis]. path is a full path from the GroveDB root (the same convention as Self::query_items_at_path).

This is how the proof walk — prover and verifier alike — learns that a layer is an axis-ordered read of an indexed tree rather than a key-selecting descent into its primary. Both sides resolve from the same query through this one function, so they cannot disagree about which layers are axis reads.

Positions inside a subquery branch’s subquery_path resolve to None (a read mode lives on a query node, never mid-path), as do paths that diverge from the query entirely.

pub fn sum_budget_read_at_path(&self, path: &[&[u8]]) -> Option<&SumBudgetRead>

The sum-budget read governing the subtree at path, if any — the sum-budget sibling of Self::axis_read_at_path. The budget’s items live on the same node; callers re-resolve them from the query root (a sum-budget read only classifies at the root node).

pub fn query_items_at_path( &self, path: &[&[u8]], grove_version: &GroveVersion, ) -> Result<Option<SinglePathSubquery<'_>>, Error>

Returns the query items applicable at the given path, if any.

Trait Implementations

impl<'__de, __Context> BorrowDecode<'__de, __Context> for PathQuery

fn borrow_decode<__D>(decoder: &mut __D) -> Result<PathQuery, DecodeError>

where __D: BorrowDecoder<'__de, Context = __Context>,

Attempt to decode this type with the given BorrowDecode.

impl Clone for PathQuery

fn clone(&self) -> PathQuery

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PathQuery

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

Formats the value using the given formatter.

impl<__Context> Decode<__Context> for PathQuery

fn decode<__D>(decoder: &mut __D) -> Result<PathQuery, DecodeError>

where __D: Decoder<Context = __Context>,

Attempt to decode this type with the given Decode.

impl Display for PathQuery

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

Formats the value using the given formatter.

impl Encode for PathQuery

fn encode<__E>(&self, encoder: &mut __E) -> Result<(), EncodeError>

where __E: Encoder,

Encode a given type.

impl PartialEq for PathQuery

fn eq(&self, other: &PathQuery) -> 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 StructuralPartialEq for PathQuery

impl TryFromPlatformVersioned<SingleDocumentDriveQuery> for PathQuery

type Error = Error

The type returned in the event of a conversion error.

fn try_from_platform_versioned( value: SingleDocumentDriveQuery, platform_version: &PlatformVersion, ) -> Result<Self, Self::Error>

Performs the conversion.