Skip to main content

QueryBuilder

Struct QueryBuilder 

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

Implementations§

Source§

impl QueryBuilder<'_>

Source

pub fn execute_arrow(&self) -> Result<RecordBatch, QueryBuilderError>

Execute the query and convert the result to an Arrow RecordBatch. The batch always includes compatibility metadata columns _doc_id and _score before the requested projections.

Source

pub fn execute_parquet<P: AsRef<Path>>( &self, path: P, ) -> Result<(), QueryBuilderError>

Execute the query and write the Arrow result to a Parquet file.

Source§

impl<'a> QueryBuilder<'a>

Source

pub fn new(engine: &'a Engine, table: impl Into<String>) -> Self

Source

pub fn select_columns<S: AsRef<str>>(self, columns: &[S]) -> Self

Replace the SELECT projection list. Pass column names verbatim; pass * for star projection.

Source

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

Add a single projection expression. The argument is inserted into the SQL verbatim, so callers can pass aliased expressions like count(*) AS n.

Source

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

Add an arbitrary boolean expression to the WHERE clause. All added filters combine with AND.

Source

pub fn where_eq(self, column: &str, value: &Value) -> Result<Self, SQLError>

Convenience: <column> = <value> filter.

§Errors

Returns an error when value cannot be represented losslessly as a SQL literal, such as a map or a non-finite float.

Source

pub fn where_gt(self, column: &str, value: &Value) -> Result<Self, SQLError>

Convenience: <column> > <value> filter.

§Errors

Returns an error when value cannot be represented losslessly as a SQL literal, such as a map or a non-finite float.

Source

pub fn where_gte(self, column: &str, value: &Value) -> Result<Self, SQLError>

Convenience: <column> >= <value> filter.

§Errors

Returns an error when value cannot be represented losslessly as a SQL literal, such as a map or a non-finite float.

Source

pub fn where_lt(self, column: &str, value: &Value) -> Result<Self, SQLError>

Convenience: <column> < <value> filter.

§Errors

Returns an error when value cannot be represented losslessly as a SQL literal, such as a map or a non-finite float.

Source

pub fn where_lte(self, column: &str, value: &Value) -> Result<Self, SQLError>

Convenience: <column> <= <value> filter.

§Errors

Returns an error when value cannot be represented losslessly as a SQL literal, such as a map or a non-finite float.

Source

pub fn text_match(self, field: &str, query: &str) -> Self

Add text_match(field, '<query>') to WHERE.

Source

pub fn knn_match( self, field: &str, vector: &[f32], k: usize, ) -> Result<Self, SQLError>

Add knn_match(field, ARRAY[v1, v2, ...], k) to WHERE.

§Errors

Returns an error when field is empty, vector is empty or contains a non-finite component, or k is zero or does not fit in SQL BIGINT.

Source

pub fn multi_field_match( self, fields_and_queries: &[(&str, &str)], ) -> Result<Self, SQLError>

Add multi_field_match(field_1, '<q1>', field_2, '<q2>', ...) to WHERE.

§Errors

Returns an error unless at least two field/query pairs are supplied, or when any field name is empty.

Source

pub fn staged_retrieval( self, stages: &[(&str, &str, usize)], ) -> Result<Self, SQLError>

Add staged_retrieval(f1, '<q1>', k1, f2, '<q2>', k2, ...) to WHERE.

§Errors

Returns an error when there are no stages, a field name is empty, or a stage cutoff is zero or does not fit in SQL BIGINT.

Source

pub fn graph_pagerank(self, graph_name: &str) -> Self

Add graph_pagerank('<graph>') to WHERE.

Source

pub fn graph_traverse( self, graph_name: &str, start_vertex: u64, label: Option<&str>, max_hops: u32, ) -> Self

Add graph_traverse('<graph>', start, label?, max_hops) to WHERE.

Source

pub fn graph_neighbors( self, graph_name: &str, vertex_id: u64, label: Option<&str>, direction: &str, ) -> Self

Add graph_neighbors('<graph>', vertex, label?, '<direction>') to WHERE.

Source

pub fn deep_predict(self, model_name: &str) -> Self

Add deep_predict('<model>') to WHERE.

Source

pub fn order_by(self, column: impl Into<String>, order: Order) -> Self

Source

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

Source

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

Source

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

Source

pub fn offset(self, n: u64) -> Self

Source

pub fn to_sql(&self) -> String

Render the SQL string the builder would execute. Useful for logging, test introspection, or EXPLAIN-style diagnostics.

Source

pub fn execute(&self) -> Result<SQLResult, SQLError>

Source

pub fn term(self, term: &str, field: Option<&str>) -> Self

Add a bare term filter (text_match(field, 'term')). When field is None, the SQL function falls back to all-field search via the engine’s analyzer registry.

Source

pub fn and(self, other: &QueryBuilder<'a>) -> Self

Combine two builders’ filter lists with AND. The resulting builder keeps the receiver’s projection / order / limit / offset state and absorbs other’s filters.

Source

pub fn or(self, other: &QueryBuilder<'a>) -> Self

Wrap the builder’s filter list in an OR group with other’s filters: ((self_filters) OR (other_filters)).

Source

pub fn not(self) -> Self

Negate the current filter list. Renders to NOT (a AND b ...).

Source

pub fn vector( self, query: &[f32], k: usize, field: &str, ) -> Result<Self, SQLError>

Add a nearest-neighbor vector retrieval predicate. This compatibility name delegates to the registered knn_match SQL function.

§Errors

Returns an error under the same conditions as Self::knn_match.

Source

pub fn aggregate(self, field: &str, agg: &str) -> Self

Promote the projection list to a single aggregate over field, e.g. SELECT count(field) FROM .... Resets any previous projections.

Source

pub fn facet(self, field: &str) -> Self

Replace projections with field, count(*) and add a GROUP BY field ordering hint. The engine’s GROUP BY pipeline picks up the projection.

Source

pub fn score_bm25(self, query: &str, field: Option<&str>) -> Self

Add score_bm25(field, 'query') to the projection list.

Source

pub fn score_bayesian_bm25(self, query: &str, field: Option<&str>) -> Self

Add score_bayesian_bm25(field, 'query') to the projection list.

Source

pub fn fuse_log_odds( self, signals: &[&str], base_rate: Option<f64>, ) -> Result<Self, SQLError>

Add exact signed-evidence log-odds fusion. This is an alias for Self::fuse_bayesian_evidence: each signal must emit a prior-free evidence probability, and the optional corpus prior enters once.

§Errors

Returns an error unless at least two non-empty signal expressions are supplied, or when base_rate is not finite and strictly between zero and one.

Source

pub fn pool_positive_evidence( self, signals: &[&str], alpha: f64, ) -> Result<Self, SQLError>

Add a gated, confidence-scaled positive-evidence retrieval pool. This operator is a ranking heuristic and does not claim exact Bayesian posterior semantics.

§Errors

Returns an error unless at least two non-empty signal expressions are supplied, or when alpha is non-finite or outside [0, 1].

Source

pub fn fuse_bayesian_evidence( self, signals: &[&str], base_rate: Option<f64>, ) -> Result<Self, SQLError>

Add exact signed-evidence Bayesian fusion. Each signal must emit a prior-free evidence probability; the optional corpus prior enters once.

§Errors

Returns an error unless at least two non-empty signals are supplied, or when base_rate is not finite and strictly between zero and one.

Source

pub fn multi_stage(self, stages: &[(&str, usize)]) -> Result<Self, SQLError>

Add a staged_retrieval(...) predicate from pre-rendered retrieval signals paired with their top_k cutoffs. The builder method retains its current name, while the generated SQL uses the registered shared-IR function.

§Errors

Returns an error when there are no stages, a signal expression is empty, or a cutoff is zero or does not fit in SQL BIGINT.

Source

pub fn fuse_attention(self, signals: &[&str]) -> Result<Self, SQLError>

Add a multi-signal attention-fusion retrieval predicate. signals must be probability-valued expressions such as bayesian_match(...) or calibrated_vector_match(...).

§Errors

Returns an error unless at least two non-empty signal expressions are supplied.

Source

pub fn fuse_learned( self, signals: &[&str], alpha: Option<f64>, ) -> Result<Self, SQLError>

Add a learned-fusion retrieval predicate over probability-valued signals. alpha controls the conjunction strength and defaults to the engine’s 0.5 when omitted.

§Errors

Returns an error unless at least two non-empty signal expressions are supplied, or when alpha is non-finite or outside [0, 1].

Source

pub fn calibrated_vector_match( self, field: &str, vector: &[f32], k: usize, threshold: Option<f32>, ) -> Result<Self, SQLError>

Add the query-pool KNN score transform to WHERE through its compatibility SQL name. Scores lie in [0, 1], but are not described as calibrated probabilities without a held-out evaluation.

§Errors

Returns an error when field is empty, vector is empty or contains a non-finite component, k is zero or does not fit in SQL BIGINT, or threshold is non-finite or outside [0, 1].

Source

pub fn rpq(self, expr: &str, start: u64, graph: &str) -> Self

Build an RPQ (Regular Path Query) over a named graph. Replaces the FROM clause with a table- function reference, since RPQ is a relation-producing function.

Source

pub fn traverse( self, graph: &str, start: u64, label: Option<&str>, max_hops: u32, ) -> Self

Build a graph traversal as a relation.

Source

pub fn temporal_traverse( self, graph: &str, start: u64, label: Option<&str>, max_hops: u32, t_min: f64, t_max: f64, ) -> Self

Build a temporally bounded graph traversal.

Source

pub fn highlight(self, field: &str, query: &str) -> Result<Self, SQLError>

Add a uqa_highlight(field, query [, start_tag, end_tag, max_fragments, fragment_size]) projection.

§Errors

Returns an error when field is empty.

Source

pub fn facets(self, fields: &[&str]) -> Result<Self, SQLError>

uqa_facets(field [, field2, ...]) projection. Fields are emitted as column references because the engine groups the values in those columns; string literals would facet the field names themselves.

§Errors

Returns an error when no fields are supplied or a field name is empty.

Source

pub fn deep_learn(self, model: &str, training_set: &str) -> Self

Add a deep_learn(model, training_set) analytical training projection.

Source

pub fn bayesian_match(self, field: &str, query: &str) -> Self

bayesian_match(field, '<query>') filter with the configured query-level BM25 score transform. Probability-calibration claims require parameters fitted and verified on held-out labels.

Source

pub fn score_bayesian_with_prior( self, query: &str, field: Option<&str>, prior_field: Option<&str>, prior_mode: Option<&str>, ) -> Result<Self, SQLError>

Bayesian BM25 with a document-level external prior. Rust’s SQL builder takes the serializable prior shape (prior_field, prior_mode) rather than a closure, so the assembled query can still flow through the SQL engine.

Source

pub fn learn_params( &self, query: &str, labels: &[u8], field: Option<&str>, ) -> Result<BTreeMap<String, f64>, SQLError>

Source

pub fn sparse_threshold(self, threshold: f64) -> Result<Self, SQLError>

Source

pub fn explain(&self) -> Result<String, SQLError>

Run EXPLAIN <assembled SELECT> and return the planner’s rendered plan as a single string.

Trait Implementations§

Source§

impl<'a> Clone for QueryBuilder<'a>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more

Auto Trait Implementations§

§

impl<'a> !RefUnwindSafe for QueryBuilder<'a>

§

impl<'a> !UnwindSafe for QueryBuilder<'a>

§

impl<'a> Freeze for QueryBuilder<'a>

§

impl<'a> Send for QueryBuilder<'a>

§

impl<'a> Sync for QueryBuilder<'a>

§

impl<'a> Unpin for QueryBuilder<'a>

§

impl<'a> UnsafeUnpin for QueryBuilder<'a>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> ErasedDestructor for T
where T: 'static,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.