Skip to main content

uqa_engine/
lib.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Top-level engine: a per-table [`DocumentStore`] + [`InvertedIndex`]
8//! pair, document mutation entry points, and a minimal `search` API for
9//! text-only round trips. Backed either by in-memory stores
10//! ([`Engine::new`]), the `SQLite`/`SQLCipher` constructors, or a swappable
11//! [`uqa_storage::PersistentStorageProvider`]; the operator pipeline is
12//! identical across backends.
13//!
14//! # Public API surface
15//!
16//! Construction:
17//! - [`Engine::new`] - purely in-memory; great for tests and the REPL.
18//! - [`Engine::open`] - `SQLite`-backed catalog at the given path; reopens
19//!   restore tables, models, and graphs from disk.
20//! - [`Engine::open_encrypted`] - same catalog restore path, with a
21//!   `SQLCipher` key applied before any schema access.
22//! - [`Engine::open_compressed`] - schema-neutral compressed `SQLite` VFS.
23//! - [`Engine::open_compressed_encrypted`] - compressed chunks encrypted
24//!   after compression.
25//! - [`Engine::from_persistent_provider`] - storage-neutral construction for
26//!   redb and application-defined providers, with backend-neutral sessions.
27//!
28//! Schema and table lifecycle:
29//! - [`Engine::create_table`] - register a table with declared columns.
30//! - [`Engine::create_default_table`] - convenience for FTS-only tables.
31//! - [`Engine::create_vector_field`] - attach a vector field to an
32//!   existing table.
33//!
34//! Document mutation:
35//! - [`Engine::add_document`], [`Engine::add_document_with_vectors`]
36//! - [`Engine::add_vector`] - set or replace a vector for an existing doc.
37//! - [`Engine::get_document`], [`Engine::delete_document`]
38//! - [`Engine::document_count`]
39//! - [`Engine::transaction`], [`Engine::sql_batch`] - group writes under one
40//!   engine transaction.
41//!
42//! Querying:
43//! - `Engine::sql` (defined in [`sql`]) - full SQL surface (select /
44//!   insert / update / delete / create-table, plus the registered
45//!   functions: `text_match`, `knn_match`, `fuse_bayesian_evidence` (plus
46//!   exact alias `fuse_log_odds`), `pool_positive_evidence`,
47//!   `multi_field_match`, `staged_retrieval`, `graph_*`, `deep_predict`).
48//! - [`Engine::sql_cursor`] / [`Engine::sql_columnar`] - bounded, schema-ordered
49//!   column batches for result sets that should not be retained in memory.
50//! - [`Engine::poll_sql_notifications`], [`Engine::wait_for_sql_notifications`],
51//!   and [`Engine::take_sql_notifications`] - receive committed
52//!   `LISTEN`/`NOTIFY` messages for the current session.
53//! - [`Engine::search`] - direct text-only retrieval returning a posting
54//!   list.
55//! - [`Engine::knn_search`], [`Engine::vector_similarity_search`] - k-NN
56//!   over a vector field.
57//! - [`Engine::hybrid_search`] - exact signed single-prior fusion of text and
58//!   vector posting lists (no SQL parsing in the hot path).
59//! - [`Engine::robust_hybrid_search`] - explicitly requested gated,
60//!   confidence-scaled positive-evidence pooling.
61//!
62//! Deep-model persistence:
63//! - [`Engine::save_model`], [`Engine::load_model`], [`Engine::drop_model`]
64//! - [`Engine::deep_predict`] - runs a stored model against the cached
65//!   feature row and returns ranked `(doc_id, score)` pairs.
66//!
67//! Graph workspaces (used by the Cypher front-end and the `graph_*`
68//! SQL functions):
69//! - [`Engine::create_graph`], [`Engine::drop_graph`]
70//! - [`Engine::graph_with`] - read-only access by name.
71//! - [`Engine::graph_with_mut`] - exclusive mutable access.
72//!
73//! Result types ([`SQLResult`], [`SQLParam`]) are re-exported from
74//! `uqa-sql`. Errors flow through [`EngineError`], which wraps SQL and
75//! storage errors so callers only need to match one enum.
76
77pub mod functions;
78pub mod migration;
79pub mod operator_tree_bridge;
80mod queries;
81/// SQL result formatting, type metadata and bounded cursors.
82pub use uqa_execution::result as sql;
83
84mod analyzers;
85mod async_sql_engine;
86mod cancellation;
87mod capabilities;
88mod catalog_indexes;
89mod domains;
90mod fdw;
91mod fts;
92mod generated;
93mod graphs;
94mod hierarchy;
95mod hook;
96mod models;
97mod notifications;
98mod open;
99mod prepared;
100mod relations;
101mod roles;
102mod schema_security;
103mod search;
104mod sequence_catalog;
105mod sequence_session;
106mod sequence_snapshot;
107mod sequences;
108mod session;
109mod sql_registry;
110mod state;
111mod statistics;
112pub use statistics::AutomaticStatisticsStatus;
113pub use uqa_execution::maintenance::diskann::{
114    DiskANNMaintenanceCensus, DiskANNMaintenancePhase, DiskANNMaintenanceStatus,
115    DiskANNRebuildPolicy,
116};
117mod row_locks;
118mod statement_cache;
119mod table_storage;
120mod tables;
121mod transactions;
122mod user_functions;
123mod value_index;
124
125pub(crate) use uqa_execution::mutation::{
126    deferred::DeferredForeignKeyCheck, overlay::CommandMutationOverlay,
127};
128pub(crate) use uqa_execution::row_locks::publication::TransactionRowChange;
129
130use std::collections::{BTreeMap, BTreeSet};
131use std::path::Path;
132use std::sync::atomic::{AtomicBool, Ordering};
133use std::sync::Arc;
134
135use parking_lot::RwLock;
136use uqa_analysis::{analyzer::standard_analyzer, registry as analyzer_registry, Analyzer};
137use uqa_core::{DocId, FieldName, Value};
138use uqa_ml::{DeepLearnOutput, DeepModel, LearnOptions, TrainingSet};
139use uqa_operators::ExecutionContext;
140use uqa_scoring::{
141    BM25Params, BayesianBM25Params, BayesianBM25Scorer, CalibrationMetrics, CalibrationReport,
142    ParameterLearner, RawBm25Score, UnsupervisedBm25ScoreEstimator,
143};
144use uqa_sql::SQLError;
145use uqa_storage::{
146    document_store::Document, AnalyzerPhase, CatalogFacade, CatalogIndexRow, ColumnStatsInput,
147    ColumnStatsRow, DocumentStore, HNSWIndex, HNSWIndexParams, IVFIndex, IVFIndexParams,
148    InvertedIndex, MemoryDocumentStore, MemoryInvertedIndex, MemoryVectorIndex,
149    PersistentStorageBackend, PersistentStorageProvider, PersistentStorageSession,
150    RelationIdentity, SequenceRow, StorageBackendError, StorageBackendResult, StorageSavepointId,
151    TableSchema, VectorFieldSchema, VectorIndex, VectorIndexOpenMode, VectorIndexSpec,
152};
153use uqa_storage_sqlite::{
154    ManagedConnection, SQLiteCompressedContainerAnchor, SQLiteStorageProvider,
155};
156
157pub use notifications::{
158    NotificationSubscription, NotificationSubscriptionError, NotificationSubscriptionOptions,
159    NotificationSubscriptionPermit, NotificationWait, SQLNotification, SQLNotificationOptions,
160};
161pub use sql::{SQLCursor, SQLCursorSummary};
162pub use uqa_execution::{ColumnVector, ColumnarBatch};
163pub use uqa_sql::{
164    ast::{SequenceBound, SequenceDataType, SequenceRestart},
165    AsyncSQLEngine, NoticeLevel, SQLBatchError, SQLNotice, SQLParam, SQLResult,
166};
167pub use uqa_storage_sqlite::{DatabaseFileFormat, SQLiteCompressionOptions, SQLiteError};
168
169use functions::RegisteredSQLFunction;
170pub use functions::{
171    SQLAggregateFunction, SQLAggregateState, SQLFunctionOptions, SQLFunctionVolatility,
172    SQLScalarFunction, SQLTableFunction, SQLTableFunctionResult, SQLTableFunctionStream,
173};
174use notifications::{
175    NotificationHubOwner as NotificationHub, PendingListenAction, PendingNotification,
176};
177use state::{
178    DurableCatalogSnapshot, DurableCatalogState, EpochCoordinator, QueryRuntime, RuntimeExtensions,
179    SessionContext, StorageContext, StoredView, StoredViewKind,
180};
181use statement_cache::{PreparedStatementPlan, SQLStatementCache};
182
183#[cfg(test)]
184use uqa_execution::catalog::sequence::restoration::SEQUENCES_METADATA_KEY;
185/// Default nesting cap for user-defined function calls. Exceeding it
186/// raises `stack depth limit exceeded`, mirroring the `PostgreSQL`
187/// `max_stack_depth` guard.
188const SQL_FUNCTION_DEPTH_LIMIT: usize = 128;
189
190#[derive(Debug, thiserror::Error)]
191pub enum EngineError {
192    #[error("SQL error: {0}")]
193    SQL(#[from] SQLError),
194    #[error("storage error: {0}")]
195    Storage(#[from] SQLiteError),
196}
197
198pub type EngineResult<T> = std::result::Result<T, EngineError>;
199
200pub use uqa_core::ScoredEntry;
201
202pub use uqa_scoring::{TextSearchAlgorithm, TextSearchProfile};
203
204pub use uqa_storage::FtsIndexStat;
205
206pub use uqa_scoring::ScoringMode;
207
208type TableFieldAnalyzerRegistry = BTreeMap<(String, String), uqa_storage::FieldAnalyzerBinding>;
209type SessionPortalTableSnapshots = Arc<BTreeMap<RelationIdentity, Arc<TableState>>>;
210type SessionPortalViewSnapshots = Arc<BTreeMap<RelationIdentity, StoredView>>;
211type SessionPortalSQLFunctionSnapshots =
212    Arc<BTreeMap<String, Vec<Arc<user_functions::SQLUserFunction>>>>;
213type SessionPortalCatalogSnapshot = Arc<session::RetainedCatalogSnapshot>;
214type SessionPortalTransactionOverlay =
215    Arc<BTreeMap<String, uqa_execution::query::document_changes::DocumentChanges>>;
216type ColumnStatsMap = BTreeMap<String, uqa_planner::ColumnStats>;
217type FixedTransactionCatalogBaseline = BTreeMap<[u8; 16], (RelationIdentity, Vec<u8>)>;
218type NontransactionalSequenceValues = BTreeMap<[u8; 16], NontransactionalSequenceHistory>;
219
220#[derive(Clone, Default)]
221struct NontransactionalSequenceHistory {
222    values_by_definition: BTreeMap<[u8; 16], NontransactionalSequenceValue>,
223    object_id: [u8; 16],
224    session_currval: Option<SessionSequenceValue>,
225    defines_lastval: bool,
226}
227
228/// Unified query engine composed from explicit storage, durable-catalog,
229/// session, extension, epoch, and query-runtime ownership domains.
230pub struct Engine {
231    storage: StorageContext,
232    durable: Arc<DurableCatalogState>,
233    session: Arc<SessionContext>,
234    extensions: RuntimeExtensions,
235    epochs: EpochCoordinator,
236    runtime: QueryRuntime,
237    row_locks: Arc<row_locks::RowLockManager>,
238    statistics: Arc<statistics::StatisticsCoordinator>,
239    notification_hub: Arc<NotificationHub>,
240    session_id: u64,
241    owns_session_registration: bool,
242    query_table_snapshots: Option<SessionPortalTableSnapshots>,
243    query_view_snapshots: Option<SessionPortalViewSnapshots>,
244    query_sql_function_snapshots: Option<SessionPortalSQLFunctionSnapshots>,
245    query_catalog_snapshot: Option<SessionPortalCatalogSnapshot>,
246    query_transaction_overlay: Option<SessionPortalTransactionOverlay>,
247    query_transaction_origin: Option<u64>,
248}
249
250pub use uqa_execution::catalog::sequence::SequenceState;
251
252#[derive(Clone, Copy, Default)]
253struct TransactionDirtyState {
254    table_data: bool,
255    table_catalog: bool,
256    catalog_registry: bool,
257}
258
259/// Physical write admission for the lifetime of a transaction. Savepoint undo restores SQL access characteristics but cannot turn an already promoted physical writer back into an unwritten reader.
260#[derive(Clone, Copy, PartialEq, Eq)]
261enum TransactionIntent {
262    ReadOnly,
263    ReadWrite,
264}
265
266#[derive(Clone, Copy, PartialEq, Eq)]
267enum BackendTransactionMode {
268    Deferred,
269    Writer,
270    Versioned,
271}
272
273#[derive(Clone, Copy, PartialEq, Eq)]
274enum TransactionStatus {
275    Active,
276    Failed,
277    FailedBackendAborted,
278    CommitPending(uqa_storage::mvcc::TransactionOutcomeId),
279    RollbackPending(uqa_storage::mvcc::TransactionOutcomeId),
280}
281
282#[derive(Clone, Copy, PartialEq, Eq)]
283enum TransactionFrameKind {
284    ExplicitBlock,
285    ImplicitStatement,
286    SimpleQuery,
287}
288
289#[derive(Debug, Clone, Copy, PartialEq, Eq)]
290struct TransactionCharacteristicsState {
291    isolation: uqa_sql::ast::TransactionIsolationLevel,
292    read_only: bool,
293    deferrable: bool,
294    /// The characteristics the transaction assigned itself with `BEGIN`, `SET TRANSACTION` or `SET transaction_*`, which `pg_settings` reports with the source `session` rather than `override`.
295    assigned: u8,
296}
297
298impl TransactionCharacteristicsState {
299    const ISOLATION_ASSIGNED: u8 = 1;
300    const READ_ONLY_ASSIGNED: u8 = 2;
301    const DEFERRABLE_ASSIGNED: u8 = 4;
302}
303
304impl Default for TransactionCharacteristicsState {
305    fn default() -> Self {
306        Self {
307            isolation: uqa_sql::ast::TransactionIsolationLevel::ReadCommitted,
308            read_only: false,
309            deferrable: false,
310            assigned: 0,
311        }
312    }
313}
314
315pub(crate) use uqa_sql::catalog::constraints::ConstraintIdentity;
316
317#[derive(Debug, Clone, Default)]
318pub(crate) struct ConstraintModeState {
319    all: Option<bool>,
320    named: BTreeMap<ConstraintIdentity, bool>,
321}
322
323struct TransactionFrame {
324    started_at_micros: i64,
325    /// Whether this outer frame is an implicit SQL-driver boundary rather than a user-visible `BEGIN` block. A simple-query batch promotes it when the batch reaches `BEGIN`.
326    implicit_statement: bool,
327    /// Whether the user has entered an explicit transaction block. A multi-statement simple-query message still owns one atomic frame, but `PostgreSQL` permits `DISCARD` there until `BEGIN` promotes it.
328    explicit_transaction_block: bool,
329    storage_savepoint: Option<StorageSavepointId>,
330    intent: TransactionIntent,
331    backend_mode: BackendTransactionMode,
332    status: TransactionStatus,
333    characteristics: TransactionCharacteristicsState,
334    first_snapshot_set: bool,
335    fixed_snapshot: Option<FixedTransactionSnapshot>,
336    fixed_catalog_records: Option<Arc<uqa_storage::mvcc::CommittedReadBoundary>>,
337    /// Last committed table catalog installed while a fixed row snapshot is active. Immutable fingerprints distinguish this transaction's own DDL overlay from definitions refreshed from sibling commits.
338    fixed_catalog_baseline: Option<FixedTransactionCatalogBaseline>,
339    /// `PostgreSQL` transaction/subtransaction IDs along the active frame path. The first slot belongs to this frame and each following slot to the correspondingly indexed SQL savepoint.
340    xid_levels: Vec<Option<u32>>,
341    savepoints: Vec<TransactionSavepoint>,
342    session_snapshot: SessionStateSnapshot,
343    data_snapshot: Option<EngineDataSnapshot>,
344    dirty_at_begin: TransactionDirtyState,
345    prepared_changes: uqa_execution::statement::prepared::invalidation::PreparedInvalidationLog,
346    /// Lock mark this frame started with. Rolling the whole frame back releases every acquisition at or above it, independent of the savepoint marks the frame allocated later.
347    begin_lock_mark: u32,
348    lock_mark: u32,
349    next_lock_mark: u32,
350    snapshot_change_baseline: row_locks::RowChangeBaseline,
351    row_changes: Vec<TransactionRowChange>,
352    /// The index of the rows the transaction changed, which reads at a fixed snapshot take views of; only the outer frame keeps one.
353    fixed_identities: Option<uqa_execution::query::document_changes::ChangedIdentities>,
354    statistics_changes: statistics::StatisticsChanges,
355    /// What this frame's commit did with its statistics changes, for the session to take over when the commit has succeeded.
356    statistics_settlement: statistics::StatisticsSettlement,
357    deferred_foreign_key_checks: Vec<DeferredForeignKeyCheck>,
358    deferred_constraint_trigger_events:
359        Vec<uqa_execution::mutation::triggers::DeferredConstraintTriggerEvent>,
360    pending_listen_actions: Vec<PendingListenAction>,
361    pending_notifications: Vec<PendingNotification>,
362    pending_notification_commit:
363        parking_lot::Mutex<Option<Box<notifications::CrossNotificationCommit>>>,
364    constraint_modes: ConstraintModeState,
365    /// Values allocated by `nextval` or installed by `setval` are not rolled back in `PostgreSQL`, except that allocations made against a transactionally changed sequence definition roll back with that definition. Every active frame records values by definition generation so transaction, savepoint, and PL/pgSQL exception rollback can reapply exactly the generation owned by the rollback target while preserving the latest session `currval` and `lastval` effects.
366    nontransactional_sequence_values: NontransactionalSequenceValues,
367}
368
369enum FixedTransactionSnapshot {
370    Pinned(Arc<Engine>),
371    Detached(SessionPortalTableSnapshots),
372}
373
374impl FixedTransactionSnapshot {
375    fn table(&self, relation: &RelationIdentity) -> Option<Arc<TableState>> {
376        match self {
377            Self::Pinned(snapshot) => snapshot.storage.tables.read().get(relation).cloned(),
378            Self::Detached(tables) => tables.get(relation).cloned(),
379        }
380    }
381
382    fn table_for_live_relation(
383        &self,
384        relation: &RelationIdentity,
385        live: &TableState,
386    ) -> Option<Arc<TableState>> {
387        let storage_generation = live.storage_generation();
388        let exact = self.table(relation);
389        if exact
390            .as_ref()
391            .is_some_and(|table| table.storage_generation() == storage_generation)
392        {
393            return exact;
394        }
395        match self {
396            Self::Pinned(snapshot) => snapshot
397                .storage
398                .tables
399                .read()
400                .values()
401                .find(|table| table.storage_generation() == storage_generation)
402                .cloned(),
403            Self::Detached(tables) => tables
404                .values()
405                .find(|table| table.storage_generation() == storage_generation)
406                .cloned(),
407        }
408    }
409}
410
411struct TransactionSavepoint {
412    name: String,
413    storage_savepoint: StorageSavepointId,
414    characteristics: TransactionCharacteristicsState,
415    session_snapshot: SessionStateSnapshot,
416    data_snapshot: Option<EngineDataSnapshot>,
417    dirty: TransactionDirtyState,
418    prepared_change_mark:
419        uqa_execution::statement::prepared::invalidation::PreparedInvalidationMark,
420    lock_mark: u32,
421    /// The length of the frame's row changes at the savepoint. The changes only grow after it, so a rollback truncates them to this length.
422    row_changes: usize,
423    statistics_changes: statistics::StatisticsChanges,
424    deferred_foreign_key_checks: Vec<DeferredForeignKeyCheck>,
425    deferred_constraint_trigger_events:
426        Vec<uqa_execution::mutation::triggers::DeferredConstraintTriggerEvent>,
427    pending_listen_actions: Vec<PendingListenAction>,
428    pending_notifications: Vec<PendingNotification>,
429    constraint_modes: ConstraintModeState,
430}
431
432/// Lightweight SQL-session state that follows transaction/savepoint rollback for every backend. It is intentionally separate from the database-sized memory-engine snapshot so persistent sessions receive identical SET, search-path, and statement-cache semantics. Sequence `currval` and last-used entries produced after the snapshot are reapplied because sequence functions are nontransactional in `PostgreSQL`.
433#[derive(Clone, Default)]
434struct SessionStateSnapshot {
435    command_overlays: Vec<uqa_execution::mutation::overlay::CommandOverlayCheckpoint>,
436    /// A pinned physical graph view plus this transaction's changed identities. Savepoints retain only handles and changed-id checkpoints, never graph payload replicas.
437    graph_overlay: Option<GraphTransactionOverlay>,
438    search_path: Vec<String>,
439    /// The OIDs of the session's temporary namespace and its TOAST namespace once its first temporary object created them; a rollback past that creation forgets them.
440    temporary_namespace: Option<uqa_sql::catalog::temporary_namespace::TemporaryNamespaceOids>,
441    session_vars: BTreeMap<String, String>,
442    parameter_scopes: uqa_sql::semantics::parameters::ParameterScopes<state::RuntimeParameterValue>,
443    sequence_currvals: BTreeMap<RelationIdentity, SessionSequenceValue>,
444    last_sequence: Option<SessionLastSequenceReference>,
445    sequence_discard_generation: u64,
446    sql_statement_cache: SQLStatementCache,
447    /// Names of portals that existed at this transaction or savepoint boundary. Rollback removes portals created later without rewinding cursor positions or resurrecting closed portals.
448    portal_names: BTreeSet<String>,
449    listened_channels: Vec<String>,
450    authorization: uqa_sql::catalog::roles::session::SessionAuthorization,
451}
452
453#[derive(Clone)]
454struct GraphTransactionOverlay {
455    store: Arc<uqa_graph::PersistentGraphStore>,
456    names: Arc<BTreeSet<String>>,
457}
458
459#[derive(Clone, Copy, PartialEq, Eq)]
460enum PinnedPortalTransactionControl {
461    MakeHoldable,
462    Reject,
463}
464
465struct SessionPortalState {
466    data: SessionPortalData,
467    schema: uqa_sql::RowSchema,
468    transaction_origin: u64,
469    position: SessionPortalPosition,
470    scrollable: bool,
471    holdable: bool,
472    /// Action to take when procedural transaction control encounters this pinned PL/pgSQL loop portal.
473    pinned_transaction_control: PinnedPortalTransactionControl,
474    /// A PL/pgSQL row loop pins its portal while user statements run so the loop body cannot close the executor that owns its current tuple batch.
475    pin_count: usize,
476    /// Retain live catalog visibility while the executor is temporarily outside the session map.
477    _registration: uqa_execution::statement::portal::PortalRegistration,
478}
479
480use uqa_execution::statement::portal::{SessionPortalCommandDeclaration, SessionPortalDeclaration};
481
482enum SessionPortalData {
483    Pending {
484        query: uqa_planner::QueryPlan,
485        params: Vec<SQLParam>,
486        table_snapshots: SessionPortalTableSnapshots,
487        view_snapshots: SessionPortalViewSnapshots,
488        sql_function_snapshots: SessionPortalSQLFunctionSnapshots,
489        catalog_snapshot: SessionPortalCatalogSnapshot,
490        restart: Option<SessionPortalRestart>,
491    },
492    PendingCommand {
493        command: Box<uqa_planner::CommandPlan>,
494        params: Vec<SQLParam>,
495        /// Preserve `PostgreSQL` 18's explicit-`SCROLL` DML tuple image while retaining the command's returned row count.
496        null_returning_values: bool,
497    },
498    Result(SQLResult),
499    Indexed(SessionPortalMaterialization),
500    Streaming {
501        worker: SessionPortalWorker,
502        materialized: Option<SessionPortalMaterialization>,
503        eof: bool,
504        restart: Option<SessionPortalRestart>,
505    },
506}
507
508struct SessionPortalRestart {
509    query: uqa_planner::QueryPlan,
510    params: Vec<SQLParam>,
511    table_snapshots: SessionPortalTableSnapshots,
512    view_snapshots: SessionPortalViewSnapshots,
513    sql_function_snapshots: SessionPortalSQLFunctionSnapshots,
514    catalog_snapshot: SessionPortalCatalogSnapshot,
515}
516
517struct SessionPortalMaterialization {
518    rows: uqa_execution::IndexedSpill,
519}
520
521use uqa_execution::statement::portal::worker::{
522    SessionPortalWorker, SessionPortalWorkerRequest, SessionPortalWorkerResponse,
523};
524
525/// `PostgreSQL` distinguishes the positions before the first row and after the last row from a position on a row.
526#[derive(Debug, Clone, Copy, PartialEq, Eq)]
527enum SessionPortalPosition {
528    BeforeFirst,
529    /// The one-based position of the current row.
530    OnRow(usize),
531    /// Number of rows processed while moving forward before the executor reported end of scan.
532    AfterLast(usize),
533}
534
535#[derive(Clone, Copy)]
536struct SessionRandomState {
537    s0: u64,
538    s1: u64,
539}
540
541impl Default for SessionRandomState {
542    fn default() -> Self {
543        Self {
544            s0: 0x5851_f42d_4c95_7f2d,
545            s1: 0x1405_7b7e_f767_814f,
546        }
547    }
548}
549
550#[derive(Clone)]
551struct EngineDataSnapshot {
552    tables: BTreeMap<RelationIdentity, TableDataSnapshot>,
553    durable: DurableCatalogSnapshot,
554    foreign_memory_tables: BTreeMap<RelationIdentity, Vec<uqa_sql::ResultRow>>,
555}
556
557#[derive(Clone)]
558#[expect(clippy::struct_excessive_bools, reason = "independent snapshot flags")]
559struct TableDataSnapshot {
560    state: Arc<TableState>,
561    security: state::BoundTableSecurity,
562    storage_generation: [u8; 16],
563    document_store: Arc<dyn DocumentStore>,
564    inverted_index: Arc<dyn InvertedIndex>,
565    vector_indexes: BTreeMap<FieldName, Arc<dyn VectorIndex>>,
566    value_indexes: BTreeMap<uqa_storage::ValueIndexKey, value_index::ColumnValueIndex>,
567    fts_fields: Vec<FieldName>,
568    columns: Vec<uqa_sql::ast::ColumnDef>,
569    columns_declared: bool,
570    /// One-past-the-last allocated document id. `u128` is intentional: it
571    /// represents `u64::MAX + 1`, so exhaustion is distinguishable from an
572    /// available final id and can never wrap or issue a duplicate.
573    next_id: u128,
574    analyzer: Analyzer,
575    column_stats: BTreeMap<String, uqa_planner::ColumnStats>,
576    column_stats_loaded: bool,
577    column_stats_dirty: bool,
578    statistics_maintenance: statistics::MaintenanceState,
579    table_checks: Vec<uqa_sql::ast::TableCheck>,
580    foreign_keys: Vec<uqa_sql::ast::ForeignKey>,
581    key_constraints: Vec<uqa_sql::ast::TableKeyConstraint>,
582    hierarchy: uqa_sql::ast::TableHierarchy,
583    row_type_array_name: Option<String>,
584    dropped_attributes: Vec<uqa_sql::catalog::relation_attributes::DroppedAttribute>,
585    doc_count_cache: u64,
586    doc_count_dirty: bool,
587}
588
589pub(crate) struct TableState {
590    /// Session-local relation generation. Reloads of the same catalog object preserve this value, while CREATE allocates a new value even when a dropped relation's name is reused.
591    lifecycle_id: std::sync::atomic::AtomicU64,
592    /// Durable logical relation identity used by `PostgreSQL` catalogs. Renames, schema changes, `TRUNCATE`, and reopen preserve it.
593    object_id: [u8; 16],
594    /// Durable SQL role ownership and ACL. Mutations publish this value atomically and preserve the relation's logical and physical identities.
595    security: state::CatalogCell<state::BoundTableSecurity>,
596    /// Durable physical-storage generation shared by every session. Schema-only changes preserve it; CREATE and TRUNCATE replace it so a fixed transaction snapshot never aliases a different physical relation lifetime.
597    storage_generation: RwLock<[u8; 16]>,
598    pub(crate) document_store: RwLock<Box<dyn DocumentStore>>,
599    inverted_index: RwLock<Box<dyn InvertedIndex>>,
600    vector_indexes: RwLock<uqa_storage::vector_index::VectorIndexes>,
601    fts_fields: state::CatalogCell<Vec<FieldName>>,
602    /// Column schema captured at CREATE TABLE / ALTER TABLE time, driving auto-id allocation and ALTER COLUMN bookkeeping.
603    columns: state::CatalogCell<Vec<uqa_sql::ast::ColumnDef>>,
604    columns_declared: state::CatalogCell<bool>,
605    /// Retained document-ID floor. Capable persistent backends reserve from the storage-owned durable namespace; temporary, memory and serialized backends use this local state. `u128` preserves the exhausted `u64::MAX + 1` value.
606    next_id: parking_lot::Mutex<u128>,
607    /// Whether the table's single integer primary key, if it has one, names its rows' identities (see `MutationIdentifiers::maps_integer_keys`). A table an earlier version wrote with a row at an identity its key does not name resolves its keys through the key's index instead.
608    maps_integer_keys: AtomicBool,
609    analyzer: state::CatalogCell<Analyzer>,
610    /// Per-column statistics refreshed by `ANALYZE table_name` or lazily
611    /// by `column_stats` after writes mark the table dirty. Keyed by column
612    /// name.
613    column_stats: state::CatalogCell<BTreeMap<String, uqa_planner::ColumnStats>>,
614    column_stats_loaded: AtomicBool,
615    column_stats_dirty: AtomicBool,
616    /// Changes since the last analysis of a table that no catalog tracks: tables of a memory-only engine and temporary tables. Their lazy analysis follows the maintenance policy of durable tables instead of re-analyzing after every write.
617    statistics_maintenance: parking_lot::Mutex<statistics::MaintenanceState>,
618    /// Table-level `CHECK` constraints, evaluated against every row
619    /// at INSERT / UPDATE time.
620    table_checks: state::CatalogCell<Vec<uqa_sql::ast::TableCheck>>,
621    /// Table-level `FOREIGN KEY` constraints. Each entry binds local
622    /// columns to a `(ref_table, ref_columns)` lookup target.
623    foreign_keys: state::CatalogCell<Vec<uqa_sql::ast::ForeignKey>>,
624    /// Typed PRIMARY KEY / UNIQUE tuples, including composite keys and
625    /// their SQL NULL-equality policy.
626    key_constraints: state::CatalogCell<Vec<uqa_sql::ast::TableKeyConstraint>>,
627    /// Direct parents, an optional partition key, and an optional child bound.
628    /// The complete object is persisted with the table's constraint envelope.
629    hierarchy: state::CatalogCell<uqa_sql::ast::TableHierarchy>,
630    /// Lazily built per-column value indexes for PRIMARY KEY / UNIQUE
631    /// / `CREATE INDEX` btree columns. Maintained incrementally by the
632    /// document write paths; cleared on bulk reloads.
633    value_indexes: RwLock<BTreeMap<uqa_storage::ValueIndexKey, value_index::ColumnValueIndex>>,
634    /// Cached `document_store.len()`. Persistent stores answer `len`
635    /// with a `COUNT(*)` query, which used to run once per SQL
636    /// statement for planner row estimates; the cache is invalidated
637    /// by every write and recomputed on demand.
638    doc_count_cache: std::sync::atomic::AtomicU64,
639    doc_count_dirty: AtomicBool,
640    /// Immutable relation lifecycle attributes captured at creation.
641    persistence: uqa_sql::ast::RelationPersistence,
642    on_commit: uqa_sql::ast::OnCommitAction,
643    /// The public OIDs allocated when the table was created; `None` for a table created before OIDs were recorded, which derives them from its identity.
644    catalog_oids: Option<uqa_sql::catalog::relation_oids::RelationCatalogOids>,
645    row_type_array_name: state::CatalogCell<Option<String>>,
646    dropped_attributes:
647        state::CatalogCell<Vec<uqa_sql::catalog::relation_attributes::DroppedAttribute>>,
648}
649
650impl TableState {
651    fn lifecycle_id(&self) -> u64 {
652        self.lifecycle_id.load(Ordering::Acquire)
653    }
654
655    fn storage_generation(&self) -> [u8; 16] {
656        *self.storage_generation.read()
657    }
658
659    fn object_id(&self) -> [u8; 16] {
660        self.object_id
661    }
662
663    fn recorded_catalog_oids(
664        &self,
665    ) -> Option<uqa_sql::catalog::relation_oids::RelationCatalogOids> {
666        self.catalog_oids
667    }
668
669    /// The table's public OIDs: the recorded ones, or those its identity derives.
670    fn relation_oids(&self) -> uqa_sql::catalog::relation_oids::RelationCatalogOids {
671        self.catalog_oids.unwrap_or_else(|| {
672            uqa_sql::catalog::relation_oids::RelationCatalogOids::legacy(
673                uqa_sql::catalog::relation_oids::RelationOidKind::Table,
674                &self.object_id,
675            )
676        })
677    }
678
679    /// The namespace this table's document identities are allocated and observed in.
680    fn document_id_namespace(
681        &self,
682    ) -> uqa_storage::document_store::identifiers::DocumentIdNamespace {
683        uqa_storage::document_store::identifiers::DocumentIdNamespace {
684            object: self.object_id(),
685            generation: self.storage_generation(),
686        }
687    }
688
689    fn role_owner(&self) -> uqa_sql::catalog::roles::RoleIdentity {
690        self.security.read().role_owner
691    }
692
693    fn security(&self) -> state::BoundTableSecurity {
694        self.security.read().clone()
695    }
696
697    fn fts_fields(&self) -> Vec<FieldName> {
698        self.fts_fields.read().clone()
699    }
700}
701
702fn next_table_lifecycle_id() -> u64 {
703    static NEXT_TABLE_LIFECYCLE_ID: std::sync::atomic::AtomicU64 =
704        std::sync::atomic::AtomicU64::new(1);
705    uqa_core::atomic::try_update_u64(
706        &NEXT_TABLE_LIFECYCLE_ID,
707        Ordering::Relaxed,
708        Ordering::Relaxed,
709        |current| current.checked_add(1),
710    )
711    .expect("table lifecycle id space exhausted")
712}
713
714pub(crate) use uqa_execution::catalog::identity::new_nonzero_catalog_identity;
715
716fn new_table_object_id() -> StorageBackendResult<[u8; 16]> {
717    new_nonzero_catalog_identity("table", "object identity")
718}
719
720fn new_view_object_id() -> StorageBackendResult<[u8; 16]> {
721    new_nonzero_catalog_identity("view", "object identity")
722}
723
724fn new_table_storage_generation() -> StorageBackendResult<[u8; 16]> {
725    new_nonzero_catalog_identity("table", "storage generation")
726}
727
728fn new_sequence_object_id() -> StorageBackendResult<[u8; 16]> {
729    new_nonzero_catalog_identity("sequence", "object identity")
730}
731
732fn new_sequence_definition_generation() -> StorageBackendResult<[u8; 16]> {
733    new_nonzero_catalog_identity("sequence", "definition generation")
734}
735
736fn normalize_analyzer_config_value(value: &mut serde_json::Value) {
737    if let Some(tokenizer) = value.get_mut("tokenizer") {
738        if let Some(name) = tokenizer.as_str() {
739            *tokenizer = serde_json::json!({
740                "type": name.to_ascii_lowercase().replace('-', "_")
741            });
742        }
743    }
744    if let Some(filters) = value
745        .get_mut("token_filters")
746        .and_then(|v| v.as_array_mut())
747    {
748        for filter in filters {
749            if let Some(name) = filter.as_str() {
750                *filter = serde_json::json!({
751                    "type": name.to_ascii_lowercase().replace('-', "_")
752                });
753            }
754        }
755    }
756}
757
758fn parse_analyzer_config(name: &str, config_json: &str) -> std::result::Result<Analyzer, String> {
759    let mut value: serde_json::Value = serde_json::from_str(config_json)
760        .map_err(|e| format!("analyzer `{name}` config is not valid JSON: {e}"))?;
761    normalize_analyzer_config_value(&mut value);
762    let analyzer: Analyzer = serde_json::from_value(value)
763        .map_err(|e| format!("analyzer `{name}` config is not a valid analyzer: {e}"))?;
764    analyzer
765        .validate()
766        .map_err(|e| format!("analyzer `{name}` config is invalid: {e}"))?;
767    Ok(analyzer)
768}
769
770fn normalize_analyzer_phase(phase: &str) -> std::result::Result<(String, AnalyzerPhase), String> {
771    let phase = AnalyzerPhase::parse(&phase.to_ascii_lowercase())?;
772    let normalized = match phase {
773        AnalyzerPhase::Index => "index",
774        AnalyzerPhase::Search => "search",
775        AnalyzerPhase::Both => "both",
776    };
777    Ok((normalized.to_string(), phase))
778}
779
780impl Drop for Engine {
781    fn drop(&mut self) {
782        if self.owns_session_registration {
783            self.session.portals.lock().clear();
784            if let Some(backend) = self.storage.backend.as_ref() {
785                if backend.in_transaction() {
786                    let _ = backend.rollback_transaction();
787                }
788            }
789            for frame in self.session.transactions.lock().iter() {
790                drop(frame.pending_notification_commit.lock().take());
791            }
792            self.row_locks.close_temporary_roles(self.session_id);
793            self.row_locks.release_session(self.session_id);
794            self.notification_hub.unregister(self.session_id);
795            self.release_automatic_statistics_client();
796        }
797    }
798}
799
800fn initial_random_state() -> SessionRandomState {
801    use std::sync::atomic::{AtomicU64, Ordering};
802
803    static NEXT_STATE: AtomicU64 = AtomicU64::new(0x4d59_5df4_d0f3_3173);
804    random_state_from_seed(NEXT_STATE.fetch_add(0x9e37_79b9_7f4a_7c15, Ordering::Relaxed))
805}
806
807fn random_state_from_seed(mut seed: u64) -> SessionRandomState {
808    let mut splitmix64 = || {
809        seed = seed.wrapping_add(0x9e37_79b9_7f4a_7c15);
810        let mut value = seed;
811        value = (value ^ (value >> 30)).wrapping_mul(0xbf58_476d_1ce4_e5b9);
812        value = (value ^ (value >> 27)).wrapping_mul(0x94d0_49bb_1331_11eb);
813        value ^ (value >> 31)
814    };
815    let state = SessionRandomState {
816        s0: splitmix64(),
817        s1: splitmix64(),
818    };
819    if state.s0 == 0 && state.s1 == 0 {
820        SessionRandomState::default()
821    } else {
822        state
823    }
824}
825
826/// Exact signed single-prior hybrid-search arguments. Keeps
827/// [`Engine::hybrid_search`] borrowing-friendly without an explosion of
828/// positional parameters.
829#[derive(Debug, Clone)]
830pub struct HybridSearchParams<'a> {
831    pub table: &'a str,
832    pub text_field: &'a str,
833    pub text_query: &'a str,
834    pub vector_field: &'a str,
835    pub query_vector: Vec<f32>,
836    /// How many KNN candidates to pull from the vector index before
837    /// fusion. Tune above `top_k` to widen the recall pool.
838    pub knn_pool: usize,
839    pub top_k: usize,
840}
841
842/// Explicit robust-ranking variant of [`HybridSearchParams`]. This contract
843/// applies positive-evidence gating and confidence scaling rather than exact
844/// single-prior Bayesian evidence fusion.
845#[derive(Debug, Clone)]
846pub struct RobustHybridSearchParams<'a> {
847    pub table: &'a str,
848    pub text_field: &'a str,
849    pub text_query: &'a str,
850    pub vector_field: &'a str,
851    pub query_vector: Vec<f32>,
852    /// How many KNN candidates to pull from the vector index before
853    /// fusion. Tune above `top_k` to widen the recall pool.
854    pub knn_pool: usize,
855    /// Confidence-scaling exponent for robust positive-evidence pooling.
856    /// Must be finite and in `[0, 1]`.
857    pub alpha: f64,
858    pub top_k: usize,
859}
860
861#[cfg(test)]
862mod tests;
863
864mod copy;
865
866use uqa_execution::catalog::sequence::session::{
867    NontransactionalSequenceValue, SessionLastSequenceReference, SessionSequenceCache,
868    SessionSequenceValue,
869};