Struct QueryBuilder 

pub struct QueryBuilder { /* private fields */ }

Fluent builder for constructing a QueryAst.

Start with QueryBuilder::nodes and chain filtering, traversal, and expansion steps before calling compile or compile_grouped.

Implementations

impl QueryBuilder

pub fn nodes(kind: impl Into<String>) -> Self

Create a builder that queries nodes of the given kind.

pub fn vector_search(self, query: impl Into<String>, limit: usize) -> Self

Add a vector similarity search step.

pub fn text_search(self, query: impl Into<String>, limit: usize) -> Self

Add a full-text search step.

The input is parsed into FathomDB’s safe supported subset: literal terms, quoted phrases, uppercase OR, uppercase NOT, and implicit AND by adjacency. Unsupported syntax remains literal rather than being passed through as raw FTS5 control syntax.

pub fn traverse( self, direction: TraverseDirection, label: impl Into<String>, max_depth: usize, ) -> Self

Add a graph traversal step following edges of the given label.

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

Filter results to a single logical ID.

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

Filter results to nodes matching the given kind.

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

Filter results to nodes matching the given source_ref.

pub fn filter_content_ref_not_null(self) -> Self

Filter results to nodes where content_ref is not NULL.

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

Filter results to nodes matching the given content_ref URI.

pub fn filter_json_text_eq( self, path: impl Into<String>, value: impl Into<String>, ) -> Self

Filter results where a JSON property at path equals the given text value.

pub fn filter_json_bool_eq(self, path: impl Into<String>, value: bool) -> Self

Filter results where a JSON property at path equals the given boolean value.

pub fn filter_json_integer_gt(self, path: impl Into<String>, value: i64) -> Self

Filter results where a JSON integer at path is greater than value.

pub fn filter_json_integer_gte( self, path: impl Into<String>, value: i64, ) -> Self

Filter results where a JSON integer at path is greater than or equal to value.

pub fn filter_json_integer_lt(self, path: impl Into<String>, value: i64) -> Self

Filter results where a JSON integer at path is less than value.

pub fn filter_json_integer_lte( self, path: impl Into<String>, value: i64, ) -> Self

Filter results where a JSON integer at path is less than or equal to value.

pub fn filter_json_timestamp_gt( self, path: impl Into<String>, value: i64, ) -> Self

Filter results where a JSON timestamp at path is after value (epoch seconds).

pub fn filter_json_timestamp_gte( self, path: impl Into<String>, value: i64, ) -> Self

Filter results where a JSON timestamp at path is at or after value.

pub fn filter_json_timestamp_lt( self, path: impl Into<String>, value: i64, ) -> Self

Filter results where a JSON timestamp at path is before value.

pub fn filter_json_timestamp_lte( self, path: impl Into<String>, value: i64, ) -> Self

Filter results where a JSON timestamp at path is at or before value.

pub fn filter_json_fused_text_eq_unchecked( self, path: impl Into<String>, value: impl Into<String>, ) -> Self

Append a fused JSON text-equality predicate without validating whether the caller has a property-FTS schema for the kind.

Callers must have already validated the fusion gate; the tethered crate::QueryBuilder has no engine handle to consult a schema. Mis-use — calling this without prior schema validation — produces SQL that pushes a json_extract predicate into the search CTE’s inner WHERE clause. That is valid SQL but defeats the “developer opt-in” contract.

pub fn filter_json_fused_timestamp_gt_unchecked( self, path: impl Into<String>, value: i64, ) -> Self

Append a fused JSON timestamp-greater-than predicate without validating the fusion gate. See Self::filter_json_fused_text_eq_unchecked for the contract.

pub fn filter_json_fused_timestamp_gte_unchecked( self, path: impl Into<String>, value: i64, ) -> Self

Append a fused JSON timestamp-greater-or-equal predicate without validating the fusion gate. See Self::filter_json_fused_text_eq_unchecked for the contract.

pub fn filter_json_fused_timestamp_lt_unchecked( self, path: impl Into<String>, value: i64, ) -> Self

Append a fused JSON timestamp-less-than predicate without validating the fusion gate. See Self::filter_json_fused_text_eq_unchecked for the contract.

pub fn filter_json_fused_timestamp_lte_unchecked( self, path: impl Into<String>, value: i64, ) -> Self

Append a fused JSON timestamp-less-or-equal predicate without validating the fusion gate. See Self::filter_json_fused_text_eq_unchecked for the contract.

pub fn filter_json_fused_bool_eq_unchecked( self, path: impl Into<String>, value: bool, ) -> Self

Append a fused JSON boolean-equality predicate without validating the fusion gate. See Self::filter_json_fused_text_eq_unchecked for the contract.

pub fn filter_json_fused_text_in_unchecked( self, path: impl Into<String>, values: Vec<String>, ) -> Self

Append a fused JSON text IN-set predicate without validating the fusion gate. See Self::filter_json_fused_text_eq_unchecked for the contract.

Panics

Panics if values is empty — SQLite IN with an empty list is a syntax error.

pub fn filter_json_text_in( self, path: impl Into<String>, values: Vec<String>, ) -> Self

Filter results where a JSON text property at path is one of values.

This is the non-fused variant; the predicate is applied as a residual WHERE clause. No FTS schema is required.

Panics

Panics if values is empty — SQLite IN with an empty list is a syntax error.

pub fn expand( self, slot: impl Into<String>, direction: TraverseDirection, label: impl Into<String>, max_depth: usize, filter: Option<Predicate>, edge_filter: Option<Predicate>, ) -> Self

Add an expansion slot that traverses edges of the given label for each root result.

Pass filter: None to preserve the existing behavior. filter: Some(_) is accepted by the AST but the compilation is not yet implemented (Pack 3). Pass edge_filter: None to preserve pre-Pack-D behavior (no edge filtering). edge_filter: Some(EdgePropertyEq { .. }) filters traversed edges by their JSON properties; only edges matching the predicate are followed.

pub fn traverse_edges( self, slot: impl Into<String>, direction: TraverseDirection, label: impl Into<String>, max_depth: usize, ) -> EdgeExpansionBuilder

Begin registering an edge-projecting expansion slot. Chain EdgeExpansionBuilder::edge_filter / EdgeExpansionBuilder::endpoint_filter to attach predicates, then call EdgeExpansionBuilder::done to return this builder.

Emits (EdgeRow, NodeRow) tuples per root on execution. The endpoint node is the target on Out traversal, source on In. Slot name must be unique across both node- and edge-expansions within the same query; collisions are reported by Self::compile_grouped.

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

Set the maximum number of result rows.

pub fn ast(&self) -> &QueryAst

Borrow the underlying QueryAst.

pub fn into_ast(self) -> QueryAst

Consume the builder and return the underlying QueryAst.

pub fn compile(&self) -> Result<CompiledQuery, CompileError>

Compile this builder’s AST into an executable CompiledQuery.

Errors

Returns CompileError if the query violates structural constraints (e.g. too many traversal steps or too many bind parameters).

pub fn compile_grouped(&self) -> Result<CompiledGroupedQuery, CompileError>

Compile this builder’s AST into an executable grouped query.

Errors

Returns CompileError if the query violates grouped-query structural constraints such as duplicate slot names or excessive depth.

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 PartialEq for QueryBuilder

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

impl StructuralPartialEq for QueryBuilder