UQA Engine

UQA Engine is an embeddable database engine that lets one application use a PostgreSQL 18-compatible SQL surface across the behavior covered by its differential suite, full-text search, vector search, graph queries, and ranked retrieval through a shared Rust runtime.

It is designed for applications that need more than a relational table but do not want to assemble a separate database, search server, vector store, and graph engine for every query path.

What you can build

• Run relational queries, joins, aggregates, CTEs, windows, JSON operations, and transactions with PostgreSQL 18 compatibility across the verified SQL surface.
• Search text with BM25 or Bayesian BM25, retrieve vectors with KNN, and combine both signals in hybrid queries.
• Store named graphs, execute Cypher and regular path queries, and call graph traversal or centrality functions from SQL.
• Start in memory for experiments, then choose the default SQLite backend or the pure-Rust redb backend without changing the query API.
• Use the same SQL result and parameter shapes against a local or Cloud UQA node through authenticated Rust, Python, Node.js, and browser HTTP engines.
• Embed the engine in Rust or C/C++, or use the Python, Node.js, and browser WASM bindings included in the workspace.

New in 0.6.3

Version 0.6.3 reduces memory required by large multi-row INSERTs, transaction snapshots and native SQLite text-index mutations. It preserves nested SQL cursor scopes and deadlines, handles catalog-refresh failures inside transaction ownership, and avoids repeated metadata construction in projected aggregate batches. See the release history.

EXPLAIN (MEMORY) reports the selected native executable's live storage before execution in TEXT, JSON, XML and YAML. The SQL contract describes the fields and their measurement boundary.

The platform and build guide covers native packages, browser WASM and iOS/iPadOS source builds using the existing Rust crate or C/C++/Swift integration. Follow the 0.6.3 upgrade guide when updating an existing installation.

Mathematical foundation

A Typed Carrier Algebra for Unified Query Execution states the implementation-grounded theory behind UQA Engine. It distinguishes document support, weighted relations, decorated postings, ranked views, SQL bags, join tuples, graph context, and aggregate state while showing how they compose through one typed planning and execution framework.

The manuscript consolidates and revises the published work on unified query algebra, its graph-data extension, and the Bayesian framework for hybrid search. For academic use, cite the software and the papers relevant to the features used; machine-readable metadata is provided in CITATION.cff.

Try it in a terminal

Install the prebuilt Python package to get both the Python binding and the usql command:

python -m pip install uqa==0.6.3
usql

Building the full workspace requires Rust 1.95 or newer and native build tools. Embedded Rust crates support Rust 1.90; the CLI and Python source builds require Rust 1.95.

Start the interactive usql shell from the repository:

cargo run -p uqa-cli --bin usql

Create a table and run a text search:

CREATE TABLE notes (
    id INTEGER PRIMARY KEY,
    title TEXT,
    body TEXT
);

CREATE INDEX notes_body_gin ON notes USING gin (body);

INSERT INTO notes (id, title, body) VALUES
    (1, 'Rust async', 'Futures and the Tokio runtime'),
    (2, 'Embedded Rust', 'Drivers for constrained devices'),
    (3, 'Web application', 'Forms, routing, and templates');

SELECT id, title, _score
FROM notes
WHERE text_match(body, 'rust async')
ORDER BY _score DESC
LIMIT 5;

Use a file-backed database by adding --db:

cargo run -p uqa-cli --bin usql -- --db notes.uqa

Execute one command without entering the shell:

cargo run -p uqa-cli --bin usql -- -c "SELECT 1 AS ready"

Embed it in Rust

Add the released package to your application:

cargo add uqa@0.6.3

Korean and Japanese text analysis are separate optional features that this command does not enable: nori adds the Korean analyzer with its embedded dictionary, and kuromoji the Japanese one. Enable the ones an application uses, for example cargo add uqa@0.6.3 --features nori,kuromoji or features = ["nori", "kuromoji"] on the dependency in Cargo.toml; uqa-engine takes the same features. A build without them rejects requests for those analyzers. The usql CLI and the Python, Node.js, and browser WASM packages enable both by default.

uqa is the primary Rust package on crates.io. It is a thin facade over uqa-engine that also re-exports the core Value type; applications that need the implementation package directly can depend on uqa-engine. Public component crates including uqa-engine, uqa-client, uqa-api, and uqa-cli are also published independently. The following example creates an in-memory engine, inserts data, and runs SQL through the same interface used by a persistent engine.

use uqa::Engine;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new();

    engine.sql(
        "CREATE TABLE notes (id INTEGER PRIMARY KEY, title TEXT, body TEXT)",
        &[],
    )?;
    engine.sql(
        "CREATE INDEX notes_body_gin ON notes USING gin (body)",
        &[],
    )?;
    engine.sql(
        "INSERT INTO notes (id, title, body) VALUES
         (1, 'Rust async', 'Futures and the Tokio runtime'),
         (2, 'Embedded Rust', 'Drivers for constrained devices')",
        &[],
    )?;

    let result = engine.sql(
        "SELECT id, title, _score
         FROM notes
         WHERE text_match(body, 'rust async')
         ORDER BY _score DESC",
        &[],
    )?;

    for row in result.rows {
        println!("{row:?}");
    }

    Ok(())
}

Run the complete example from this repository:

cargo run -p uqa-engine --example text_search

Additional runnable examples cover hybrid search and encrypted storage:

cargo run -p uqa-engine --example hybrid_search
cargo run -p uqa-engine --example sqlcipher_encrypted_catalog
cargo run -p uqa-engine --example compressed_encrypted_catalog

Connect to a local or Cloud UQA node

uqa-client::HttpEngine sends SQL directly to the authenticated HTTP data plane shared by local and Cloud nodes. Native applications can resolve a project through the installed CLI once during construction, while services can continue to supply an explicit URL and token or trusted UQA_URL and UQA_TOKEN environment variables.

use uqa_client::{HttpEngine, SQLParam};
use uqa_core::Value;

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let engine = HttpEngine::cloud("notes", Some("example")).await?;
let result = engine
    .sql(
        "SELECT id, title FROM notes WHERE id = $1",
        &[SQLParam::scalar(Value::Int(42))],
    )
    .await?;
assert_eq!(result.rows.len(), 1);
# Ok(())
# }

Python and Node.js provide matching local and cloud project constructors; browsers retain explicit URL/token and environment construction because they cannot execute the CLI or access its credential store. Every client calls /v1/sql, /v1/sql/batch, and /v1/sql/stream directly after construction. See the HTTP Engine reference for connection, binding examples, result, streaming, CORS, and security contracts.

Choose a query path

Persistence and encryption

Engine::new() keeps data in memory, while Engine::open(path) and usql --db <path> use the default persistent SQLite backend. Persistent engines restore schemas, documents, text postings, graphs, scoring parameters, models, views, and statistics when reopened.

uqa-storage owns provider-independent contracts and shared data structures, while uqa-storage-sqlite owns SQLite connections, catalogs, indexes, transactions, graph persistence, and compressed storage. Rust callers using concrete storage types must use the updated provider imports.

Applications that want a pure-Rust single-file store can compose the engine with uqa-storage-redb. The provider owns the database, and every Engine::new_session() receives independent transaction state over the same file.

use std::sync::Arc;
use uqa::Engine;
use uqa_storage::PersistentStorageProvider;
use uqa_storage_redb::RedbStorage;

let provider: Arc<dyn PersistentStorageProvider> =
    Arc::new(RedbStorage::open("notes.redb")?);
let engine = Engine::from_persistent_provider(provider)?;
# Ok::<(), Box<dyn std::error::Error>>(())

The redb path supports the catalog, documents, full-text search, graphs, durable B-tree indexes, exact brute-force vectors, physical IVF and HNSW indexes, transactions, and savepoints. It uses the same SQL DDL and query API as SQLite; the main capability difference is that redb does not provide encryption at rest. See the Key/Value storage design for storage and transaction details.

Persistent full-text indexes use clustered postings rather than one physical row or key per (term, doc_id): one (table, field, term, doc_id / 65,536) value stores delta-encoded document IDs, term frequencies, and document lengths, while positions live in a separate value. Ranking opens score-only cursors, reuses one decode buffer for at most 128 postings per block, and leaves positional payloads unread unless a positional consumer asks for them. SQLite schema v22 and the shared Key/Value backend automatically migrate the previous per-document posting format on open; each SQLite or redb rewrite is atomic, idempotent, and rolls back without changing the old data when validation fails.

Security-sensitive deployments should use the SQLCipher path exposed by Engine::open_encrypted. Compressed encrypted containers are also available when compression is required, but they have a narrower, explicitly documented threat model and require an external trusted anchor for whole-file rollback detection.

Read the compressed VFS security contract before selecting that format.

Language bindings

Released Node.js applications install @cognica-io/uqa from npm; npm selects an exact-version native optional package under @cognica-io for the current supported platform. Browser applications install the independent @cognica-io/uqa-wasm package.

The memory foreign-data wrapper is included by default. Enable arrow for native Arrow IPC sources or duckdb for native DuckDB sources; the features are independent and disabled by default. Foreign-table definitions and catalog inspection remain available for every handler; see the feature contract.

Supported platforms

Native Python and Node.js packages select the matching platform during installation. C/C++ packages and standalone usql binaries are available from GitHub Releases. Linux Python wheels require glibc 2.28 or newer. iOS applications can use the Rust crate directly or link the C library as a static archive or XCFramework.

Build and test

Run source-build commands from the repository root. Use Rust 1.95 or newer for the full workspace, CLI and Python binding; embedded Rust crates require Rust 1.90 or newer. Native dependencies also require a C/C++ compiler, libclang, CMake, Make and Perl. The C package tools require CMake 3.24 or newer and Python 3.11 or newer.

On Linux, install your distribution's compiler tools, libclang development package, CMake, Perl and pkg-config. On macOS, install Xcode Command Line Tools and CMake; iOS builds require full Xcode with its iOS SDKs. On Windows, use a Visual Studio developer shell with the MSVC C++ toolchain, LLVM/libclang, CMake and native Perl available on PATH.

Native Rust and CLI

Build the embedded Rust facade or the command-line application:

cargo build --locked --release -p uqa
cargo build --locked --release -p uqa-cli --bin usql

The CLI is written to target/release/usql (usql.exe on Windows). Add --features nori,kuromoji to the Rust facade build to include both morphological analyzers; the CLI enables them by default.

Native C/C++ libraries

Select the host target: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-apple-darwin, aarch64-apple-darwin, or x86_64-pc-windows-msvc. For example, on Linux x86_64:

python3 scripts/build-c-bindings.py \
  --target x86_64-unknown-linux-gnu --profile release \
  --prefix target/c-installed --build-directory target/c-native-build

On macOS, set MACOSX_DEPLOYMENT_TARGET=11.0 before running the command with the matching Apple target. On Windows, use python in the MSVC developer shell. The installation contains headers, shared/static libraries, CMake targets and pkg-config metadata. Link UQA::uqa or UQA::uqa_static from CMake; see the C/C++ consumer guide.

iOS and iPadOS

Build on macOS with full Xcode selected by xcode-select. Install the device and Apple Silicon simulator Rust targets:

rustup target add aarch64-apple-ios aarch64-apple-ios-sim

In a shell used for iOS builds, configure the deployment target and the parser's Clang targets and SDKs. These settings apply to both Rust and C/C++ builds.

unset CFLAGS CXXFLAGS CPPFLAGS LDFLAGS SDKROOT MACOSX_DEPLOYMENT_TARGET
unset LIBRARY_PATH CPATH C_INCLUDE_PATH CPLUS_INCLUDE_PATH
export IPHONEOS_DEPLOYMENT_TARGET=15.0
export BINDGEN_EXTRA_CLANG_ARGS_aarch64_apple_ios="--target=arm64-apple-ios${IPHONEOS_DEPLOYMENT_TARGET} -isysroot \"$(xcrun --sdk iphoneos --show-sdk-path)\""
export BINDGEN_EXTRA_CLANG_ARGS_aarch64_apple_ios_sim="--target=arm64-apple-ios${IPHONEOS_DEPLOYMENT_TARGET}-simulator -isysroot \"$(xcrun --sdk iphonesimulator --show-sdk-path)\""

Rust applications: add the crate to your application's Cargo.toml and use the Rust Engine API. Enable the analyzers your application needs:

[dependencies]
uqa = { version = "0.6.3", features = ["nori", "kuromoji"] }

Build from your application's directory with cargo build --release --target aarch64-apple-ios, or select aarch64-apple-ios-sim for the simulator. To build the Rust facade from this repository instead:

cargo build --locked --release -p uqa --features nori,kuromoji --target aarch64-apple-ios
cargo build --locked --release -p uqa --features nori,kuromoji --target aarch64-apple-ios-sim

C/C++ and Swift applications: build the C ABI as static libraries using the same iOS environment:

cargo rustc --locked --release -p uqa-ffi --lib --crate-type staticlib \
  --target aarch64-apple-ios -- --print=native-static-libs
cargo rustc --locked --release -p uqa-ffi --lib --crate-type staticlib \
  --target aarch64-apple-ios-sim -- --print=native-static-libs

The archives are target/aarch64-apple-ios/release/libuqa.a and target/aarch64-apple-ios-sim/release/libuqa.a. Both include Nori and Kuromoji by default. Combine the device and simulator libraries into one Xcode dependency:

xcodebuild -create-xcframework \
  -library target/aarch64-apple-ios/release/libuqa.a \
  -headers crates/uqa-ffi/include \
  -library target/aarch64-apple-ios-sim/release/libuqa.a \
  -headers crates/uqa-ffi/include \
  -output target/ios/UQA.xcframework

Add UQA.xcframework to the application's linked libraries with Do Not Embed, because it contains static libraries. Add the system libraries/frameworks reported by native-static-libs to the app's linker settings, including libiconv and CoreFoundation. Include <uqa/uqa.h> from C/C++. For Swift, use an application bridging header and expose the macro constants your Swift code needs as typed C constants, such as static const uqa_status app_uqa_ok = UQA_OK;. Store persistent databases in a writable application container directory, such as Application Support, and set the app's deployment target to the library's minimum or newer.

Browser WebAssembly

Install the Emscripten SDK, activate its environment, then build the browser package:

rustup target add wasm32-unknown-emscripten
bash scripts/build-wasm.sh

The JavaScript loader and WASM binary are written under crates/uqa-wasm/js. See the browser examples for loading the module and using IndexedDB persistence.

Workspace tests

Install the commit hook, then build and test the workspace:

bash scripts/install-git-hooks.sh
cargo build --workspace --locked
cargo test --workspace --locked

Run a focused test during development:

cargo test -p uqa-engine --test integration queries::sql_joins::

See CONTRIBUTING.md for contributor checks, crate ownership for implementation boundaries, and verification for compatibility tests and benchmarks.

PostgreSQL 18 compatibility

Compatibility remains incomplete. The manual and manifest-derived ledger distinguish verified behavior from remaining SQL, type, protocol and client work. The unmodified upstream regression corpus has PostgreSQL reference evidence; its complete UQA execution is still unaudited.

The repository includes a deterministic TPC-H-derived scale-factor 0.001 fixture with all 22 default queries. The self-contained correctness gate compares exact columns, row order, NULLs, text bytes, and type-aware canonical numeric values with checked-in PostgreSQL 18.4 results:

cargo test -p uqa-engine --test integration sql_tpch::

The broader PostgreSQL 18.4 gate validates the compatibility manifest and compares every checked-in value or SQLSTATE probe with a live server. Build usql in release mode before running it:

cargo build --release -p uqa-cli
python3 tests/parity/pg18/run_diff.py --validate-manifest
python3 tests/parity/pg18/run_diff.py

Stateful routine, constraint, type-and-temporal, trigger, and rewrite-rule oracles plus the pinned psycopg, pgx, and node-postgres matrix are documented in PG18 differential probes. The current milestone and open-gate ledger is the PostgreSQL 18 compatibility plan.

Current performance verification uses the deterministic regression inventory and the separate controlled-runner protocol. The 2026-11-01 controlled results record all twenty accepted comparisons for source e8abe2c88, including Q1's calibrated interval below its unchanged 1.10 limit. The TPC-H benchmark records a dated comparison of the 0.6.0 release with PostgreSQL 18; posting and relevance measurements remain dated development snapshots in the performance design.

Contributor checks, benchmark build gates, and repository conventions are documented in CONTRIBUTING.md.

Documentation

Project layout

Cypher default-label validation belongs to uqa-graph; Engine supplies the selected graph snapshot and retains its transaction boundary. Graph tests cover nested pattern requirements and missing-label diagnostics, while durable graph lifecycle tests remain with Engine.

RPQ syntax and its parser are shared through uqa-core; planner estimates no longer import the graph runtime. Existing graph syntax imports remain available, and parser tests move with their implementation.

The repository is a Rust workspace with small crates for the algebra, storage, scoring, graph, SQL, planning, execution, engine, CLI, APIs, and language bindings. The full dependency map and ownership rules live in the system architecture, keeping this README focused on using the project.

Model training uses shared native execution for Rust and SQL callers: uqa-execution converts projected table rows, parses training JSON, invokes uqa-ml, and publishes the trained result through Engine's model transaction boundary. Pure training-input and persisted IVF-parameter tests live with their owning crates. See the ownership design.

Creation namespace selection and index-target visibility run in SQL and native execution. Engine lends live schema, role, relation, and session guards; CTAS and index creation retain their existing authorization and collision-check order.

Contributing

See CONTRIBUTING.md for local gates, test conventions, crate boundaries, pull request guidelines, and the current contributor-licensing requirement.

AI-assisted contributions follow AI_POLICY.md, including semantic preservation, algebraic proofs for feature additions, and maintainer judgment on code and design.

License

This source tree uses the Apache License, Version 2.0. The change applies beginning with 0.6.2; already published packages retain their distributed terms, including the 0.6.1 policy. Third-party components retain their own licenses and notices. See the included LICENSE and LICENSING.md files for the complete terms and release boundary.

Optional support, warranties, and other negotiated terms are described in the commercial agreements guide. A separate commercial license is not required solely for proprietary or commercial use of Apache-licensed releases.