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        visitor: &mut dyn FnMut(uqa_core::DocId, bool, &[&uqa_core::Value]) -> bool,
31    ) -> Option<usize> {
32        let indexes = self.value_indexes.read();
33        let columns = fields
34            .iter()
35            .map(|field| indexes.get(&uqa_storage::ValueIndexKey::Column((*field).to_owned())))
36            .collect::<Option<Vec<_>>>()?;
37        // Every accelerator indexes every row, so without a field to project any of them tells whether a row exists.
38        let presence = match columns.first() {
39            Some(column) => *column,
40            None => indexes.values().next()?,
41        };
42        let mut values = Vec::with_capacity(columns.len());
43        let mut visited = 0;
44        for &id in ids {
45            values.clear();
46            values.extend(columns.iter().map_while(|column| column.stored_value(id)));
47            let exists = values.len() == columns.len() && presence.contains(id);
48            if !exists {
49                values.clear();
50            }
51            visited += 1;
52            if !visitor(id, exists, &values) {
53                break;
54            }
55        }
56        Some(visited)
57    }
58}
59
60use crate::Engine;
61use uqa_execution::query::{
62    table_read::QueryTableAccess,
63    table_sources::{
64        retrieval::{DirectVectorRetrieval, RetrievalAccess},
65        TableRetrievalContext, TableScanContext,
66    },
67};
68use uqa_sql::{SQLError, SQLParam, ScalarExpr};
69impl Engine {
70    pub(crate) fn table_scan_context(&self) -> TableScanContext<'_> {
71        TableScanContext {
72            tables: self,
73            runtime: self.query_runtime_view(),
74        }
75    }
76    pub(crate) fn table_retrieval_context(&self) -> TableRetrievalContext<'_> {
77        TableRetrievalContext {
78            tables: self,
79            retrieval: self,
80        }
81    }
82}
83impl QueryTableAccess for Engine {
84    fn serializable_read(
85        &self,
86        name: &str,
87    ) -> Result<Option<uqa_execution::serializable::SerializableRelationRead>, SQLError> {
88        self.serializable_table_read(name)
89    }
90
91    fn table(&self, name: &str) -> Result<std::sync::Arc<dyn TableRead>, SQLError> {
92        self.require_query_table(name)
93            .map(|table| table as std::sync::Arc<dyn TableRead>)
94    }
95    fn index_holds_fields(
96        &self,
97        name: &str,
98        table: &std::sync::Arc<dyn TableRead>,
99        fields: &[String],
100    ) -> Result<bool, SQLError> {
101        self.prepare_index_only_read(name, table, fields)
102    }
103    fn table_row_estimate(&self, name: &str) -> Result<u64, SQLError> {
104        self.table_row_estimate(name)
105    }
106}
107impl uqa_execution::query::indexed_filter::QueryIndexRead for Engine {
108    fn value_index_scan(
109        &self,
110        table: &str,
111        field: &str,
112        predicate: &uqa_core::Predicate,
113    ) -> Result<Option<uqa_core::PostingList>, SQLError> {
114        self.value_index_query_scan(table, field, predicate)
115    }
116
117    fn command_overlay_changes(
118        &self,
119        table: &str,
120    ) -> Result<Option<uqa_execution::query::document_changes::DocumentChanges>, SQLError> {
121        self.command_overlay_changes(table)
122    }
123
124    fn exact_command_matches(
125        &self,
126        table: &str,
127        field: &str,
128        value: &uqa_core::Value,
129    ) -> Result<uqa_execution::mutation::overlay::CommandIndexProbe, SQLError> {
130        let table = self.command_overlay_table_name(table)?;
131        let control = self.query_retention_control()?;
132        uqa_execution::mutation::overlay::CommandMutationOverlay::column_matches_with_catalog(
133            &mut self.session.command_mutation_overlays.lock(),
134            &table,
135            &[field.to_owned()],
136            std::slice::from_ref(value),
137            &control,
138            Some(self),
139        )
140    }
141}
142impl RetrievalAccess for Engine {
143    fn direct_vector_retrieval(
144        &self,
145        predicate: &ScalarExpr,
146        params: &[SQLParam],
147    ) -> Result<Option<DirectVectorRetrieval>, SQLError> {
148        self.retrieval_binding()
149            .direct_vector_retrieval(predicate, params)
150    }
151    fn knn_entries(
152        &self,
153        table: &str,
154        field: &str,
155        query: &[f32],
156        top_k: usize,
157        committed: bool,
158    ) -> Result<Vec<crate::ScoredEntry>, SQLError> {
159        if committed {
160            self.committed_knn_entries(table, field, query, top_k)
161        } else {
162            self.knn_search_leaf(
163                table,
164                field,
165                query,
166                top_k,
167                self.runtime.diagnostics.capture().as_ref(),
168            )
169        }
170    }
171    fn retrieval_entries(
172        &self,
173        table: &str,
174        predicate: &ScalarExpr,
175        params: &[SQLParam],
176        committed: bool,
177    ) -> Result<Option<Vec<crate::ScoredEntry>>, SQLError> {
178        if committed {
179            self.committed_retrieval_entries(table, predicate, params)
180        } else {
181            crate::operator_tree_bridge::run_optimised(self, table, Some(predicate), params)
182        }
183    }
184}
185
186impl uqa_execution::query::block::context::QueryDocumentRead for Engine {
187    fn document_ids(&self, table: &str) -> Result<Vec<uqa_core::DocId>, SQLError> {
188        self.query_table_doc_ids(table)
189    }
190    fn document(
191        &self,
192        table: &str,
193        doc_id: uqa_core::DocId,
194    ) -> Result<Option<uqa_storage::document_store::Document>, SQLError> {
195        self.get_query_document(table, doc_id)
196    }
197    fn document_fields(
198        &self,
199        table: &str,
200        ids: &[uqa_core::DocId],
201        fields: &[&str],
202    ) -> Result<std::collections::BTreeMap<uqa_core::DocId, Vec<uqa_core::Value>>, SQLError> {
203        self.get_query_document_fields_multi(table, ids, fields)
204    }
205    fn column_definitions(
206        &self,
207        table: &str,
208    ) -> Result<Option<Vec<uqa_sql::ast::ColumnDef>>, String> {
209        self.try_describe_query_table(table)
210            .map_err(|error| error.to_string())
211    }
212    fn command_overlay_holds(&self, table: &str) -> Result<bool, SQLError> {
213        self.command_overlay_holds(table)
214    }
215}
216
217use uqa_execution::{
218    serializable::{SerializableRelationRead, SerializableWrites},
219    storage_errors::storage_error,
220};
221use uqa_sql::ast::RelationPersistence;
222
223impl Engine {
224    pub(crate) fn serializable_table_read(
225        &self,
226        table: &str,
227    ) -> Result<Option<SerializableRelationRead>, SQLError> {
228        self.serializable_table_read_using(|| self.require_query_table(table))
229    }
230
231    pub(crate) fn serializable_table_state_read(
232        &self,
233        table: &std::sync::Arc<TableState>,
234    ) -> Result<Option<SerializableRelationRead>, SQLError> {
235        self.serializable_table_read_using(|| Ok(std::sync::Arc::clone(table)))
236    }
237
238    fn serializable_table_read_using(
239        &self,
240        table: impl FnOnce() -> Result<std::sync::Arc<TableState>, SQLError>,
241    ) -> Result<Option<SerializableRelationRead>, SQLError> {
242        let Some(session) = self.serializable_session() else {
243            return Ok(None);
244        };
245        let Some(context) = session
246            .serializable_read_context()
247            .map_err(|error| storage_error("retain serializable reader", &error))?
248        else {
249            return Ok(None);
250        };
251        let table = table()?;
252        Ok(
253            (table.persistence != RelationPersistence::Temporary).then(|| {
254                SerializableRelationRead::new(
255                    table.object_id(),
256                    context,
257                    &self.runtime.cancellation,
258                )
259            }),
260        )
261    }
262}