uqa-engine 0.6.2

Engine: schema-aware table store, catalog restore, transactions
Documentation
//
// Unified Query Algebra
//
// Copyright (c) 2023-2026 Cognica, Inc.
//

//! Bind physical scans to the selected table generation.

use crate::TableState;
use std::sync::atomic::Ordering;
use uqa_execution::query::table_read::TableRead;
impl TableRead for TableState {
    fn column_definitions(&self) -> Vec<uqa_sql::ast::ColumnDef> {
        self.columns.read().clone()
    }
    fn read_documents(
        &self,
    ) -> parking_lot::RwLockReadGuard<'_, Box<dyn uqa_storage::DocumentStore>> {
        self.document_store.read()
    }

    fn maps_integer_keys(&self) -> bool {
        self.maps_integer_keys.load(Ordering::Acquire)
    }

    fn for_each_indexed_fields(
        &self,
        ids: &[uqa_core::DocId],
        fields: &[&str],
        control: &uqa_storage::read_control::StorageReadControl,
        visitor: &mut dyn FnMut(uqa_core::DocId, bool, &[&uqa_core::Value]) -> bool,
    ) -> Result<Option<usize>, uqa_sql::SQLError> {
        let indexes = self.value_indexes.read();
        let Some(columns) = fields
            .iter()
            .map(|field| indexes.get(&uqa_storage::ValueIndexKey::Column((*field).to_owned())))
            .collect::<Option<Vec<_>>>()
        else {
            return Ok(None);
        };
        // Every accelerator indexes every row, so without a field to project any of them tells whether a row exists.
        let presence = if let Some(column) = columns.first() {
            *column
        } else {
            let Some(index) = indexes.values().next() else {
                return Ok(None);
            };
            index
        };
        uqa_execution::catalog::index::value::visit_stored_fields(
            &columns, presence, ids, control, visitor,
        )
        .map(Some)
    }
}

use crate::Engine;
use uqa_execution::query::{
    table_read::QueryTableAccess,
    table_sources::{
        retrieval::{DirectVectorRetrieval, RetrievalAccess},
        TableRetrievalContext, TableScanContext,
    },
};
use uqa_sql::{SQLError, SQLParam, ScalarExpr};
impl Engine {
    pub(crate) fn table_scan_context(&self) -> TableScanContext<'_> {
        TableScanContext {
            tables: self,
            runtime: self.query_runtime_view(),
        }
    }
    pub(crate) fn table_retrieval_context(&self) -> TableRetrievalContext<'_> {
        TableRetrievalContext {
            tables: self,
            retrieval: self,
        }
    }
}
impl QueryTableAccess for Engine {
    fn index_read_control(
        &self,
    ) -> Result<uqa_storage::read_control::StorageReadControl, SQLError> {
        self.query_retention_control()
    }

    fn serializable_read(
        &self,
        name: &str,
    ) -> Result<Option<uqa_execution::serializable::SerializableRelationRead>, SQLError> {
        self.serializable_table_read(name)
    }

    fn table(&self, name: &str) -> Result<std::sync::Arc<dyn TableRead>, SQLError> {
        self.require_query_table(name)
            .map(|table| table as std::sync::Arc<dyn TableRead>)
    }
    fn index_holds_fields(
        &self,
        name: &str,
        table: &std::sync::Arc<dyn TableRead>,
        fields: &[String],
    ) -> Result<bool, SQLError> {
        self.prepare_index_only_read(name, table, fields)
    }
    fn table_row_estimate(&self, name: &str) -> Result<u64, SQLError> {
        self.table_row_estimate(name)
    }
}
impl uqa_execution::query::indexed_filter::QueryIndexRead for Engine {
    fn visit_value_index(
        &self,
        table: &str,
        field: &str,
        predicate: &uqa_core::Predicate,
        visit: &mut dyn FnMut(uqa_core::DocId) -> Result<(), SQLError>,
    ) -> Result<bool, SQLError> {
        self.value_index_query_visit(table, field, predicate, visit)
    }

    fn visit_exact_command_matches(
        &self,
        table: &str,
        field: &str,
        value: &uqa_core::Value,
        visit: &mut dyn FnMut(uqa_core::DocId) -> Result<(), SQLError>,
    ) -> Result<uqa_execution::query::document_changes::DocumentChanges, SQLError> {
        let table = self.command_overlay_table_name(table)?;
        uqa_execution::mutation::overlay::CommandMutationOverlay::visit_column_matches_with_catalog(
            &mut self.session.command_mutation_overlays.lock(),
            &table,
            &[field.to_owned()],
            std::slice::from_ref(value),
            &self.query_retention_control()?,
            Some(self),
            visit,
        )
    }

    fn value_index_scan(
        &self,
        table: &str,
        field: &str,
        predicate: &uqa_core::Predicate,
    ) -> Result<Option<uqa_core::PostingList>, SQLError> {
        self.value_index_query_scan(table, field, predicate)
    }

    fn command_overlay_changes(
        &self,
        table: &str,
    ) -> Result<Option<uqa_execution::query::document_changes::DocumentChanges>, SQLError> {
        self.command_overlay_changes(table)
    }

    fn exact_command_matches(
        &self,
        table: &str,
        field: &str,
        value: &uqa_core::Value,
    ) -> Result<uqa_execution::mutation::overlay::CommandIndexProbe, SQLError> {
        let table = self.command_overlay_table_name(table)?;
        let control = self.query_retention_control()?;
        uqa_execution::mutation::overlay::CommandMutationOverlay::column_matches_with_catalog(
            &mut self.session.command_mutation_overlays.lock(),
            &table,
            &[field.to_owned()],
            std::slice::from_ref(value),
            &control,
            Some(self),
        )
    }
}
impl RetrievalAccess for Engine {
    fn direct_vector_retrieval(
        &self,
        predicate: &ScalarExpr,
        params: &[SQLParam],
    ) -> Result<Option<DirectVectorRetrieval>, SQLError> {
        self.retrieval_binding()
            .direct_vector_retrieval(predicate, params)
    }
    fn knn_entries(
        &self,
        table: &str,
        field: &str,
        query: &[f32],
        top_k: usize,
        committed: bool,
    ) -> Result<Vec<crate::ScoredEntry>, SQLError> {
        if committed {
            self.committed_knn_entries(table, field, query, top_k)
        } else {
            self.knn_search_leaf(
                table,
                field,
                query,
                top_k,
                self.runtime.diagnostics.capture().as_ref(),
            )
        }
    }
    fn retrieval_entries(
        &self,
        table: &str,
        predicate: &ScalarExpr,
        params: &[SQLParam],
        committed: bool,
    ) -> Result<Option<Vec<crate::ScoredEntry>>, SQLError> {
        if committed {
            self.committed_retrieval_entries(table, predicate, params)
        } else {
            crate::operator_tree_bridge::run_optimised(self, table, Some(predicate), params)
        }
    }
    fn retrieval_input(
        &self,
        table: &str,
        predicate: &ScalarExpr,
        params: &[SQLParam],
        committed: bool,
    ) -> Result<Option<uqa_execution::query::scored_input::ProducedScoredEntries>, SQLError> {
        let read = |session: &Engine| {
            uqa_execution::query::block::where_filter::capture_typed_retrieval(
                &session.source_execution_context(),
                table,
                Some(predicate),
                params,
                &crate::capabilities::query_scope::new_for_current_routine(session),
            )
        };
        if committed {
            self.with_committed_retrieval(table, read)
        } else {
            read(self)
        }
    }
}

impl uqa_execution::query::block::context::QueryDocumentRead for Engine {
    fn document_ids(&self, table: &str) -> Result<Vec<uqa_core::DocId>, SQLError> {
        self.query_table_doc_ids(table)
    }
    fn document(
        &self,
        table: &str,
        doc_id: uqa_core::DocId,
    ) -> Result<Option<uqa_storage::document_store::Document>, SQLError> {
        self.get_query_document(table, doc_id)
    }
    fn document_fields(
        &self,
        table: &str,
        ids: &[uqa_core::DocId],
        fields: &[&str],
    ) -> Result<std::collections::BTreeMap<uqa_core::DocId, Vec<uqa_core::Value>>, SQLError> {
        self.get_query_document_fields_multi(table, ids, fields)
    }
    fn column_definitions(
        &self,
        table: &str,
    ) -> Result<Option<Vec<uqa_sql::ast::ColumnDef>>, String> {
        self.try_describe_query_table(table)
            .map_err(|error| error.to_string())
    }
    fn command_overlay_holds(&self, table: &str) -> Result<bool, SQLError> {
        self.command_overlay_holds(table)
    }
}

use uqa_execution::{
    serializable::{SerializableRelationRead, SerializableWrites},
    storage_errors::storage_error,
};
use uqa_sql::ast::RelationPersistence;

impl Engine {
    pub(crate) fn serializable_table_read(
        &self,
        table: &str,
    ) -> Result<Option<SerializableRelationRead>, SQLError> {
        self.serializable_table_read_using(|| self.require_query_table(table))
    }

    pub(crate) fn serializable_table_state_read(
        &self,
        table: &std::sync::Arc<TableState>,
    ) -> Result<Option<SerializableRelationRead>, SQLError> {
        self.serializable_table_read_using(|| Ok(std::sync::Arc::clone(table)))
    }

    fn serializable_table_read_using(
        &self,
        table: impl FnOnce() -> Result<std::sync::Arc<TableState>, SQLError>,
    ) -> Result<Option<SerializableRelationRead>, SQLError> {
        let Some(session) = self.serializable_session() else {
            return Ok(None);
        };
        let Some(context) = session
            .serializable_read_context()
            .map_err(|error| storage_error("retain serializable reader", &error))?
        else {
            return Ok(None);
        };
        let table = table()?;
        Ok(
            (table.persistence != RelationPersistence::Temporary).then(|| {
                SerializableRelationRead::new(
                    table.object_id(),
                    context,
                    &self.runtime.cancellation,
                )
            }),
        )
    }
}