Skip to main content

uqa_api/
query_builder.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! `QueryBuilder` assembles a `SELECT` statement and runs it via
8//! [`uqa_engine::Engine::sql`]. Infallible methods return the builder by
9//! value, while helpers that validate SQL literals or retrieval options
10//! return `Result<Self, SQLError>` and compose with `?`. The builder is
11//! transport-only; all real work happens in the engine's SQL pipeline.
12
13use uqa_core::Value;
14use uqa_engine::{Engine, SQLResult};
15use uqa_sql::SQLError;
16
17use std::fmt::{self, Write as _};
18use std::fs::File;
19use std::path::Path;
20use std::sync::Arc;
21
22use arrow_array::{ArrayRef, BooleanArray, Float64Array, Int64Array, RecordBatch, StringArray};
23use arrow_schema::{ArrowError, DataType, Field, Schema};
24use parquet::arrow::ArrowWriter;
25use parquet::errors::ParquetError;
26
27mod literals;
28mod output;
29mod validation;
30
31use literals::{quote_str, render_value};
32pub use output::QueryBuilderError;
33#[cfg(test)]
34use output::{infer_arrow_type, sql_result_to_record_batch};
35use validation::{
36    render_vector, validate_field_name, validate_fusion_alpha, validate_probability_threshold,
37    validate_retrieval_signals, validate_stage_count, validate_stage_cutoffs,
38    validate_vector_query,
39};
40
41#[derive(Debug, Clone, Copy, PartialEq, Eq)]
42pub enum Order {
43    Asc,
44    Desc,
45}
46
47#[derive(Clone)]
48pub struct QueryBuilder<'a> {
49    engine: &'a Engine,
50    table: String,
51    projections: Vec<String>,
52    filters: Vec<String>,
53    group_by: Vec<String>,
54    order_by: Vec<(String, Order)>,
55    limit: Option<u64>,
56    offset: Option<u64>,
57}
58
59fn render_exact_fusion(
60    function_name: &str,
61    signals: &[&str],
62    base_rate: Option<f64>,
63) -> Result<String, SQLError> {
64    validate_retrieval_signals(function_name, signals, 2)?;
65    if let Some(base_rate) = base_rate {
66        if !base_rate.is_finite() || base_rate <= 0.0 || base_rate >= 1.0 {
67            return Err(SQLError::TypeMismatch(format!(
68                "{function_name} base_rate must be finite and in (0, 1), got {base_rate}"
69            )));
70        }
71    }
72    let mut arguments = signals.join(", ");
73    if let Some(base_rate) = base_rate {
74        write!(arguments, ", base_rate => {base_rate}").expect("writing to String cannot fail");
75    }
76    Ok(format!("{function_name}({arguments})"))
77}
78
79impl<'a> QueryBuilder<'a> {
80    pub fn new(engine: &'a Engine, table: impl Into<String>) -> Self {
81        Self {
82            engine,
83            table: table.into(),
84            projections: Vec::new(),
85            filters: Vec::new(),
86            group_by: Vec::new(),
87            order_by: Vec::new(),
88            limit: None,
89            offset: None,
90        }
91    }
92
93    /// Replace the SELECT projection list. Pass column names verbatim;
94    /// pass `*` for star projection.
95    pub fn select_columns<S: AsRef<str>>(mut self, columns: &[S]) -> Self {
96        self.projections = columns.iter().map(|s| s.as_ref().to_string()).collect();
97        self
98    }
99
100    /// Add a single projection expression. The argument is inserted
101    /// into the SQL verbatim, so callers can pass aliased expressions
102    /// like `count(*) AS n`.
103    pub fn select(mut self, expr: impl Into<String>) -> Self {
104        self.projections.push(expr.into());
105        self
106    }
107
108    /// Add an arbitrary boolean expression to the `WHERE` clause. All
109    /// added filters combine with `AND`.
110    pub fn r#where(mut self, predicate: impl Into<String>) -> Self {
111        self.filters.push(predicate.into());
112        self
113    }
114
115    /// Convenience: `<column> = <value>` filter.
116    ///
117    /// # Errors
118    ///
119    /// Returns an error when `value` cannot be represented losslessly as a
120    /// SQL literal, such as a map or a non-finite float.
121    pub fn where_eq(self, column: &str, value: &Value) -> Result<Self, SQLError> {
122        Ok(self.r#where(format!("{column} = {}", render_value(value)?)))
123    }
124
125    /// Convenience: `<column> > <value>` filter.
126    ///
127    /// # Errors
128    ///
129    /// Returns an error when `value` cannot be represented losslessly as a
130    /// SQL literal, such as a map or a non-finite float.
131    pub fn where_gt(self, column: &str, value: &Value) -> Result<Self, SQLError> {
132        Ok(self.r#where(format!("{column} > {}", render_value(value)?)))
133    }
134
135    /// Convenience: `<column> >= <value>` filter.
136    ///
137    /// # Errors
138    ///
139    /// Returns an error when `value` cannot be represented losslessly as a
140    /// SQL literal, such as a map or a non-finite float.
141    pub fn where_gte(self, column: &str, value: &Value) -> Result<Self, SQLError> {
142        Ok(self.r#where(format!("{column} >= {}", render_value(value)?)))
143    }
144
145    /// Convenience: `<column> < <value>` filter.
146    ///
147    /// # Errors
148    ///
149    /// Returns an error when `value` cannot be represented losslessly as a
150    /// SQL literal, such as a map or a non-finite float.
151    pub fn where_lt(self, column: &str, value: &Value) -> Result<Self, SQLError> {
152        Ok(self.r#where(format!("{column} < {}", render_value(value)?)))
153    }
154
155    /// Convenience: `<column> <= <value>` filter.
156    ///
157    /// # Errors
158    ///
159    /// Returns an error when `value` cannot be represented losslessly as a
160    /// SQL literal, such as a map or a non-finite float.
161    pub fn where_lte(self, column: &str, value: &Value) -> Result<Self, SQLError> {
162        Ok(self.r#where(format!("{column} <= {}", render_value(value)?)))
163    }
164
165    /// Add `text_match(field, '<query>')` to WHERE.
166    pub fn text_match(self, field: &str, query: &str) -> Self {
167        self.r#where(format!("text_match({field}, {})", quote_str(query)))
168    }
169
170    /// Add `knn_match(field, ARRAY[v1, v2, ...], k)` to `WHERE`.
171    ///
172    /// # Errors
173    ///
174    /// Returns an error when `field` is empty, `vector` is empty or contains
175    /// a non-finite component, or `k` is zero or does not fit in SQL `BIGINT`.
176    pub fn knn_match(self, field: &str, vector: &[f32], k: usize) -> Result<Self, SQLError> {
177        validate_vector_query("knn_match", field, vector, k)?;
178        let arr = vector
179            .iter()
180            .map(f32::to_string)
181            .collect::<Vec<_>>()
182            .join(", ");
183        Ok(self.r#where(format!("knn_match({field}, ARRAY[{arr}], {k})")))
184    }
185
186    /// Add `multi_field_match(field_1, '<q1>', field_2, '<q2>', ...)` to
187    /// `WHERE`.
188    ///
189    /// # Errors
190    ///
191    /// Returns an error unless at least two field/query pairs are supplied,
192    /// or when any field name is empty.
193    pub fn multi_field_match(self, fields_and_queries: &[(&str, &str)]) -> Result<Self, SQLError> {
194        if fields_and_queries.len() < 2 {
195            return Err(SQLError::BadArity {
196                name: "multi_field_match".into(),
197                expected: ">=2 field/query pairs".into(),
198                actual: fields_and_queries.len(),
199            });
200        }
201        if fields_and_queries
202            .iter()
203            .any(|(field, _)| field.trim().is_empty())
204        {
205            return Err(SQLError::TypeMismatch(
206                "multi_field_match field names cannot be empty".into(),
207            ));
208        }
209        let mut parts = Vec::with_capacity(fields_and_queries.len() * 2);
210        for (field, query) in fields_and_queries {
211            parts.push((*field).to_string());
212            parts.push(quote_str(query));
213        }
214        Ok(self.r#where(format!("multi_field_match({})", parts.join(", "))))
215    }
216
217    /// Add `staged_retrieval(f1, '<q1>', k1, f2, '<q2>', k2, ...)` to
218    /// `WHERE`.
219    ///
220    /// # Errors
221    ///
222    /// Returns an error when there are no stages, a field name is empty, or
223    /// a stage cutoff is zero or does not fit in SQL `BIGINT`.
224    pub fn staged_retrieval(self, stages: &[(&str, &str, usize)]) -> Result<Self, SQLError> {
225        validate_stage_count(stages.len())?;
226        validate_stage_cutoffs(stages.iter().map(|(_, _, top_k)| *top_k))?;
227        if stages.iter().any(|(field, _, _)| field.trim().is_empty()) {
228            return Err(SQLError::TypeMismatch(
229                "staged_retrieval field names cannot be empty".into(),
230            ));
231        }
232        let mut parts = Vec::with_capacity(stages.len() * 3);
233        for (field, query, top_k) in stages {
234            parts.push((*field).to_string());
235            parts.push(quote_str(query));
236            parts.push(top_k.to_string());
237        }
238        Ok(self.r#where(format!("staged_retrieval({})", parts.join(", "))))
239    }
240
241    /// Add `graph_pagerank('<graph>')` to WHERE.
242    pub fn graph_pagerank(self, graph_name: &str) -> Self {
243        self.r#where(format!("graph_pagerank({})", quote_str(graph_name)))
244    }
245
246    /// Add `graph_traverse('<graph>', start, label?, max_hops)` to WHERE.
247    pub fn graph_traverse(
248        self,
249        graph_name: &str,
250        start_vertex: u64,
251        label: Option<&str>,
252        max_hops: u32,
253    ) -> Self {
254        let label_arg = match label {
255            Some(l) => quote_str(l),
256            None => "NULL".to_string(),
257        };
258        self.r#where(format!(
259            "graph_traverse({}, {start_vertex}, {label_arg}, {max_hops})",
260            quote_str(graph_name)
261        ))
262    }
263
264    /// Add `graph_neighbors('<graph>', vertex, label?, '<direction>')` to WHERE.
265    pub fn graph_neighbors(
266        self,
267        graph_name: &str,
268        vertex_id: u64,
269        label: Option<&str>,
270        direction: &str,
271    ) -> Self {
272        let label_arg = match label {
273            Some(l) => quote_str(l),
274            None => "NULL".to_string(),
275        };
276        self.r#where(format!(
277            "graph_neighbors({}, {vertex_id}, {label_arg}, {})",
278            quote_str(graph_name),
279            quote_str(direction)
280        ))
281    }
282
283    /// Add `deep_predict('<model>')` to WHERE.
284    pub fn deep_predict(self, model_name: &str) -> Self {
285        self.r#where(format!("deep_predict({})", quote_str(model_name)))
286    }
287
288    pub fn order_by(mut self, column: impl Into<String>, order: Order) -> Self {
289        self.order_by.push((column.into(), order));
290        self
291    }
292
293    pub fn order_by_asc(self, column: impl Into<String>) -> Self {
294        self.order_by(column, Order::Asc)
295    }
296
297    pub fn order_by_desc(self, column: impl Into<String>) -> Self {
298        self.order_by(column, Order::Desc)
299    }
300
301    pub fn limit(mut self, n: u64) -> Self {
302        self.limit = Some(n);
303        self
304    }
305
306    pub fn offset(mut self, n: u64) -> Self {
307        self.offset = Some(n);
308        self
309    }
310
311    /// Render the SQL string the builder would execute. Useful for
312    /// logging, test introspection, or `EXPLAIN`-style diagnostics.
313    #[allow(clippy::items_after_statements)]
314    pub fn to_sql(&self) -> String {
315        let projection = if self.projections.is_empty() {
316            "*".to_string()
317        } else {
318            self.projections.join(", ")
319        };
320        let mut sql = format!("SELECT {projection} FROM {}", self.table);
321        if !self.filters.is_empty() {
322            sql.push_str(" WHERE ");
323            sql.push_str(&self.filters.join(" AND "));
324        }
325        if !self.group_by.is_empty() {
326            sql.push_str(" GROUP BY ");
327            sql.push_str(&self.group_by.join(", "));
328        }
329        if !self.order_by.is_empty() {
330            sql.push_str(" ORDER BY ");
331            let pieces: Vec<String> = self
332                .order_by
333                .iter()
334                .map(|(col, ord)| match ord {
335                    Order::Asc => format!("{col} ASC"),
336                    Order::Desc => format!("{col} DESC"),
337                })
338                .collect();
339            sql.push_str(&pieces.join(", "));
340        }
341        if let Some(limit) = self.limit {
342            let _ = write!(sql, " LIMIT {limit}");
343        }
344        if let Some(offset) = self.offset {
345            let _ = write!(sql, " OFFSET {offset}");
346        }
347        sql
348    }
349
350    pub fn execute(&self) -> Result<SQLResult, SQLError> {
351        self.engine.sql(&self.to_sql(), &[])
352    }
353
354    // -----------------------------------------------------------------
355    // Fluent full-text and retrieval helpers.
356    // -----------------------------------------------------------------
357
358    /// Add a bare term filter (`text_match(field, 'term')`). When
359    /// `field` is `None`, the SQL function falls back to all-field
360    /// search via the engine's analyzer registry.
361    pub fn term(self, term: &str, field: Option<&str>) -> Self {
362        match field {
363            Some(f) => self.text_match(f, term),
364            None => self.r#where(format!("fts_match('_all', {})", quote_str(term))),
365        }
366    }
367
368    /// Combine two builders' filter lists with `AND`. The resulting
369    /// builder keeps the receiver's projection / order / limit /
370    /// offset state and absorbs `other`'s filters.
371    pub fn and(mut self, other: &QueryBuilder<'a>) -> Self {
372        for f in &other.filters {
373            self.filters.push(f.clone());
374        }
375        self
376    }
377
378    /// Wrap the builder's filter list in an `OR` group with `other`'s
379    /// filters: `((self_filters) OR (other_filters))`.
380    pub fn or(mut self, other: &QueryBuilder<'a>) -> Self {
381        let lhs = self.filters.join(" AND ");
382        let rhs = other.filters.join(" AND ");
383        let merged = match (lhs.is_empty(), rhs.is_empty()) {
384            (true, true) => String::new(),
385            (false, true) => lhs,
386            (true, false) => rhs,
387            (false, false) => format!("({lhs}) OR ({rhs})"),
388        };
389        self.filters = if merged.is_empty() {
390            Vec::new()
391        } else {
392            vec![merged]
393        };
394        self
395    }
396
397    /// Negate the current filter list. Renders to `NOT (a AND b ...)`.
398    #[allow(clippy::should_implement_trait)]
399    pub fn not(mut self) -> Self {
400        if self.filters.is_empty() {
401            return self;
402        }
403        let combined = self.filters.join(" AND ");
404        self.filters = vec![format!("NOT ({combined})")];
405        self
406    }
407
408    /// Add a nearest-neighbor vector retrieval predicate. This compatibility
409    /// name delegates to the registered `knn_match` SQL function.
410    ///
411    /// # Errors
412    ///
413    /// Returns an error under the same conditions as [`Self::knn_match`].
414    pub fn vector(self, query: &[f32], k: usize, field: &str) -> Result<Self, SQLError> {
415        self.knn_match(field, query, k)
416    }
417
418    /// Promote the projection list to a single aggregate over `field`,
419    /// e.g. `SELECT count(field) FROM ...`. Resets any previous
420    /// projections.
421    pub fn aggregate(mut self, field: &str, agg: &str) -> Self {
422        self.projections.clear();
423        self.group_by.clear();
424        self.projections.push(format!("{agg}({field})"));
425        self
426    }
427
428    /// Replace projections with `field, count(*)` and add a
429    /// `GROUP BY field` ordering hint. The engine's GROUP BY pipeline
430    /// picks up the projection.
431    pub fn facet(mut self, field: &str) -> Self {
432        self.projections.clear();
433        self.projections.push(field.to_string());
434        self.projections.push("count(*) AS _facet_count".into());
435        self.group_by = vec![field.to_string()];
436        self.order_by_desc("_facet_count")
437    }
438
439    /// Add `score_bm25(field, 'query')` to the projection list.
440    pub fn score_bm25(mut self, query: &str, field: Option<&str>) -> Self {
441        let proj = match field {
442            Some(f) => format!("score_bm25({f}, {})", quote_str(query)),
443            None => format!("score_bm25({})", quote_str(query)),
444        };
445        self.projections.push(proj);
446        self
447    }
448
449    /// Add `score_bayesian_bm25(field, 'query')` to the projection
450    /// list.
451    pub fn score_bayesian_bm25(mut self, query: &str, field: Option<&str>) -> Self {
452        let proj = match field {
453            Some(f) => format!("score_bayesian_bm25({f}, {})", quote_str(query)),
454            None => format!("score_bayesian_bm25({})", quote_str(query)),
455        };
456        self.projections.push(proj);
457        self
458    }
459
460    /// Add exact signed-evidence log-odds fusion. This is an alias for
461    /// [`Self::fuse_bayesian_evidence`]: each signal must emit a prior-free
462    /// evidence probability, and the optional corpus prior enters once.
463    ///
464    /// # Errors
465    ///
466    /// Returns an error unless at least two non-empty signal expressions are
467    /// supplied, or when `base_rate` is not finite and strictly between zero
468    /// and one.
469    pub fn fuse_log_odds(self, signals: &[&str], base_rate: Option<f64>) -> Result<Self, SQLError> {
470        let predicate = render_exact_fusion("fuse_log_odds", signals, base_rate)?;
471        Ok(self.r#where(predicate))
472    }
473
474    /// Add a gated, confidence-scaled positive-evidence retrieval pool.
475    /// This operator is a ranking heuristic and does not claim exact Bayesian
476    /// posterior semantics.
477    ///
478    /// # Errors
479    ///
480    /// Returns an error unless at least two non-empty signal expressions are
481    /// supplied, or when `alpha` is non-finite or outside `[0, 1]`.
482    pub fn pool_positive_evidence(self, signals: &[&str], alpha: f64) -> Result<Self, SQLError> {
483        validate_retrieval_signals("pool_positive_evidence", signals, 2)?;
484        validate_fusion_alpha("pool_positive_evidence", alpha)?;
485        let inner = signals.join(", ");
486        Ok(self.r#where(format!("pool_positive_evidence({inner}, {alpha})")))
487    }
488
489    /// Add exact signed-evidence Bayesian fusion. Each signal must emit a
490    /// prior-free evidence probability; the optional corpus prior enters once.
491    ///
492    /// # Errors
493    ///
494    /// Returns an error unless at least two non-empty signals are supplied, or
495    /// when `base_rate` is not finite and strictly between zero and one.
496    pub fn fuse_bayesian_evidence(
497        self,
498        signals: &[&str],
499        base_rate: Option<f64>,
500    ) -> Result<Self, SQLError> {
501        let predicate = render_exact_fusion("fuse_bayesian_evidence", signals, base_rate)?;
502        Ok(self.r#where(predicate))
503    }
504
505    /// Add a `staged_retrieval(...)` predicate from pre-rendered retrieval
506    /// signals paired with their `top_k` cutoffs. The builder method retains
507    /// its current name, while the generated SQL uses the registered
508    /// shared-IR function.
509    ///
510    /// # Errors
511    ///
512    /// Returns an error when there are no stages, a signal expression is
513    /// empty, or a cutoff is zero or does not fit in SQL `BIGINT`.
514    pub fn multi_stage(self, stages: &[(&str, usize)]) -> Result<Self, SQLError> {
515        validate_stage_count(stages.len())?;
516        validate_stage_cutoffs(stages.iter().map(|(_, top_k)| *top_k))?;
517        if stages.iter().any(|(signal, _)| signal.trim().is_empty()) {
518            return Err(SQLError::TypeMismatch(
519                "staged_retrieval signal expressions cannot be empty".into(),
520            ));
521        }
522        let mut parts: Vec<String> = Vec::with_capacity(stages.len() * 2);
523        for (signal, top_k) in stages {
524            parts.push((*signal).to_string());
525            parts.push(top_k.to_string());
526        }
527        Ok(self.r#where(format!("staged_retrieval({})", parts.join(", "))))
528    }
529
530    /// Add a multi-signal attention-fusion retrieval predicate. `signals`
531    /// must be probability-valued expressions such as `bayesian_match(...)`
532    /// or `calibrated_vector_match(...)`.
533    ///
534    /// # Errors
535    ///
536    /// Returns an error unless at least two non-empty signal expressions are
537    /// supplied.
538    pub fn fuse_attention(self, signals: &[&str]) -> Result<Self, SQLError> {
539        validate_retrieval_signals("fuse_attention", signals, 2)?;
540        Ok(self.r#where(format!("fuse_attention({})", signals.join(", "))))
541    }
542
543    /// Add a learned-fusion retrieval predicate over probability-valued
544    /// signals. `alpha` controls the conjunction strength and defaults to the
545    /// engine's `0.5` when omitted.
546    ///
547    /// # Errors
548    ///
549    /// Returns an error unless at least two non-empty signal expressions are
550    /// supplied, or when `alpha` is non-finite or outside `[0, 1]`.
551    pub fn fuse_learned(self, signals: &[&str], alpha: Option<f64>) -> Result<Self, SQLError> {
552        validate_retrieval_signals("fuse_learned", signals, 2)?;
553        let mut parts = signals
554            .iter()
555            .map(|signal| (*signal).to_string())
556            .collect::<Vec<_>>();
557        if let Some(alpha) = alpha {
558            validate_fusion_alpha("fuse_learned", alpha)?;
559            parts.push(format!("alpha => {alpha}"));
560        }
561        Ok(self.r#where(format!("fuse_learned({})", parts.join(", "))))
562    }
563
564    /// Add the query-pool KNN score transform to `WHERE` through its
565    /// compatibility SQL name. Scores lie in `[0, 1]`, but are not described
566    /// as calibrated probabilities without a held-out evaluation.
567    ///
568    /// # Errors
569    ///
570    /// Returns an error when `field` is empty, `vector` is empty or contains
571    /// a non-finite component, `k` is zero or does not fit in SQL `BIGINT`, or
572    /// `threshold` is non-finite or outside `[0, 1]`.
573    pub fn calibrated_vector_match(
574        self,
575        field: &str,
576        vector: &[f32],
577        k: usize,
578        threshold: Option<f32>,
579    ) -> Result<Self, SQLError> {
580        validate_vector_query("calibrated_vector_match", field, vector, k)?;
581        if let Some(threshold) = threshold {
582            validate_probability_threshold("calibrated_vector_match", f64::from(threshold))?;
583        }
584        let v = render_vector(vector);
585        let predicate = match threshold {
586            Some(t) => format!(
587                "calibrated_vector_match({}, ARRAY[{v}], {k}, {t})",
588                quote_str(field)
589            ),
590            None => format!(
591                "calibrated_vector_match({}, ARRAY[{v}], {k})",
592                quote_str(field)
593            ),
594        };
595        Ok(self.r#where(predicate))
596    }
597
598    /// Build an `RPQ` (Regular Path Query) over a named graph. Replaces the
599    /// `FROM` clause with a table-
600    /// function reference, since RPQ is a relation-producing function.
601    pub fn rpq(mut self, expr: &str, start: u64, graph: &str) -> Self {
602        self.table = format!("rpq({}, {start}, {})", quote_str(expr), quote_str(graph));
603        self
604    }
605
606    /// Build a graph traversal as a relation.
607    pub fn traverse(mut self, graph: &str, start: u64, label: Option<&str>, max_hops: u32) -> Self {
608        let lbl = match label {
609            Some(s) => quote_str(s),
610            None => "NULL".into(),
611        };
612        self.table = format!(
613            "traverse_match({}, {start}, {lbl}, {max_hops})",
614            quote_str(graph)
615        );
616        self
617    }
618
619    /// Build a temporally bounded graph traversal.
620    pub fn temporal_traverse(
621        mut self,
622        graph: &str,
623        start: u64,
624        label: Option<&str>,
625        max_hops: u32,
626        t_min: f64,
627        t_max: f64,
628    ) -> Self {
629        let lbl = match label {
630            Some(s) => quote_str(s),
631            None => "NULL".into(),
632        };
633        self.table = format!(
634            "temporal_traverse({}, {start}, {lbl}, {max_hops}, {t_min}, {t_max})",
635            quote_str(graph)
636        );
637        self
638    }
639
640    /// Add a `uqa_highlight(field, query [, start_tag, end_tag,
641    /// max_fragments, fragment_size])` projection.
642    ///
643    /// # Errors
644    ///
645    /// Returns an error when `field` is empty.
646    pub fn highlight(mut self, field: &str, query: &str) -> Result<Self, SQLError> {
647        validate_field_name("uqa_highlight", field)?;
648        self.projections
649            .push(format!("uqa_highlight({field}, {})", quote_str(query)));
650        Ok(self)
651    }
652
653    /// `uqa_facets(field [, field2, ...])` projection. Fields are emitted as
654    /// column references because the engine groups the values in those
655    /// columns; string literals would facet the field names themselves.
656    ///
657    /// # Errors
658    ///
659    /// Returns an error when no fields are supplied or a field name is empty.
660    pub fn facets(mut self, fields: &[&str]) -> Result<Self, SQLError> {
661        if fields.is_empty() {
662            return Err(SQLError::BadArity {
663                name: "uqa_facets".into(),
664                expected: ">=1 field".into(),
665                actual: 0,
666            });
667        }
668        for field in fields {
669            validate_field_name("uqa_facets", field)?;
670        }
671        let inner = fields.join(", ");
672        self.projections.push(format!("uqa_facets({inner})"));
673        Ok(self)
674    }
675
676    /// Add a `deep_learn(model, training_set)` analytical training projection.
677    pub fn deep_learn(mut self, model: &str, training_set: &str) -> Self {
678        self.projections.push(format!(
679            "deep_learn({}, {})",
680            quote_str(model),
681            quote_str(training_set)
682        ));
683        self
684    }
685
686    /// `bayesian_match(field, '<query>')` filter with the configured
687    /// query-level BM25 score transform. Probability-calibration claims
688    /// require parameters fitted and verified on held-out labels.
689    pub fn bayesian_match(self, field: &str, query: &str) -> Self {
690        self.r#where(format!("bayesian_match({field}, {})", quote_str(query)))
691    }
692
693    /// Bayesian BM25 with a document-level external prior. Rust's SQL
694    /// builder takes the serializable prior shape (`prior_field`,
695    /// `prior_mode`) rather than a closure, so the assembled query can
696    /// still flow through the SQL engine.
697    pub fn score_bayesian_with_prior(
698        self,
699        query: &str,
700        field: Option<&str>,
701        prior_field: Option<&str>,
702        prior_mode: Option<&str>,
703    ) -> Result<Self, SQLError> {
704        let Some(prior_field) = prior_field else {
705            return Err(SQLError::TypeMismatch("prior_fn is required".into()));
706        };
707        let Some(prior_mode) = prior_mode else {
708            return Err(SQLError::TypeMismatch("prior_fn is required".into()));
709        };
710        let field = field.unwrap_or("_default");
711        Ok(self.r#where(format!(
712            "bayesian_match_with_prior({field}, {}, {prior_field}, {})",
713            quote_str(query),
714            quote_str(prior_mode)
715        )))
716    }
717
718    pub fn learn_params(
719        &self,
720        query: &str,
721        labels: &[u8],
722        field: Option<&str>,
723    ) -> Result<std::collections::BTreeMap<String, f64>, SQLError> {
724        self.engine
725            .learn_scoring_params(&self.table, field.unwrap_or("_default"), query, labels)
726    }
727
728    pub fn sparse_threshold(mut self, threshold: f64) -> Result<Self, SQLError> {
729        if self.filters.len() != 1 {
730            return Err(SQLError::TypeMismatch(
731                "sparse_threshold requires a source and accepts exactly one retrieval filter"
732                    .into(),
733            ));
734        }
735        if !threshold.is_finite() {
736            return Err(SQLError::TypeMismatch(format!(
737                "sparse_threshold must be finite, got {threshold:?}"
738            )));
739        }
740        let source = self.filters.pop().ok_or_else(|| {
741            SQLError::Internal("validated sparse_threshold source disappeared".into())
742        })?;
743        self.filters = vec![format!("sparse_threshold({source}, {threshold})")];
744        Ok(self)
745    }
746
747    /// Run `EXPLAIN <assembled SELECT>` and return the planner's rendered plan
748    /// as a single string.
749    pub fn explain(&self) -> Result<String, SQLError> {
750        let stmt = self.to_sql();
751        let result = self.engine.sql(&format!("EXPLAIN {stmt}"), &[])?;
752        let mut out = String::new();
753        for row in &result.rows {
754            if let Some(Value::Str(line)) = row.get("QUERY PLAN") {
755                if !out.is_empty() {
756                    out.push('\n');
757                }
758                out.push_str(line);
759            }
760        }
761        Ok(out)
762    }
763}
764
765#[cfg(test)]
766mod tests {
767    use std::collections::BTreeMap;
768
769    use super::*;
770
771    #[test]
772    fn assembles_basic_select() {
773        // We can't make an Engine in unit tests without bringing in
774        // its full surface, but to_sql doesn't touch the engine when
775        // `execute()` isn't called. Use a transmute-free dummy via
776        // `unsafe { std::mem::zeroed() }`? Avoid that; instead test
777        // through a dedicated integration test that holds a real
778        // Engine. The unit tests below verify the SQL builders that
779        // don't need a runtime: render_value and quote_str.
780    }
781
782    #[test]
783    fn render_int_and_string() {
784        assert_eq!(render_value(&Value::Int(7)).unwrap(), "7");
785        assert_eq!(render_value(&Value::Str("hi".into())).unwrap(), "'hi'");
786    }
787
788    #[test]
789    fn render_string_escapes_single_quote() {
790        assert_eq!(quote_str("it's"), "'it''s'");
791    }
792
793    #[test]
794    fn render_list_uses_array_literal() {
795        let v = Value::List(vec![Value::Int(1), Value::Int(2)]);
796        assert_eq!(render_value(&v).unwrap(), "ARRAY[1, 2]");
797    }
798
799    #[test]
800    fn render_sql_array_preserves_explicit_lower_bound() {
801        let array =
802            uqa_core::ArrayValue::with_lower_bounds(vec![Value::Int(1), Value::Int(2)], vec![0])
803                .expect("one-dimensional array");
804        assert_eq!(render_value(&Value::Array(array)).unwrap(), "'[0:1]={1,2}'");
805    }
806
807    #[test]
808    fn legacy_vector_literals_retain_array_function_shapes() {
809        use uqa_core::{ArrayValue, LegacyVectorKind, LegacyVectorValue};
810        for kind in [LegacyVectorKind::SmallInteger, LegacyVectorKind::Oid] {
811            let ty = kind.type_name();
812            for (elements, bounds, expected) in [
813                (vec![Value::Int(1)], vec![0], format!("'1'::{ty}")),
814                (
815                    vec![Value::Int(1)],
816                    vec![1],
817                    format!("trim_array('1'::{ty}, 0)"),
818                ),
819                (vec![], vec![], format!("trim_array('0'::{ty}, 1)")),
820            ] {
821                let value = Value::LegacyVector(
822                    LegacyVectorValue::try_from_array(
823                        kind,
824                        ArrayValue::with_lower_bounds(elements, bounds).unwrap(),
825                    )
826                    .unwrap(),
827                );
828                assert_eq!(render_value(&value).unwrap(), expected);
829            }
830        }
831    }
832
833    #[test]
834    fn legacy_vector_arrow_output_reports_invalid_text_layout() {
835        let value = Value::LegacyVector(
836            uqa_core::LegacyVectorValue::try_from_array(
837                uqa_core::LegacyVectorKind::SmallInteger,
838                uqa_core::ArrayValue::try_new(vec![]).unwrap(),
839            )
840            .unwrap(),
841        );
842        let result = SQLResult::from_rows(
843            vec!["value".into()],
844            vec![BTreeMap::from([("value".into(), value)])],
845        );
846        let error = sql_result_to_record_batch(&result).unwrap_err();
847        assert!(error
848            .to_string()
849            .contains("42804: array is not a valid int2vector"));
850    }
851
852    #[test]
853    fn mixed_numeric_arrow_output_does_not_round_large_integers() {
854        let result = SQLResult::from_rows(
855            vec!["value".into()],
856            vec![
857                BTreeMap::from([("value".into(), Value::Int(i64::MAX))]),
858                BTreeMap::from([("value".into(), Value::Float(1.5))]),
859            ],
860        );
861        assert_eq!(infer_arrow_type(0, "value", &result), DataType::Utf8);
862        let batch = sql_result_to_record_batch(&result).expect("lossless string batch");
863        let values = batch
864            .column(0)
865            .as_any()
866            .downcast_ref::<StringArray>()
867            .expect("utf8 array");
868        assert_eq!(values.value(0), i64::MAX.to_string());
869    }
870
871    #[test]
872    fn forced_metadata_type_mismatch_is_an_arrow_error() {
873        let result = SQLResult::from_rows(
874            vec!["_doc_id".into()],
875            vec![BTreeMap::from([(
876                "_doc_id".into(),
877                Value::Str("not an id".into()),
878            )])],
879        );
880        let error = sql_result_to_record_batch(&result)
881            .expect_err("a string document id must not silently become null");
882        assert!(error.to_string().contains("int64 was inferred"));
883    }
884
885    #[test]
886    fn arrow_output_preserves_values_at_duplicate_column_positions() {
887        let result = SQLResult::from_rows_with_positions(
888            vec!["value".into(), "value".into()],
889            vec![BTreeMap::new()],
890            Some(vec![vec![Value::Int(5), Value::Int(6)]]),
891        );
892        let batch = sql_result_to_record_batch(&result).expect("duplicate-label Arrow batch");
893        let first = batch
894            .column(0)
895            .as_any()
896            .downcast_ref::<Int64Array>()
897            .expect("first integer array");
898        let second = batch
899            .column(1)
900            .as_any()
901            .downcast_ref::<Int64Array>()
902            .expect("second integer array");
903        assert_eq!(first.value(0), 5);
904        assert_eq!(second.value(0), 6);
905    }
906}