Skip to main content

uqa_execution/query/
table_read.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Read-only access retained by physical table sources.
8
9use parking_lot::RwLockReadGuard;
10use uqa_core::{DocId, Value};
11use uqa_sql::ast::ColumnDef;
12use uqa_storage::document_store::DocumentStore;
13
14/// A direct table read retains the same identity-checked access-share lock as a SQL source. The caller supplies its selected catalog and data handle; binding and wait revalidation stay in execution.
15pub fn bind_direct_table_read<T>(
16    session: &dyn crate::row_locks::binding::RelationLockSession,
17    resolve: impl FnMut() -> Result<
18        Option<crate::row_locks::binding::RelationBinding<T>>,
19        uqa_sql::SQLError,
20    >,
21) -> Result<Option<crate::row_locks::binding::RelationBinding<T>>, uqa_sql::SQLError> {
22    crate::row_locks::binding::bind_relation(
23        session,
24        crate::row_locks::RelationLockMode::AccessShare,
25        false,
26        resolve,
27        |_| Ok(()),
28    )
29}
30
31/// Only column definitions, shared document reads and the stored values that indexes hold are exposed. A scan cannot mutate catalog state, obtain an engine, or acquire a storage write guard.
32pub trait TableRead: Send + Sync {
33    fn column_definitions(&self) -> Vec<ColumnDef>;
34    fn read_documents(&self) -> RwLockReadGuard<'_, Box<dyn DocumentStore>>;
35    /// Whether the table's single integer primary key, if it has one, names its rows' identities: every row whose key lies below `KEY_IDENTITY_LIMIT` has the identity equal to its key, and no other row has an identity below the limit. A table that does not keep this resolves its keys through the key's index.
36    fn maps_integer_keys(&self) -> bool;
37
38    /// Visit `fields` of the rows `ids` from index entries alone, in `ids` order and as a document store's point projection reports them: each row, whether it exists, and its values when it does, while `visitor` returns true. Returns the rows visited, or `None` without visiting when the indexes do not hold every field. `visitor` runs while the index entries are lent and must not call back into the engine.
39    fn for_each_indexed_fields(
40        &self,
41        ids: &[DocId],
42        fields: &[&str],
43        control: &uqa_storage::read_control::StorageReadControl,
44        visitor: &mut dyn FnMut(DocId, bool, &[&Value]) -> bool,
45    ) -> Result<Option<usize>, uqa_sql::SQLError> {
46        let _ = (ids, fields, control, visitor);
47        Ok(None)
48    }
49}
50
51/// The chosen transaction snapshot supplies a table generation and the command's row overlay separately.
52pub trait QueryTableAccess: super::indexed_filter::QueryIndexRead {
53    fn index_read_control(
54        &self,
55    ) -> Result<uqa_storage::read_control::StorageReadControl, uqa_sql::SQLError>;
56
57    fn serializable_read(
58        &self,
59        name: &str,
60    ) -> Result<Option<crate::serializable::SerializableRelationRead>, uqa_sql::SQLError>;
61
62    fn table(&self, name: &str) -> Result<std::sync::Arc<dyn TableRead>, uqa_sql::SQLError>;
63
64    /// Whether the indexes of `table`, the handle [`Self::table`] returned for `name`, hold `fields` for every row, loading or building what the catalog provides. An index-only read then projects those fields without reading a document.
65    fn index_holds_fields(
66        &self,
67        name: &str,
68        table: &std::sync::Arc<dyn TableRead>,
69        fields: &[String],
70    ) -> Result<bool, uqa_sql::SQLError> {
71        let _ = (name, table, fields);
72        Ok(false)
73    }
74    /// An estimate of the rows a read of the table sees, which costs no work in the number of changes it merges; scans size their output by it.
75    fn table_row_estimate(&self, name: &str) -> Result<u64, uqa_sql::SQLError>;
76}