Skip to main content

uqa_engine/table_storage/
reads.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bind public table queries to their transaction and retain unscoped execution and mutation views.
8
9use uqa_execution::query::document_changes::DocumentChanges;
10
11use crate::{Engine, TableState};
12use std::sync::Arc;
13use uqa_sql::SQLError;
14use uqa_storage::{document_store::Document, InvertedIndex};
15
16impl Engine {
17    pub(crate) fn with_direct_table_read<R>(
18        &self,
19        name: &str,
20        read: impl FnOnce(&Self, &str, &Arc<TableState>) -> Result<R, SQLError>,
21    ) -> Result<R, SQLError> {
22        self.with_direct_table_query(name, true, read)
23    }
24
25    pub(crate) fn with_direct_table_query<R>(
26        &self,
27        name: &str,
28        read_only: bool,
29        query: impl FnOnce(&Self, &str, &Arc<TableState>) -> Result<R, SQLError>,
30    ) -> Result<R, SQLError> {
31        self.with_direct_query_snapshot(
32            read_only,
33            |engine| {
34                let binding = engine.bind_query_table_read(name)?;
35                query(engine, &binding.name, &binding.value)
36            },
37            std::convert::identity,
38        )
39    }
40
41    /// Bind retained table state and its relation lock within the caller's existing statement.
42    pub(crate) fn bind_query_table_read(
43        &self,
44        name: &str,
45    ) -> Result<uqa_execution::row_locks::binding::RelationBinding<Arc<TableState>>, SQLError> {
46        let resolve = || {
47            let Some(name) = self.try_resolve_query_table_name(name).map_err(|error| {
48                uqa_execution::storage_errors::storage_error("resolve direct read table", &error)
49            })?
50            else {
51                return Ok(None);
52            };
53            let table = self.require_query_table(&name)?;
54            Ok(Some(uqa_execution::row_locks::binding::RelationBinding {
55                name,
56                object_id: Some(table.object_id()),
57                value: table,
58            }))
59        };
60        // Attached physical readers already retain their source view and have no logical frame whose locks this call could own.
61        let binding = if self.query_table_snapshots.is_some() || self.transaction_depth() == 0 {
62            resolve()?
63        } else {
64            uqa_execution::query::table_read::bind_direct_table_read(self, resolve)?
65        };
66        binding.ok_or_else(|| SQLError::UnknownTable(name.to_string()))
67    }
68
69    pub fn get_document(
70        &self,
71        table: &str,
72        doc_id: uqa_core::DocId,
73    ) -> Result<Option<Document>, SQLError> {
74        self.with_direct_table_read(table, |engine, name, table| {
75            if let Some(read) = engine.serializable_table_state_read(table)? {
76                read.observe_row(doc_id)?;
77            }
78            engine.materialized_document_from_state(name, table, doc_id)
79        })
80    }
81
82    pub(crate) fn get_live_document(
83        &self,
84        table: &str,
85        doc_id: uqa_core::DocId,
86    ) -> Result<Option<Document>, SQLError> {
87        let state = self.require_table(table)?;
88        self.materialized_document_from_state(table, &state, doc_id)
89    }
90
91    pub(crate) fn get_raw_live_document(
92        &self,
93        table: &str,
94        doc_id: uqa_core::DocId,
95    ) -> Result<Option<Document>, SQLError> {
96        let state = self.require_table(table)?;
97        self.raw_command_visible_document(table, &state, doc_id)
98            .map(|document| document.map(uqa_storage::StoredDocument::into_fields))
99    }
100
101    pub(crate) fn get_query_document(
102        &self,
103        table: &str,
104        doc_id: uqa_core::DocId,
105    ) -> Result<Option<Document>, SQLError> {
106        let state = self.require_query_table(table)?;
107        self.materialized_document_from_state(table, &state, doc_id)
108    }
109
110    fn materialized_document_from_state(
111        &self,
112        name: &str,
113        table: &TableState,
114        doc_id: uqa_core::DocId,
115    ) -> Result<Option<Document>, SQLError> {
116        let mut document = self.raw_command_visible_document(name, table, doc_id)?;
117        if let Some(document) = document.as_mut() {
118            Self::materialize_query_document(&table.columns.read(), document)?;
119        }
120        Ok(document.map(uqa_storage::StoredDocument::into_fields))
121    }
122
123    /// Count documents retained by the table's text index in the selected transaction view.
124    pub fn document_count(&self, table: &str) -> Result<u64, SQLError> {
125        self.with_direct_table_read(table, |engine, _, table| {
126            let index = table.inverted_index.read();
127            let index = uqa_execution::serializable::text::ObservedTextIndex::new(
128                index.as_ref(),
129                engine.serializable_table_state_read(table)?,
130                table.columns.snapshot(),
131            );
132            index.doc_count().map_err(|error| {
133                uqa_execution::storage_errors::storage_error("read indexed document count", &error)
134            })
135        })
136    }
137
138    /// All document ids in the caller's selected transaction view.
139    pub fn table_doc_ids(&self, table: &str) -> Result<Vec<uqa_core::DocId>, SQLError> {
140        self.with_direct_table_read(table, |engine, name, table| {
141            if let Some(read) = engine.serializable_table_state_read(table)? {
142                read.observe_scan()?;
143            }
144            engine.table_doc_ids_from_state(name, table)
145        })
146    }
147
148    pub(crate) fn query_table_doc_ids(
149        &self,
150        table: &str,
151    ) -> Result<Vec<uqa_core::DocId>, SQLError> {
152        let Some(t) = self
153            .try_query_table(table)
154            .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
155        else {
156            return Err(SQLError::UnknownTable(table.to_string()));
157        };
158        self.table_doc_ids_from_state(table, &t)
159    }
160
161    /// All current document ids for schema mutation and validation. Unlike the SELECT-facing path, DDL must inspect rows committed after a fixed transaction snapshot was acquired.
162    pub(crate) fn live_table_doc_ids(&self, table: &str) -> Result<Vec<uqa_core::DocId>, SQLError> {
163        let Some(t) = self.try_table(table).map_err(|error| {
164            SQLError::Internal(format!("resolve live table `{table}`: {error}"))
165        })?
166        else {
167            return Err(SQLError::UnknownTable(table.to_string()));
168        };
169        self.table_doc_ids_from_state(table, &t)
170    }
171
172    fn table_doc_ids_from_state(
173        &self,
174        table: &str,
175        state: &crate::TableState,
176    ) -> Result<Vec<uqa_core::DocId>, SQLError> {
177        let doc_ids = state
178            .document_store
179            .read()
180            .doc_ids()
181            .map_err(|error| SQLError::Internal(format!("read document ids: {error}")))?;
182        let Some(changes) = self.command_overlay_changes(table)? else {
183            return Ok(doc_ids);
184        };
185        let mut visible = doc_ids
186            .into_iter()
187            .collect::<std::collections::BTreeSet<_>>();
188        for change in changes.changes() {
189            let (doc_id, present) = change.map_err(|error| {
190                SQLError::Internal(format!("read command-visible ids: {error}"))
191            })?;
192            if present {
193                visible.insert(doc_id);
194            } else {
195                visible.remove(&doc_id);
196            }
197        }
198        Ok(visible.into_iter().collect())
199    }
200
201    /// An estimate of the rows a read of `table` sees: the rows of the table the read selects, and each row the running commands staged for it as if it added one. Unlike [`Self::table_doc_count`] it reads no changed row, so its cost does not grow with the changes a read merges.
202    pub(crate) fn table_row_estimate(&self, table: &str) -> Result<u64, SQLError> {
203        let Some(t) = self
204            .try_query_table(table)
205            .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
206        else {
207            return Err(SQLError::UnknownTable(table.to_string()));
208        };
209        let stored = t.stored_document_count()?;
210        Ok(stored.saturating_add(self.command_overlay_row_bound(table)?))
211    }
212
213    pub(crate) fn table_doc_count(&self, table: &str) -> Result<u64, SQLError> {
214        let Some(t) = self
215            .try_query_table(table)
216            .map_err(|error| SQLError::Internal(format!("resolve table `{table}`: {error}")))?
217        else {
218            return Err(SQLError::UnknownTable(table.to_string()));
219        };
220        let mut count = t.stored_document_count()?;
221        let Some(changes) = self
222            .command_overlay_changes(table)?
223            .filter(DocumentChanges::has_changes)
224        else {
225            return Ok(count);
226        };
227        let store = t.document_store.read();
228        for change in changes.changes() {
229            let (doc_id, present) = change.map_err(|error| {
230                SQLError::Internal(format!("read command-visible document count: {error}"))
231            })?;
232            let persisted = store.contains_doc_id(doc_id).map_err(|error| {
233                SQLError::Internal(format!("read command-visible document count: {error}"))
234            })?;
235            match (persisted, present) {
236                (false, true) => {
237                    count = count
238                        .checked_add(1)
239                        .ok_or_else(|| SQLError::Internal("document count exceeds u64".into()))?;
240                }
241                (true, false) => {
242                    count = count
243                        .checked_sub(1)
244                        .ok_or_else(|| SQLError::Internal("document count underflow".into()))?;
245                }
246                _ => {}
247            }
248        }
249        Ok(count)
250    }
251}