uqa_api/lib.rs
1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Fluent `QueryBuilder` API on top of the SQL surface.
8//!
9//! The builder composes a `SELECT` statement programmatically and
10//! sends it through [`uqa_engine::Engine::sql`]. Infallible methods return
11//! the builder by value; validated helpers return `Result` and remain
12//! linearly chainable with `?`:
13//!
14//! ```no_run
15//! use uqa_api::QueryBuilder;
16//! use uqa_core::Value;
17//! use uqa_engine::Engine;
18//!
19//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
20//! let engine = Engine::new();
21//! let result = QueryBuilder::new(&engine, "docs")
22//! .select_columns(&["id", "_score"])
23//! .where_gte("year", &Value::Int(2024))?
24//! .knn_match("embedding", &[0.1, 0.2], 5)?
25//! .order_by_desc("_score")
26//! .limit(5)
27//! .execute()?;
28//! # let _ = result;
29//! # Ok(())
30//! # }
31//! ```
32//!
33//! The implementation is deliberately thin: it builds a SQL string
34//! and lets the existing parser/engine path do the actual work. Typed
35//! helpers cover common read and retrieval flows; callers can use raw
36//! projection and predicate fragments where appropriate, while complete SQL
37//! remains available through [`uqa_engine::Engine::sql`].
38
39pub mod arrow_export;
40pub mod query_builder;
41
42pub use query_builder::{Order, QueryBuilder};
43
44/// Convenience entry point that builds a fluent [`QueryBuilder`] scoped
45/// to `table` against `engine`.
46pub fn query(engine: &uqa_engine::Engine, table: impl Into<String>) -> QueryBuilder<'_> {
47 QueryBuilder::new(engine, table)
48}