Skip to main content

uqa_engine/capabilities/
physical_retrieval.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bind physical retrieval to retained table generations and active statement state.
8
9use crate::{Engine, ScoringMode, TableState};
10use std::{collections::BTreeMap, sync::Arc};
11use uqa_core::{DocId, ScoredEntry, Value};
12use uqa_execution::operator_tree::driver::{
13    context::{
14        PhysicalDriverContext, PhysicalTextRetrieval, PhysicalVectorRetrieval, RetrievalGraphs,
15        RetrievalIndexState, RetrievalIndexes, RetrievalModels, RetrievalRelations,
16        RetrievalSnapshots, TextIndexRead, VectorIndexRead,
17    },
18    PhysicalRetrievalDriver,
19};
20use uqa_operators::{base::ExecutionContext, TextTopKPlan};
21use uqa_sql::{
22    ast::{ColumnDef, ColumnType},
23    SQLError, SQLParam,
24};
25use uqa_storage::{document_store::Document, CatalogIndexRow, DocumentStore, StorageBackendResult};
26
27struct TableIndexState(Arc<TableState>);
28impl RetrievalIndexState for TableIndexState {
29    fn columns(&self) -> Arc<Vec<ColumnDef>> {
30        self.0.columns.snapshot()
31    }
32    fn inverted_index(&self) -> TextIndexRead<'_> {
33        Box::new(self.0.inverted_index.read())
34    }
35    fn vector_indexes(&self) -> VectorIndexRead<'_> {
36        Box::new(self.0.vector_indexes.read())
37    }
38}
39
40impl RetrievalRelations for Engine {
41    fn serializable_read(
42        &self,
43        table: &str,
44    ) -> Result<Option<uqa_execution::serializable::SerializableRelationRead>, SQLError> {
45        self.serializable_table_read(table)
46    }
47
48    fn try_describe_query_table(
49        &self,
50        table: &str,
51    ) -> StorageBackendResult<Option<Vec<ColumnDef>>> {
52        self.try_describe_query_table(table)
53    }
54    fn has_table(&self, table: &str) -> StorageBackendResult<bool> {
55        self.has_table_in_execution(table)
56    }
57    fn column_type(&self, table: &str, field: &str) -> StorageBackendResult<Option<ColumnType>> {
58        self.column_type(table, field)
59    }
60    fn table_doc_ids(&self, table: &str) -> Result<Vec<DocId>, SQLError> {
61        self.query_table_doc_ids(table)
62    }
63    fn table_doc_id_page(
64        &self,
65        table: &str,
66        after: Option<DocId>,
67        limit: usize,
68        control: &uqa_storage::read_control::StorageReadControl,
69    ) -> Result<uqa_core::memory::BudgetedVec<DocId>, SQLError> {
70        uqa_execution::mutation::constraints::context::MutationRead::table_doc_id_page(
71            self, table, after, limit, control,
72        )
73    }
74    fn get_document_fields(
75        &self,
76        table: &str,
77        ids: &[DocId],
78        field: &str,
79    ) -> Result<BTreeMap<DocId, Value>, SQLError> {
80        self.get_document_fields(table, ids, field)
81    }
82    fn capture_document_filter(
83        &self,
84        table: &str,
85        ids: &uqa_execution::query::SelectedIds,
86        field: &str,
87        predicate: &uqa_core::Predicate,
88        bytes: usize,
89        cancellation: &uqa_core::CancellationToken,
90    ) -> Result<uqa_execution::query::scored_input::CapturedScoredEntries, SQLError> {
91        let state = self.require_query_table(table)?;
92        let columns = state.columns.snapshot();
93        let changes = self.command_overlay_changes(table)?;
94        let documents = state.document_store.read();
95        uqa_execution::query::document_projection::FilterProjection {
96            source: documents.as_ref(),
97            changes: changes.as_ref(),
98            definitions: &columns,
99        }
100        .capture(table, ids, field, predicate, bytes, cancellation)
101    }
102}
103
104impl RetrievalSnapshots for Engine {
105    fn snapshot_context(&self, table: &str) -> Result<Option<ExecutionContext>, SQLError> {
106        self.snapshot_context(table)
107    }
108    fn snapshot_context_for_scores(
109        &self,
110        table: &str,
111    ) -> Result<Option<ExecutionContext>, SQLError> {
112        self.snapshot_context_for_scores(table)
113    }
114    fn snapshot_context_with_document_store(
115        &self,
116        table: &str,
117        documents: Arc<dyn DocumentStore>,
118    ) -> Result<Option<ExecutionContext>, SQLError> {
119        self.snapshot_context_with_document_store(table, documents)
120    }
121    fn get_documents_with_materialized_projection(
122        &self,
123        table: &str,
124        ids: &[DocId],
125        projection: &[String],
126    ) -> Result<BTreeMap<DocId, Document>, SQLError> {
127        self.get_documents_with_materialized_projection(table, ids, projection)
128    }
129}
130
131impl RetrievalIndexes for Engine {
132    fn query_table_indexes(
133        &self,
134        table: &str,
135    ) -> StorageBackendResult<Option<Box<dyn RetrievalIndexState>>> {
136        Ok(self
137            .try_query_table(table)?
138            .map(|state| Box::new(TableIndexState(state)) as Box<dyn RetrievalIndexState>))
139    }
140    fn table_indexes(
141        &self,
142        table: &str,
143    ) -> StorageBackendResult<Option<Box<dyn RetrievalIndexState>>> {
144        Ok(self
145            .table(table)?
146            .map(|state| Box::new(TableIndexState(state)) as Box<dyn RetrievalIndexState>))
147    }
148    fn catalog_index(&self, name: &str) -> StorageBackendResult<Option<CatalogIndexRow>> {
149        self.catalog_index_in_execution(name)
150    }
151    fn resolve_table_name(&self, table: &str) -> StorageBackendResult<Option<String>> {
152        self.resolve_table_name(table)
153    }
154}
155
156impl PhysicalTextRetrieval for Engine {
157    fn validate_text_search_field(&self, table: &str, field: &str) -> Result<(), SQLError> {
158        self.validate_text_search_field(table, field)
159    }
160    fn fts_fields_for_table(&self, table: &str) -> Result<Vec<String>, SQLError> {
161        self.fts_fields_for_table(table)
162    }
163    fn bayesian_params_for_relation(
164        &self,
165        table: &str,
166        signal_table: &str,
167        field: &str,
168    ) -> Result<uqa_scoring::BayesianBM25Params, SQLError> {
169        self.bayesian_params_for_relation_in_execution(table, signal_table, field)
170    }
171    fn search_leaf(
172        &self,
173        table: &str,
174        field: &str,
175        query: &str,
176        mode: &ScoringMode,
177        limit: usize,
178        top_k: Option<TextTopKPlan>,
179    ) -> Result<Vec<ScoredEntry>, SQLError> {
180        self.search_leaf(table, field, query, mode, limit, top_k)
181    }
182
183    fn visit_search_leaf(
184        &self,
185        table: &str,
186        field: &str,
187        query: &str,
188        mode: &ScoringMode,
189        visitor: &mut dyn FnMut(ScoredEntry) -> Result<(), SQLError>,
190    ) -> Result<(), SQLError> {
191        self.visit_search_leaf(table, field, query, mode, visitor)
192    }
193}
194
195impl PhysicalVectorRetrieval for Engine {
196    fn knn_search_leaf(
197        &self,
198        table: &str,
199        field: &str,
200        query: &[f32],
201        k: usize,
202        diagnostics: Option<&uqa_execution::query::diagnostics::CapturedDiagnostics>,
203    ) -> Result<Vec<ScoredEntry>, SQLError> {
204        self.knn_search_leaf(table, field, query, k, diagnostics)
205    }
206}
207
208impl RetrievalGraphs for Engine {
209    fn graph_handle(
210        &self,
211        graph: &str,
212    ) -> Result<Option<Arc<uqa_graph::GraphStoreHandle>>, SQLError> {
213        self.graph_handle_in_execution(graph).map_err(|error| {
214            uqa_execution::storage_errors::storage_error("retain graph reader", &error)
215        })
216    }
217}
218
219impl RetrievalModels for Engine {
220    fn load_model(&self, name: &str) -> Result<Option<uqa_ml::DeepModel>, SQLError> {
221        self.load_model_in_execution(name)
222    }
223}
224
225impl Engine {
226    pub(crate) fn physical_driver_context(&self) -> PhysicalDriverContext<'_> {
227        PhysicalDriverContext {
228            runtime: self.query_runtime_view(),
229            parallel: &self.extensions.parallel,
230            relations: self,
231            snapshots: self,
232            indexes: self,
233            text: self,
234            vector: self,
235            graphs: self,
236            models: self,
237            text_catalog: self,
238            text_functions: self,
239            documents: self,
240            vector_pool: self,
241            functions: self,
242        }
243    }
244    pub(crate) fn physical_retrieval_driver<'a>(
245        &'a self,
246        table: &'a str,
247        signal_table: &'a str,
248        params: &'a [SQLParam],
249    ) -> PhysicalRetrievalDriver<'a> {
250        PhysicalRetrievalDriver::new(self.physical_driver_context(), table, signal_table, params)
251    }
252    pub(crate) fn tree_execution_context(
253        &self,
254    ) -> uqa_execution::operator_tree::runtime::TreeExecutionContext<'_> {
255        uqa_execution::operator_tree::runtime::TreeExecutionContext {
256            driver: self.physical_driver_context(),
257            optimizer: self,
258            transaction: self,
259        }
260    }
261}
262
263impl uqa_execution::operator_tree::runtime::RetrievalPlanOptimizer for Engine {
264    fn optimize(
265        &self,
266        table: &str,
267        tree: &uqa_operators::OperatorTree,
268    ) -> Result<uqa_operators::OperatorTree, SQLError> {
269        Ok(
270            uqa_planner::retrieval_planning::query_optimizer(self, table, tree)?
271                .optimize(tree.clone()),
272        )
273    }
274}
275impl uqa_execution::operator_tree::runtime::RetrievalTransactionState for Engine {
276    fn transaction_depth(&self) -> usize {
277        self.transaction_depth()
278    }
279}