Skip to main content

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}