Struct QueryBuilder 

pub struct QueryBuilder { /* private fields */ }

Fluent builder that compiles a chain of operator method calls into a QueryPlan.

Composition rules

1. The first step appended must be context-free. Self::scan, Self::scan_with, Self::scan_all, Self::union, Self::intersect, and Self::difference all satisfy that contract; calling Self::filter or Self::traverse on an empty builder produces a BuildError::FirstStepNotContextFree at Self::build time.
2. Self::union, Self::intersect, and Self::difference take an arbitrary QueryPlan as the right-hand operand. The builder’s current accumulated state is folded into the left-hand operand. If the builder is empty, the right-hand operand becomes the first step.
3. Self::traverse normalises its EdgeKind argument so that the plan hash is independent of metadata the executor ignores (see normalize_edge_kind).
4. Self::build always wraps the accumulated steps in a PlanNode::Chain, even when only a single step is present. This keeps the plan shape uniform for the fuser and the executor; callers that want the bare step can match against the resulting Chain.steps.

Cloning

QueryBuilder is Clone so that an in-progress chain can be branched — useful when constructing two related queries from a shared prefix:

use sqry_core::graph::unified::node::kind::NodeKind;
use sqry_db::planner::{Predicate, QueryBuilder};

let prefix = QueryBuilder::new().scan(NodeKind::Function);
let with_callers = prefix.clone().filter(Predicate::HasCaller).build();
let with_callees = prefix.filter(Predicate::HasCallee).build();
assert!(with_callers.is_ok() && with_callees.is_ok());

Implementations

impl QueryBuilder

pub const fn new() -> Self

Constructs an empty builder.

At least one of Self::scan, Self::scan_with, Self::scan_all, Self::union, Self::intersect, or Self::difference must be called before Self::build for the resulting plan to validate.

pub fn scan(self, kind: NodeKind) -> Self

Appends a PlanNode::NodeScan filtered to the given NodeKind.

Equivalent to .scan_with(ScanFilters::new().with_kind(kind)).

pub fn scan_with(self, filters: ScanFilters) -> Self

Appends a PlanNode::NodeScan with the given filter combination.

pub fn scan_all(self) -> Self

Appends an unfiltered PlanNode::NodeScan that matches every node in the graph.

Use sparingly — this is an expensive operation on large snapshots.

pub fn filter(self, predicate: Predicate) -> Self

Appends a PlanNode::Filter step with the given predicate.

Every variant of Predicate is acceptable here, including the boolean combinators (Predicate::And, Predicate::Or, Predicate::Not) and value-bearing relation predicates with PredicateValue::Subquery payloads.

pub fn filter_name(self, pattern: StringPattern) -> Self

Convenience wrapper that builds a Predicate::MatchesName filter from a StringPattern and appends it as a PlanNode::Filter.

pub fn filter_in_file(self, path: impl Into<PathPattern>) -> Self

Convenience wrapper that builds a Predicate::InFile filter from a PathPattern (or anything convertible to one) and appends it.

pub fn traverse( self, direction: Direction, edge_kind: EdgeKind, max_depth: u32, ) -> Self

Appends a PlanNode::EdgeTraversal step.

The supplied EdgeKind is run through normalize_edge_kind so that two builders that pick the same edge kind but supply different per-edge metadata produce the same plan hash. See normalize_edge_kind for the rationale.

Note that max_depth == 0 is accepted here but rejected at Self::build time with BuildError::ZeroDepth. The builder defers validation so that callers can compose traversals freely without fallible intermediate steps.

pub fn traverse_any(self, direction: Direction, max_depth: u32) -> Self

Appends a PlanNode::EdgeTraversal step that matches any edge kind.

Useful for “follow any outgoing edge to depth N” queries (impact analysis, broad reachability).

pub fn union(self, other: QueryPlan) -> Self

Combines the builder’s current state with another plan via union.

If the builder already holds steps, they are wrapped in a PlanNode::Chain and used as the left-hand operand. If the builder is empty, the right-hand operand becomes the sole context-free step.

pub fn intersect(self, other: QueryPlan) -> Self

Combines the builder’s current state with another plan via intersection.

See Self::union for the composition semantics when the builder is non-empty vs empty.

pub fn difference(self, other: QueryPlan) -> Self

Combines the builder’s current state with another plan via difference.

result = self \ other. See Self::union for composition semantics.

pub fn step_count(&self) -> usize

Returns the number of steps currently accumulated in the builder.

Does not include nested operators inside PlanNode::SetOp or PlanNode::Chain payloads — only top-level steps that Self::build would emit.

pub fn is_empty(&self) -> bool

Returns true if the builder has no steps yet.

pub fn build(self) -> Result<QueryPlan, BuildError>

Materialises the accumulated steps into a QueryPlan.

Validation

1. The builder must contain at least one step (BuildError::EmptyBuilder).
2. The first step must be context-free (BuildError::FirstStepNotContextFree).
3. No PlanNode::EdgeTraversal step may have max_depth = 0 (BuildError::ZeroDepth). This is checked recursively through PlanNode::SetOp and PlanNode::Chain payloads, so a malformed sub-plan supplied to Self::union is also caught.
4. Any PlanNode::SetOp node added by Self::union / Self::intersect / Self::difference must have both operands rooted at a context-free node (BuildError::InvalidSetOpOperand).

Output shape

The returned QueryPlan’s root is always a PlanNode::Chain. Single-step builders therefore produce a Chain { steps: vec![one] } rather than the bare one. This keeps the plan shape uniform for downstream fusion and execution. Callers that prefer the bare step can match against plan.root and unwrap when Chain.steps.len() == 1.

Trait Implementations

impl Clone for QueryBuilder

fn clone(&self) -> QueryBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for QueryBuilder

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

Formats the value using the given formatter.

impl Default for QueryBuilder

fn default() -> QueryBuilder

Returns the “default value” for a type.