Struct Query 

pub struct Query {
    pub items: Vec<QueryItem>,
    pub default_subquery_branch: SubqueryBranch,
    pub conditional_subquery_branches: Option<IndexMap<QueryItem, SubqueryBranch>>,
    pub left_to_right: bool,
    pub add_parent_tree_on_subquery: bool,
}

Query represents one or more keys or ranges of keys, which can be used to resolve a proof which will include all the requested values.

Fields

items: Vec<QueryItem>

Items

default_subquery_branch: SubqueryBranch

Default subquery branch

conditional_subquery_branches: Option<IndexMap<QueryItem, SubqueryBranch>>

Conditional subquery branches

left_to_right: bool

Left to right?

add_parent_tree_on_subquery: bool

When true, the parent tree element (e.g. a CountTree or SumTree) is included in query results alongside its subquery children.

Known limitation

Parent tree results added by this flag do not currently count against SizedQuery::limit. A query with limit = 10 may return more than 10 results when this flag is active, because the limit only governs child-level results. This will be resolved in a future redesign that introduces per-level limits.

Absence-proof verification

When verifying with verify_query_with_absence_proof or verify_subset_query_with_absence_proof, results are reconstructed from terminal_keys() which does not emit parent-tree entries. Parent tree elements will therefore not appear in the verified result set in those modes.

Implementations

impl Query

pub fn insert_key(&mut self, key: Vec<u8>)

Adds an individual key to the query, so that its value (or its absence) in the tree will be included in the resulting proof.

If the key or a range including the key already exists in the query, this will have no effect. If the query already includes a range that has a non-inclusive bound equal to the key, the bound will be changed to be inclusive.

pub fn insert_keys(&mut self, keys: Vec<Vec<u8>>)

Adds multiple individual keys to the query, so that its value (or its absence) in the tree will be included in the resulting proof.

If the key or a range including the key already exists in the query, this will have no effect. If the query already includes a range that has a non-inclusive bound equal to the key, the bound will be changed to be inclusive.

pub fn insert_range(&mut self, range: Range<Vec<u8>>)

Adds a range to the query, so that all the entries in the tree with keys in the range will be included in the resulting proof.

If a range including the range already exists in the query, this will have no effect. If the query already includes a range that overlaps with the range, the ranges will be joined together.

pub fn insert_range_inclusive(&mut self, range: RangeInclusive<Vec<u8>>)

Adds an inclusive range to the query, so that all the entries in the tree with keys in the range will be included in the resulting proof.

If a range including the range already exists in the query, this will have no effect. If the query already includes a range that overlaps with the range, the ranges will be merged together.

pub fn insert_range_to_inclusive(&mut self, range: RangeToInclusive<Vec<u8>>)

Adds a range until a certain included value to the query, so that all the entries in the tree with keys in the range will be included in the resulting proof.

If a range including the range already exists in the query, this will have no effect. If the query already includes a range that overlaps with the range, the ranges will be joined together.

pub fn insert_range_from(&mut self, range: RangeFrom<Vec<u8>>)

Adds a range from a certain included value to the query, so that all the entries in the tree with keys in the range will be included in the resulting proof.

If a range including the range already exists in the query, this will have no effect. If the query already includes a range that overlaps with the range, the ranges will be joined together.

pub fn insert_range_to(&mut self, range: RangeTo<Vec<u8>>)

Adds a range until a certain non included value to the query, so that all the entries in the tree with keys in the range will be included in the resulting proof.

If a range including the range already exists in the query, this will have no effect. If the query already includes a range that overlaps with the range, the ranges will be joined together.

pub fn insert_range_after(&mut self, range: RangeFrom<Vec<u8>>)

Adds a range after the first value, so that all the entries in the tree with keys in the range will be included in the resulting proof.

If a range including the range already exists in the query, this will have no effect. If the query already includes a range that overlaps with the range, the ranges will be joined together.

pub fn insert_range_after_to(&mut self, range: Range<Vec<u8>>)

Adds a range after the first value, until a certain non included value to the query, so that all the entries in the tree with keys in the range will be included in the resulting proof.

If a range including the range already exists in the query, this will have no effect. If the query already includes a range that overlaps with the range, the ranges will be joined together.

pub fn insert_range_after_to_inclusive( &mut self, range: RangeInclusive<Vec<u8>>, )

Adds a range after the first value, until a certain included value to the query, so that all the entries in the tree with keys in the range will be included in the resulting proof.

If a range including the range already exists in the query, this will have no effect. If the query already includes a range that overlaps with the range, the ranges will be joined together.

pub fn insert_all(&mut self)

Adds a range of all potential values to the query, so that the query will return all values

All other items in the query will be discarded as you are now getting back all elements.

pub fn insert_item(&mut self, item: QueryItem)

Adds the QueryItem to the query, first checking to see if it collides with any existing ranges or keys. All colliding items will be removed then merged together so that the query includes the minimum number of items (with no items covering any duplicate parts of keyspace) while still including every key or range that has been added to the query.

pub fn insert_items(&mut self, items: Vec<QueryItem>)

Performs an insert_item on each item in the vector.

impl Query

pub fn merge_default_subquery_branch( &mut self, other_default_subquery_branch: SubqueryBranch, )

Merges the subquery for the query with the current subquery. Subqueries causes every element that is returned by the query to be subqueried or subqueried to the subquery_path/subquery if a subquery is present. Merging involves creating conditional subqueries in the subqueries subqueries and paths.

pub fn merge_multiple(queries: Vec<Query>) -> Query

Merges multiple queries into a single query. Items are unioned and conditional subquery branches are merged where they intersect.

pub fn merge_with(&mut self, other: Query)

Merges another query into this one, combining items and conditional subquery branches.

pub fn merge_conditional_boxed_subquery( &mut self, query_item_merging_in: QueryItem, subquery_branch_merging_in: SubqueryBranch, )

Adds a conditional subquery. A conditional subquery replaces the default subquery and subquery_path if the item matches for the key. If multiple conditional subquery items match, then the first one that matches is used (in order that they were added).

pub fn merge_conditional_subquery_branches_with_new_at_query_item( conditional_subquery_branches: Option<IndexMap<QueryItem, SubqueryBranch>>, query_item_merging_in: QueryItem, subquery_branch_merging_in: SubqueryBranch, ) -> IndexMap<QueryItem, SubqueryBranch>

Adds a conditional subquery. A conditional subquery replaces the default subquery and subquery_path if the item matches for the key. If multiple conditional subquery items match, then the first one that matches is used (in order that they were added).

impl Query

pub fn new() -> Query

Creates a new query which contains no items.

pub fn new_range_full() -> Query

Creates a new query which contains all items.

pub fn new_single_key(key: Vec<u8>) -> Query

Creates a new query which contains only one key.

pub fn new_single_query_item(query_item: QueryItem) -> Query

Creates a new query which contains only one item.

pub fn new_with_direction(left_to_right: bool) -> Query

Creates a new query with a direction specified

pub fn new_single_query_item_with_direction( query_item: QueryItem, left_to_right: bool, ) -> Query

Creates a new query which contains only one item with the specified direction.

pub fn has_subquery_on_key(&self, key: &[u8], in_path: bool) -> bool

Returns true if the given key would trigger a subquery (either via the default subquery branch or a matching conditional branch).

pub fn has_subquery_or_subquery_path_on_key( &self, key: &[u8], in_path: bool, ) -> bool

Returns true if the given key would trigger a subquery or subquery path (either via the default branch or a matching conditional branch).

pub fn terminal_keys( &self, current_path: Vec<Vec<u8>>, max_results: usize, result: &mut Vec<(Vec<Vec<u8>>, Vec<u8>)>, ) -> Result<usize, Error>

Pushes terminal key paths and keys to result, no more than max_results. Returns the number of terminal keys added.

Terminal keys are the keys of a path query below which there are no more subqueries. In other words they’re the keys of the terminal queries of a path query.

pub fn len(&self) -> usize

Get number of query items

pub fn is_empty(&self) -> bool

Returns true if there are no query items.

pub fn iter(&self) -> impl Iterator<Item = &QueryItem>

Iterate through query items

pub fn rev_iter(&self) -> impl Iterator<Item = &QueryItem>

Iterate through query items in reverse

pub fn directional_iter( &self, left_to_right: bool, ) -> Box<dyn Iterator<Item = &QueryItem> + '_>

Iterate with direction specified

pub fn set_subquery_key(&mut self, key: Vec<u8>)

Sets the subquery_path for the query with one key. This causes every element that is returned by the query to be subqueried one level to the subquery_path.

pub fn set_subquery_path(&mut self, path: Vec<Vec<u8>>)

Sets the subquery_path for the query. This causes every element that is returned by the query to be subqueried to the subquery_path.

pub fn set_subquery(&mut self, subquery: Query)

Sets the subquery for the query. This causes every element that is returned by the query to be subqueried or subqueried to the subquery_path/subquery if a subquery is present.

pub fn add_conditional_subquery( &mut self, item: QueryItem, subquery_path: Option<Vec<Vec<u8>>>, subquery: Option<Query>, )

Adds a conditional subquery. A conditional subquery replaces the default subquery and subquery_path if the item matches for the key. If multiple conditional subquery items match, then the first one that matches is used (in order that they were added).

pub fn has_subquery(&self) -> bool

Check if there is a subquery

pub fn has_only_keys(&self) -> bool

Check if there are only keys

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

Returns the depth of the subquery branch This depth is how many GroveDB layers down we could query at maximum

Trait Implementations

impl<'de, Context> BorrowDecode<'de, Context> for Query

fn borrow_decode<D>(decoder: &mut D) -> Result<Query, DecodeError>

where D: BorrowDecoder<'de, Context = Context>,

Attempt to decode this type with the given BorrowDecode.

impl Clone for Query

fn clone(&self) -> Query

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Query

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

Formats the value using the given formatter.

impl<Context> Decode<Context> for Query

fn decode<D>(decoder: &mut D) -> Result<Query, DecodeError>

where D: Decoder<Context = Context>,

Attempt to decode this type with the given Decode.

impl Default for Query

fn default() -> Query

Returns the “default value” for a type.

impl Display for Query

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

Formats the value using the given formatter.

impl Encode for Query

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

where E: Encoder,

Encode a given type.

impl From<Query> for Vec<QueryItem>

fn from(q: Query) -> Vec<QueryItem>

Converts to this type from the input type.

impl<Q> From<Vec<Q>> for Query

where Q: Into<QueryItem>,

Available on crate feature blockchain only.

fn from(other: Vec<Q>) -> Query

Converts to this type from the input type.

impl IntoIterator for Query

type IntoIter = <Vec<QueryItem> as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

type Item = QueryItem

The type of the elements being iterated over.

fn into_iter(self) -> <Query as IntoIterator>::IntoIter

Creates an iterator from a value.

impl PartialEq for Query

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

fn execute_proof( &self, bytes: &[u8], limit: Option<u16>, left_to_right: bool, proof_version: u16, ) -> CostContext<Result<([u8; 32], ProofVerificationResult), Error>>

Verifies the encoded proof with the given query

Every key in keys is checked to either have a key/value pair in the proof, or to have its absence in the tree proven.

Returns Err if the proof is invalid, or a list of proven values associated with keys. For example, if keys contains keys A and B, the returned list will contain 2 elements, the value of A and the value of B. Keys proven to be absent in the tree will have an entry of None, keys that have a proven value will have an entry of Some(value).

fn verify_proof( &self, bytes: &[u8], limit: Option<u16>, left_to_right: bool, expected_hash: [u8; 32], ) -> CostContext<Result<ProofVerificationResult, Error>>

Verifies the encoded proof with the given query and expected hash

impl StructuralPartialEq for Query