Struct SearchBuilder 

pub struct SearchBuilder<'e> { /* private fields */ }

Tethered unified retrieval builder returned from NodeQueryBuilder::search.

SearchBuilder is the Phase 12 primary retrieval entry point per dev/design-adaptive-text-search-surface-addendum-1-vec.md §Public Surface. It accumulates filter predicates alongside a caller-provided raw query string, compiles into a CompiledRetrievalPlan via fathomdb_query::compile_retrieval_plan, and dispatches .execute() through fathomdb_engine::ExecutionCoordinator::execute_retrieval_plan to return SearchRows with the strict/relaxed/vector blocks fused under the addendum’s block precedence rules.

v1 scope: the unified planner’s vector branch slot is wired architecturally but never fires through search() because read-time embedding of natural-language queries is deferred. Until that future phase lands, every SearchBuilder::execute() result has vector_hit_count == 0 regardless of vector capability availability. Callers who want vector retrieval today must use the advanced vector_search() override directly with a caller-provided vector literal.

Implementations

impl<'e> SearchBuilder<'e>

pub fn with_match_attribution(self) -> Self

Request per-hit match attribution on the resulting SearchRows. Mirrors TextSearchBuilder::with_match_attribution semantics for text hits and VectorSearchBuilder::with_match_attribution for vector hits.

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.

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( self, path: impl Into<String>, value: impl Into<String>, ) -> Result<Self, BuilderValidationError>

Filter results where a JSON text property at path equals value, with fusion semantics.

Errors

Returns BuilderValidationError if the root kind has no registered property-FTS schema or the schema does not cover path.

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

Filter results where a JSON text property at path is one of values, with fusion semantics.

Errors

See Self::filter_json_fused_text_eq.

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. Non-fused; no FTS schema required.

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

Filter results where a JSON timestamp at path is strictly greater than value, with fusion semantics.

Errors

See Self::filter_json_fused_text_eq.

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

Filter results where a JSON timestamp at path is at or after value, with fusion semantics.

Errors

See Self::filter_json_fused_text_eq.

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

Filter results where a JSON timestamp at path is strictly before value, with fusion semantics.

Errors

See Self::filter_json_fused_text_eq.

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

Filter results where a JSON timestamp at path is at or before value, with fusion semantics.

Errors

See Self::filter_json_fused_text_eq.

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

Filter results where a JSON boolean property at path equals value, with fusion semantics. See Self::filter_json_fused_text_eq for the contract.

Errors

See Self::filter_json_fused_text_eq.

pub fn compile_plan(&self) -> Result<CompiledRetrievalPlan, CompileError>

Compile the builder into a CompiledRetrievalPlan without executing it. Useful for tests and introspection.

Errors

Returns CompileError if filter partitioning or text-query parsing fails.

pub fn execute(&self) -> Result<SearchRows, EngineError>

Execute the unified retrieval plan and return matching hits.

Errors

Returns EngineError if compilation or execution fails.

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 per root result. Pass edge_filter: None to preserve pre-Pack-D behavior.

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

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

Rewrites the seed TextSearch step into a real text-search step before delegating to compile_grouped_query.

Errors

Returns CompileError if grouped compilation fails.

pub fn execute_grouped(self) -> Result<GroupedQueryRows, EngineError>

Execute the grouped query and return root rows plus named expansion slots.

Errors

Returns EngineError if compilation or execution fails.