pub struct QueryBuilder<'a> { /* private fields */ }Implementations§
Source§impl QueryBuilder<'_>
impl QueryBuilder<'_>
Sourcepub fn execute_arrow(&self) -> Result<RecordBatch, QueryBuilderError>
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.
Sourcepub fn execute_parquet<P: AsRef<Path>>(
&self,
path: P,
) -> Result<(), QueryBuilderError>
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>
impl<'a> QueryBuilder<'a>
pub fn new(engine: &'a Engine, table: impl Into<String>) -> Self
Sourcepub fn select_columns<S: AsRef<str>>(self, columns: &[S]) -> Self
pub fn select_columns<S: AsRef<str>>(self, columns: &[S]) -> Self
Replace the SELECT projection list. Pass column names verbatim;
pass * for star projection.
Sourcepub fn select(self, expr: impl Into<String>) -> Self
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.
Sourcepub fn where(self, predicate: impl Into<String>) -> Self
pub fn where(self, predicate: impl Into<String>) -> Self
Add an arbitrary boolean expression to the WHERE clause. All
added filters combine with AND.
Sourcepub fn where_eq(self, column: &str, value: &Value) -> Result<Self, SQLError>
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.
Sourcepub fn where_gt(self, column: &str, value: &Value) -> Result<Self, SQLError>
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.
Sourcepub fn where_gte(self, column: &str, value: &Value) -> Result<Self, SQLError>
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.
Sourcepub fn where_lt(self, column: &str, value: &Value) -> Result<Self, SQLError>
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.
Sourcepub fn where_lte(self, column: &str, value: &Value) -> Result<Self, SQLError>
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.
Sourcepub fn text_match(self, field: &str, query: &str) -> Self
pub fn text_match(self, field: &str, query: &str) -> Self
Add text_match(field, '<query>') to WHERE.
Sourcepub fn knn_match(
self,
field: &str,
vector: &[f32],
k: usize,
) -> Result<Self, SQLError>
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.
Sourcepub fn multi_field_match(
self,
fields_and_queries: &[(&str, &str)],
) -> Result<Self, SQLError>
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.
Sourcepub fn staged_retrieval(
self,
stages: &[(&str, &str, usize)],
) -> Result<Self, SQLError>
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.
Sourcepub fn graph_pagerank(self, graph_name: &str) -> Self
pub fn graph_pagerank(self, graph_name: &str) -> Self
Add graph_pagerank('<graph>') to WHERE.
Sourcepub fn graph_traverse(
self,
graph_name: &str,
start_vertex: u64,
label: Option<&str>,
max_hops: u32,
) -> Self
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.
Sourcepub fn graph_neighbors(
self,
graph_name: &str,
vertex_id: u64,
label: Option<&str>,
direction: &str,
) -> Self
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.
Sourcepub fn deep_predict(self, model_name: &str) -> Self
pub fn deep_predict(self, model_name: &str) -> Self
Add deep_predict('<model>') to WHERE.
pub fn order_by(self, column: impl Into<String>, order: Order) -> Self
pub fn order_by_asc(self, column: impl Into<String>) -> Self
pub fn order_by_desc(self, column: impl Into<String>) -> Self
pub fn limit(self, n: u64) -> Self
pub fn offset(self, n: u64) -> Self
Sourcepub fn to_sql(&self) -> String
pub fn to_sql(&self) -> String
Render the SQL string the builder would execute. Useful for
logging, test introspection, or EXPLAIN-style diagnostics.
pub fn execute(&self) -> Result<SQLResult, SQLError>
Sourcepub fn term(self, term: &str, field: Option<&str>) -> Self
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.
Sourcepub fn and(self, other: &QueryBuilder<'a>) -> Self
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.
Sourcepub fn or(self, other: &QueryBuilder<'a>) -> Self
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)).
Sourcepub fn vector(
self,
query: &[f32],
k: usize,
field: &str,
) -> Result<Self, SQLError>
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.
Sourcepub fn aggregate(self, field: &str, agg: &str) -> Self
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.
Sourcepub fn facet(self, field: &str) -> Self
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.
Sourcepub fn score_bm25(self, query: &str, field: Option<&str>) -> Self
pub fn score_bm25(self, query: &str, field: Option<&str>) -> Self
Add score_bm25(field, 'query') to the projection list.
Sourcepub fn score_bayesian_bm25(self, query: &str, field: Option<&str>) -> Self
pub fn score_bayesian_bm25(self, query: &str, field: Option<&str>) -> Self
Add score_bayesian_bm25(field, 'query') to the projection
list.
Sourcepub fn fuse_log_odds(
self,
signals: &[&str],
base_rate: Option<f64>,
) -> Result<Self, SQLError>
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.
Sourcepub fn pool_positive_evidence(
self,
signals: &[&str],
alpha: f64,
) -> Result<Self, SQLError>
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].
Sourcepub fn fuse_bayesian_evidence(
self,
signals: &[&str],
base_rate: Option<f64>,
) -> Result<Self, SQLError>
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.
Sourcepub fn multi_stage(self, stages: &[(&str, usize)]) -> Result<Self, SQLError>
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.
Sourcepub fn fuse_attention(self, signals: &[&str]) -> Result<Self, SQLError>
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.
Sourcepub fn fuse_learned(
self,
signals: &[&str],
alpha: Option<f64>,
) -> Result<Self, SQLError>
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].
Sourcepub fn calibrated_vector_match(
self,
field: &str,
vector: &[f32],
k: usize,
threshold: Option<f32>,
) -> Result<Self, SQLError>
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].
Sourcepub fn rpq(self, expr: &str, start: u64, graph: &str) -> Self
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.
Sourcepub fn traverse(
self,
graph: &str,
start: u64,
label: Option<&str>,
max_hops: u32,
) -> Self
pub fn traverse( self, graph: &str, start: u64, label: Option<&str>, max_hops: u32, ) -> Self
Build a graph traversal as a relation.
Sourcepub fn temporal_traverse(
self,
graph: &str,
start: u64,
label: Option<&str>,
max_hops: u32,
t_min: f64,
t_max: f64,
) -> Self
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.
Sourcepub fn highlight(self, field: &str, query: &str) -> Result<Self, SQLError>
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.
Sourcepub fn facets(self, fields: &[&str]) -> Result<Self, SQLError>
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.
Sourcepub fn deep_learn(self, model: &str, training_set: &str) -> Self
pub fn deep_learn(self, model: &str, training_set: &str) -> Self
Add a deep_learn(model, training_set) analytical training projection.
Sourcepub fn bayesian_match(self, field: &str, query: &str) -> Self
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.
Sourcepub fn score_bayesian_with_prior(
self,
query: &str,
field: Option<&str>,
prior_field: Option<&str>,
prior_mode: Option<&str>,
) -> Result<Self, SQLError>
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.
pub fn learn_params( &self, query: &str, labels: &[u8], field: Option<&str>, ) -> Result<BTreeMap<String, f64>, SQLError>
pub fn sparse_threshold(self, threshold: f64) -> Result<Self, SQLError>
Trait Implementations§
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> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> ErasedDestructor for Twhere
T: 'static,
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
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 moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
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