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}