Skip to main content

uqa_engine/capabilities/
table_reads.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bind physical scans to the selected table generation.
8
9use crate::TableState;
10use std::sync::atomic::Ordering;
11use uqa_execution::query::table_read::TableRead;
12impl TableRead for TableState {
13    fn column_definitions(&self) -> Vec<uqa_sql::ast::ColumnDef> {
14        self.columns.read().clone()
15    }
16    fn read_documents(
17        &self,
18    ) -> parking_lot::RwLockReadGuard<'_, Box<dyn uqa_storage::DocumentStore>> {
19        self.document_store.read()
20    }
21
22    fn maps_integer_keys(&self) -> bool {
23        self.maps_integer_keys.load(Ordering::Acquire)
24    }
25
26    fn for_each_indexed_fields(
27        &self,
28        ids: &[uqa_core::DocId],
29        fields: &[&str],
30        control: &uqa_storage::read_control::StorageReadControl,
31        visitor: &mut dyn FnMut(uqa_core::DocId, bool, &[&uqa_core::Value]) -> bool,
32    ) -> Result<Option<usize>, uqa_sql::SQLError> {
33        let indexes = self.value_indexes.read();
34        let Some(columns) = fields
35            .iter()
36            .map(|field| indexes.get(&uqa_storage::ValueIndexKey::Column((*field).to_owned())))
37            .collect::<Option<Vec<_>>>()
38        else {
39            return Ok(None);
40        };
41        // Every accelerator indexes every row, so without a field to project any of them tells whether a row exists.
42        let presence = if let Some(column) = columns.first() {
43            *column
44        } else {
45            let Some(index) = indexes.values().next() else {
46                return Ok(None);
47            };
48            index
49        };
50        uqa_execution::catalog::index::value::visit_stored_fields(
51            &columns, presence, ids, control, visitor,
52        )
53        .map(Some)
54    }
55}
56
57use crate::Engine;
58use uqa_execution::query::{
59    table_read::QueryTableAccess,
60    table_sources::{
61        retrieval::{DirectVectorRetrieval, RetrievalAccess},
62        TableRetrievalContext, TableScanContext,
63    },
64};
65use uqa_sql::{SQLError, SQLParam, ScalarExpr};
66impl Engine {
67    pub(crate) fn table_scan_context(&self) -> TableScanContext<'_> {
68        TableScanContext {
69            tables: self,
70            runtime: self.query_runtime_view(),
71        }
72    }
73    pub(crate) fn table_retrieval_context(&self) -> TableRetrievalContext<'_> {
74        TableRetrievalContext {
75            tables: self,
76            retrieval: self,
77        }
78    }
79}
80impl QueryTableAccess for Engine {
81    fn index_read_control(
82        &self,
83    ) -> Result<uqa_storage::read_control::StorageReadControl, SQLError> {
84        self.query_retention_control()
85    }
86
87    fn serializable_read(
88        &self,
89        name: &str,
90    ) -> Result<Option<uqa_execution::serializable::SerializableRelationRead>, SQLError> {
91        self.serializable_table_read(name)
92    }
93
94    fn table(&self, name: &str) -> Result<std::sync::Arc<dyn TableRead>, SQLError> {
95        self.require_query_table(name)
96            .map(|table| table as std::sync::Arc<dyn TableRead>)
97    }
98    fn index_holds_fields(
99        &self,
100        name: &str,
101        table: &std::sync::Arc<dyn TableRead>,
102        fields: &[String],
103    ) -> Result<bool, SQLError> {
104        self.prepare_index_only_read(name, table, fields)
105    }
106    fn table_row_estimate(&self, name: &str) -> Result<u64, SQLError> {
107        self.table_row_estimate(name)
108    }
109}
110impl uqa_execution::query::indexed_filter::QueryIndexRead for Engine {
111    fn visit_value_index(
112        &self,
113        table: &str,
114        field: &str,
115        predicate: &uqa_core::Predicate,
116        visit: &mut dyn FnMut(uqa_core::DocId) -> Result<(), SQLError>,
117    ) -> Result<bool, SQLError> {
118        self.value_index_query_visit(table, field, predicate, visit)
119    }
120
121    fn visit_exact_command_matches(
122        &self,
123        table: &str,
124        field: &str,
125        value: &uqa_core::Value,
126        visit: &mut dyn FnMut(uqa_core::DocId) -> Result<(), SQLError>,
127    ) -> Result<uqa_execution::query::document_changes::DocumentChanges, SQLError> {
128        let table = self.command_overlay_table_name(table)?;
129        uqa_execution::mutation::overlay::CommandMutationOverlay::visit_column_matches_with_catalog(
130            &mut self.session.command_mutation_overlays.lock(),
131            &table,
132            &[field.to_owned()],
133            std::slice::from_ref(value),
134            &self.query_retention_control()?,
135            Some(self),
136            visit,
137        )
138    }
139
140    fn value_index_scan(
141        &self,
142        table: &str,
143        field: &str,
144        predicate: &uqa_core::Predicate,
145    ) -> Result<Option<uqa_core::PostingList>, SQLError> {
146        self.value_index_query_scan(table, field, predicate)
147    }
148
149    fn command_overlay_changes(
150        &self,
151        table: &str,
152    ) -> Result<Option<uqa_execution::query::document_changes::DocumentChanges>, SQLError> {
153        self.command_overlay_changes(table)
154    }
155
156    fn exact_command_matches(
157        &self,
158        table: &str,
159        field: &str,
160        value: &uqa_core::Value,
161    ) -> Result<uqa_execution::mutation::overlay::CommandIndexProbe, SQLError> {
162        let table = self.command_overlay_table_name(table)?;
163        let control = self.query_retention_control()?;
164        uqa_execution::mutation::overlay::CommandMutationOverlay::column_matches_with_catalog(
165            &mut self.session.command_mutation_overlays.lock(),
166            &table,
167            &[field.to_owned()],
168            std::slice::from_ref(value),
169            &control,
170            Some(self),
171        )
172    }
173}
174impl RetrievalAccess for Engine {
175    fn direct_vector_retrieval(
176        &self,
177        predicate: &ScalarExpr,
178        params: &[SQLParam],
179    ) -> Result<Option<DirectVectorRetrieval>, SQLError> {
180        self.retrieval_binding()
181            .direct_vector_retrieval(predicate, params)
182    }
183    fn knn_entries(
184        &self,
185        table: &str,
186        field: &str,
187        query: &[f32],
188        top_k: usize,
189        committed: bool,
190    ) -> Result<Vec<crate::ScoredEntry>, SQLError> {
191        if committed {
192            self.committed_knn_entries(table, field, query, top_k)
193        } else {
194            self.knn_search_leaf(
195                table,
196                field,
197                query,
198                top_k,
199                self.runtime.diagnostics.capture().as_ref(),
200            )
201        }
202    }
203    fn retrieval_entries(
204        &self,
205        table: &str,
206        predicate: &ScalarExpr,
207        params: &[SQLParam],
208        committed: bool,
209    ) -> Result<Option<Vec<crate::ScoredEntry>>, SQLError> {
210        if committed {
211            self.committed_retrieval_entries(table, predicate, params)
212        } else {
213            crate::operator_tree_bridge::run_optimised(self, table, Some(predicate), params)
214        }
215    }
216    fn retrieval_input(
217        &self,
218        table: &str,
219        predicate: &ScalarExpr,
220        params: &[SQLParam],
221        committed: bool,
222    ) -> Result<Option<uqa_execution::query::scored_input::ProducedScoredEntries>, SQLError> {
223        let read = |session: &Engine| {
224            uqa_execution::query::block::where_filter::capture_typed_retrieval(
225                &session.source_execution_context(),
226                table,
227                Some(predicate),
228                params,
229                &crate::capabilities::query_scope::new_for_current_routine(session)?,
230            )
231        };
232        if committed {
233            self.with_committed_retrieval(table, read)
234        } else {
235            read(self)
236        }
237    }
238}
239
240impl uqa_execution::query::block::context::QueryDocumentRead for Engine {
241    fn document_ids(&self, table: &str) -> Result<Vec<uqa_core::DocId>, SQLError> {
242        self.query_table_doc_ids(table)
243    }
244    fn document(
245        &self,
246        table: &str,
247        doc_id: uqa_core::DocId,
248    ) -> Result<Option<uqa_storage::document_store::Document>, SQLError> {
249        self.get_query_document(table, doc_id)
250    }
251    fn document_fields(
252        &self,
253        table: &str,
254        ids: &[uqa_core::DocId],
255        fields: &[&str],
256    ) -> Result<std::collections::BTreeMap<uqa_core::DocId, Vec<uqa_core::Value>>, SQLError> {
257        self.get_query_document_fields_multi(table, ids, fields)
258    }
259    fn column_definitions(
260        &self,
261        table: &str,
262    ) -> Result<Option<Vec<uqa_sql::ast::ColumnDef>>, String> {
263        self.try_describe_query_table(table)
264            .map_err(|error| error.to_string())
265    }
266    fn command_overlay_holds(&self, table: &str) -> Result<bool, SQLError> {
267        self.command_overlay_holds(table)
268    }
269}
270
271use uqa_execution::{
272    serializable::{SerializableRelationRead, SerializableWrites},
273    storage_errors::storage_error,
274};
275use uqa_sql::ast::RelationPersistence;
276
277impl Engine {
278    pub(crate) fn serializable_table_read(
279        &self,
280        table: &str,
281    ) -> Result<Option<SerializableRelationRead>, SQLError> {
282        self.serializable_table_read_using(|| self.require_query_table(table))
283    }
284
285    pub(crate) fn serializable_table_state_read(
286        &self,
287        table: &std::sync::Arc<TableState>,
288    ) -> Result<Option<SerializableRelationRead>, SQLError> {
289        self.serializable_table_read_using(|| Ok(std::sync::Arc::clone(table)))
290    }
291
292    fn serializable_table_read_using(
293        &self,
294        table: impl FnOnce() -> Result<std::sync::Arc<TableState>, SQLError>,
295    ) -> Result<Option<SerializableRelationRead>, SQLError> {
296        let Some(session) = self.serializable_session() else {
297            return Ok(None);
298        };
299        let Some(context) = session
300            .serializable_read_context()
301            .map_err(|error| storage_error("retain serializable reader", &error))?
302        else {
303            return Ok(None);
304        };
305        let table = table()?;
306        Ok(
307            (table.persistence != RelationPersistence::Temporary).then(|| {
308                SerializableRelationRead::new(
309                    table.object_id(),
310                    context,
311                    &self.runtime.cancellation,
312                )
313            }),
314        )
315    }
316}