Expand description
Top-level engine: a per-table DocumentStore + InvertedIndex
pair, document mutation entry points, and a minimal search API for
text-only round trips. Backed either by in-memory stores
(Engine::new), the SQLite/SQLCipher constructors, or a swappable
uqa_storage::PersistentStorageProvider; the operator pipeline is
identical across backends.
§Public API surface
Construction:
Engine::new- purely in-memory; great for tests and the REPL.Engine::open-SQLite-backed catalog at the given path; reopens restore tables, models, and graphs from disk.Engine::open_encrypted- same catalog restore path, with aSQLCipherkey applied before any schema access.Engine::open_compressed- schema-neutral compressedSQLiteVFS.Engine::open_compressed_encrypted- compressed chunks encrypted after compression.Engine::from_persistent_provider- storage-neutral construction for redb and application-defined providers, with backend-neutral sessions.
Schema and table lifecycle:
Engine::create_table- register a table with declared columns.Engine::create_default_table- convenience for FTS-only tables.Engine::create_vector_field- attach a vector field to an existing table.
Document mutation:
Engine::add_document,Engine::add_document_with_vectorsEngine::add_vector- set or replace a vector for an existing doc.Engine::get_document,Engine::delete_documentEngine::document_countEngine::transaction,Engine::sql_batch- group writes under one engine transaction.
Querying:
Engine::sql(defined insql) - full SQL surface (select / insert / update / delete / create-table, plus the registered functions:text_match,knn_match,fuse_bayesian_evidence(plus exact aliasfuse_log_odds),pool_positive_evidence,multi_field_match,staged_retrieval,graph_*,deep_predict).Engine::sql_cursor/Engine::sql_columnar- bounded, schema-ordered column batches for result sets that should not be retained in memory.Engine::poll_sql_notifications,Engine::wait_for_sql_notifications, andEngine::take_sql_notifications- receive committedLISTEN/NOTIFYmessages for the current session.Engine::search- direct text-only retrieval returning a posting list.Engine::knn_search,Engine::vector_similarity_search- k-NN over a vector field.Engine::hybrid_search- exact signed single-prior fusion of text and vector posting lists (no SQL parsing in the hot path).Engine::robust_hybrid_search- explicitly requested gated, confidence-scaled positive-evidence pooling.
Deep-model persistence:
Engine::save_model,Engine::load_model,Engine::drop_modelEngine::deep_predict- runs a stored model against the cached feature row and returns ranked(doc_id, score)pairs.
Graph workspaces (used by the Cypher front-end and the graph_*
SQL functions):
Engine::create_graph,Engine::drop_graphEngine::graph_with- read-only access by name.Engine::graph_with_mut- exclusive mutable access.
Result types (SQLResult, SQLParam) are re-exported from
uqa-sql. Errors flow through EngineError, which wraps SQL and
storage errors so callers only need to match one enum.
Modules§
- functions
- Register execution-owned extension contracts in the engine.
- migration
- Migration support for legacy UQA
SQLitecatalog directories. - operator_
tree_ bridge - Public Engine retrieval entry points and statement-boundary composition.
- sql
- SQL result formatting, type metadata and bounded cursors.
SQL result formatting,
PostgreSQLtype metadata and bounded columnar cursors.
Structs§
- Automatic
Statistics Status - Process-local health of the database’s automatic statistics worker. A failed refresh retains its durable pending state and is retried.
- Column
Vector - A column vector preserves its position in the declared output schema.
- Columnar
Batch - Column-oriented transfer batch. Physical operators may remain row-oriented internally; API consumers can process one bounded batch without retaining the complete result set or rebuilding columns themselves.
- DiskANN
Maintenance Census - Exact counts for the most recently completed index capture; later commits may already have changed its live corpus.
- DiskANN
Maintenance Status - Census progress is read-only. Evaluated writes increment pruning/rebuild counters only after confirmed completion.
- DiskANN
Rebuild Policy - Soft triggers for one index’s current uncovered documents or logical raw vector bytes. Neither limit is a write quota or a physical-retention limit.
- Engine
- Unified query engine composed from explicit storage, durable-catalog, session, extension, epoch, and query-runtime ownership domains.
- Execution
Outcome - The original native return value or error together with its operation-scoped transaction facts.
- FtsIndex
Stat - Hybrid
Search Params - Exact signed single-prior hybrid-search arguments. Keeps
Engine::hybrid_searchborrowing-friendly without an explosion of positional parameters. - Notification
Subscription - An idle listener independent of the query session that created it. Close every retained handle before replacing a database file.
- Notification
Subscription Error - A stable failure category with an original cause available only through explicit inspection.
- Notification
Subscription Options - Explicit limits for an owned listener. No deployment capacity is inferred from SQL
work_mem. - Notification
Subscription Permit - One non-cloneable reservation against the original hub’s pending/live limit. Reserve before submitting registration to a runtime queue; dropping an unused permit releases capacity without provider I/O. A permit does not retain the Engine or register any channels.
- Prepared
Statement - A session-owned prepared definition’s identity. Removing and recreating its catalog name never rebinds this handle.
- Prepared
Statement Description - Preparation-time parameter and positional result descriptors.
- Robust
Hybrid Search Params - Explicit robust-ranking variant of
HybridSearchParams. This contract applies positive-evidence gating and confidence scaling rather than exact single-prior Bayesian evidence fusion. - SQLBatch
Error - An atomic batch failure with its original SQL error and, when known, zero-based member. Transaction begin, commit and rollback failures are not attributed to a member.
- SQLCursor
- Iterator over schema-ordered column batches backed by a work-mem-bounded
SharedSpill. Dropping the cursor releases its temporary file. Positional conversion preserves separately-valued duplicate labels inColumnarBatch. - SQLCursor
Summary - Metadata known before a cursor is consumed.
- SQLFunction
Context - Host-owned invocation data belonging to the calling session. Registrations are shared across sessions; this data travels with execution, including worker and retained-portal execution, instead of with the registered code. Hosts should store weak session references here to avoid ownership cycles.
- SQLFunction
Options - Execution properties declared for a Rust-backed SQL callback.
- SQLFunction
Registration - An identity-specific lease on a shared registration, independent of the
creating session. Dropping this handle releases the lease without removing
its map entry. Call
unregisterto retire that entry explicitly. - SQLNotice
- A notice that a statement reports without failing, as
PostgreSQL’sereportsends one belowERROR: its level, SQLSTATE and primary message, and the detail and hint that clients receive as fields of their own. - SQLNotification
- One committed SQL notification waiting for this session.
- SQLNotification
Options - Opt-in bounds for the SQL session’s own LISTEN queue. Overflow is terminal and explicit. Queue bytes include string capacities, queue slots and transient prepared batches.
- SQLResult
- SQLRow
Stream - A fused row stream that closes its producer on EOF, failure or explicit
early termination. A cleanup failure is a query error, never EOF. Dropping
an abandoned stream is best-effort cleanup; execution must call
closewhile it can still report an error to its consumer. - SQLTable
Function Result - Result shape returned by a registered SQL table function.
- SQLTable
Function Stream - Pull-based result returned by a registered SQL table function.
- SQLite
Compression Options - Scored
Entry - Sequence
State - Mutable state of a single SQL sequence.
- Text
Search Profile - Observable work counters for one text top-k execution.
Enums§
- Database
File Format - On-disk format of a database file, detected from its header bytes.
- DiskANN
Maintenance Phase - Engine
Error - Execution
Completion - Transaction facts for one admitted host operation. These facts never authorize replay: a message can contain explicit commits, and nontransactional sequence effects survive rollback.
- Notice
Level - The level of a notice, as
PostgreSQLnames its message levels belowERROR, in increasing order of severity. - Notification
Receive - One receive with adapter-owned storage admitted before dequeue. Rejected admission leaves both the queued notification and its delivery sequence unchanged.
- Notification
Wait - A bounded wait ending with one value, elapsed receive time, or explicit closure.
- SQLFunction
Registration Error - SQLFunction
Volatility IMMUTABLE/STABLE/VOLATILEmarker.- SQLParam
- Value bound to a
$Nplaceholder. - SQLite
Error - Scoring
Mode - Scoring strategy for a text retrieval leaf.
- Sequence
Bound ALTER SEQUENCEbound action, distinguishing omission fromNO MINVALUEorNO MAXVALUE.- Sequence
Data Type - Sequence
Restart - Physical restart action carried by
ALTER SEQUENCE. - Text
Search Algorithm - Algorithm that actually produced a text-search result.
Traits§
- AsyncSQL
Engine - Common asynchronous SQL interface implemented by embedded and HTTP engines.
- SQLAggregate
Factory - Fallible creation of an independent SQL aggregate state.
- SQLAggregate
Function - Infallible factory retained for existing Rust aggregate implementations.
- SQLAggregate
State - Per-group state for a registered SQL aggregate function.
- SQLRow
Source - A row producer whose resources require fallible cleanup. A successful
construction transfers its resources to
SQLRowStream.closemust release them even when it reports an error; it is invoked at most once. - SQLScalar
Function - Rust implementation of a scalar SQL function.
- SQLTable
Function - Rust implementation of a SQL table function used in
FROM.