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 visitor: &mut dyn FnMut(DocId, bool, &[&Value]) -> bool,
44 ) -> Option<usize> {
45 let _ = (ids, fields, visitor);
46 None
47 }
48}
49
50/// The chosen transaction snapshot supplies a table generation and the command's row overlay separately.
51pub trait QueryTableAccess: super::indexed_filter::QueryIndexRead {
52 fn serializable_read(
53 &self,
54 name: &str,
55 ) -> Result<Option<crate::serializable::SerializableRelationRead>, uqa_sql::SQLError>;
56
57 fn table(&self, name: &str) -> Result<std::sync::Arc<dyn TableRead>, uqa_sql::SQLError>;
58
59 /// 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.
60 fn index_holds_fields(
61 &self,
62 name: &str,
63 table: &std::sync::Arc<dyn TableRead>,
64 fields: &[String],
65 ) -> Result<bool, uqa_sql::SQLError> {
66 let _ = (name, table, fields);
67 Ok(false)
68 }
69 /// 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.
70 fn table_row_estimate(&self, name: &str) -> Result<u64, uqa_sql::SQLError>;
71}