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 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_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 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

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 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 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.

impl StructuralPartialEq for PathQuery