Struct Query 

pub struct Query<'a> { /* private fields */ }

Declarative agent-facing query over a ReadonlyRepo.

Usage:

let hits = Query::new(repo)
    .label("Person")
    .where_prop("name", PropPredicate::Eq(Ipld::String("Alice".into())))
    .with_outgoing("knows")
    .limit(10)
    .execute()?;

Implementations

impl<'a> Query<'a>

pub const DEFAULT_ADJACENCY_CAP: usize = 10_000

Default per-hit cap on how many edges (in each direction) are surfaced from the adjacency index. Protects agent-facing callers from fan-in/out denial-of-service (a “celebrity” node with 1M incoming edges would otherwise allocate a 1M-entry Vec per hit). Override via Self::adjacency_cap.

The default is intentionally generous (10_000) so normal knowledge graphs are never clipped; the cap is a safety valve, not a performance knob. Callers that legitimately need the full fan-in should raise it explicitly and consume the result stream.

pub const fn new(repo: &'a ReadonlyRepo) -> Self

Start a new query against repo.

pub fn label(self, label: impl Into<String>) -> Self

Restrict matches to nodes of a specific label (ntype).

pub fn where_prop(self, name: impl Into<String>, pred: PropPredicate) -> Self

Add a property predicate. If a label is also set, the indexed (label, prop_name) -> value Prolly lookup is used (O(log n)); otherwise the query falls back to a full label scan.

pub fn where_eq(self, name: impl Into<String>, value: impl Into<Ipld>) -> Self

Convenience: where_prop(name, PropPredicate::Eq(value.into())). The most common agent query shape, one call shorter.

pub fn with_outgoing(self, edge_label: impl Into<String>) -> Self

Include outgoing edges of these labels in every hit.

pub fn with_incoming(self, edge_label: impl Into<String>) -> Self

Include incoming edges of these labels in every hit. Symmetric mirror of Self::with_outgoing: answers “who points at me through this edge-type?” using the incoming Prolly tree in O(log n) plus one bucket read per hit.

Populates QueryHit::incoming_edges. When combined with with_outgoing in the same query, a hit is kept if it matches the base predicates regardless of direction, and each direction’s edges are surfaced in its own field.

pub fn with_any_direction(self, edge_label: impl Into<String>) -> Self

Convenience: ask for this edge-type in BOTH directions. Saves the caller from writing with_outgoing(x).with_incoming(x) every time.

Self-loops (edges where src == dst) appear in edges only, not duplicated into incoming_edges. The execute path detects the self-loop case and deduplicates on EdgeId.

pub const fn adjacency_cap(self, cap: usize) -> Self

Override the per-hit adjacency cap. See Self::DEFAULT_ADJACENCY_CAP for the rationale.

pub const fn limit(self, n: usize) -> Self

Cap the result set.

pub fn first(self) -> Result<Option<QueryHit>, Error>

Convenience: execute and return the first hit, or Ok(None) if the result set is empty. Sets limit(1) internally.

Errors

Same as Self::execute.

pub fn one(self) -> Result<QueryHit, Error>

Convenience: execute and return the exactly-one hit, erroring if the result set is empty or has more than one match. Useful when the agent treats a resolve as a precondition.

Internally sets limit(2) so a genuine second hit is detected cheaply.

Errors

• RepoError::NotFound on zero matches.
• RepoError::AmbiguousMatch on >1 match.
• Propagates any error from Self::execute.

pub fn execute(self) -> Result<Vec<QueryHit>, Error>

Execute the query against the repo’s current commit.

Dispatches to the fastest matching path:

• label + prop_eq with an IndexSet present: one Prolly point lookup
• label-only with an IndexSet: label sub-tree cursor, bounded by limit
• otherwise: streaming scan of commit.nodes with in-memory filter, also bounded by limit

Errors

• RepoError::Uninitialized if the repo has no head commit.
• Store / codec errors from index lookups.

Trait Implementations

impl<'a> Clone for Query<'a>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Query<'a>

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

Formats the value using the given formatter.