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 get_document_fields(
64        &self,
65        table: &str,
66        ids: &[DocId],
67        field: &str,
68    ) -> Result<BTreeMap<DocId, Value>, SQLError> {
69        self.get_document_fields(table, ids, field)
70    }
71}
72
73impl RetrievalSnapshots for Engine {
74    fn snapshot_context(&self, table: &str) -> Result<Option<ExecutionContext>, SQLError> {
75        self.snapshot_context(table)
76    }
77    fn snapshot_context_with_document_store(
78        &self,
79        table: &str,
80        documents: Arc<dyn DocumentStore>,
81    ) -> Result<Option<ExecutionContext>, SQLError> {
82        self.snapshot_context_with_document_store(table, documents)
83    }
84    fn get_documents_with_materialized_projection(
85        &self,
86        table: &str,
87        ids: &[DocId],
88        projection: &[String],
89    ) -> Result<BTreeMap<DocId, Document>, SQLError> {
90        self.get_documents_with_materialized_projection(table, ids, projection)
91    }
92}
93
94impl RetrievalIndexes for Engine {
95    fn query_table_indexes(
96        &self,
97        table: &str,
98    ) -> StorageBackendResult<Option<Box<dyn RetrievalIndexState>>> {
99        Ok(self
100            .try_query_table(table)?
101            .map(|state| Box::new(TableIndexState(state)) as Box<dyn RetrievalIndexState>))
102    }
103    fn table_indexes(
104        &self,
105        table: &str,
106    ) -> StorageBackendResult<Option<Box<dyn RetrievalIndexState>>> {
107        Ok(self
108            .table(table)?
109            .map(|state| Box::new(TableIndexState(state)) as Box<dyn RetrievalIndexState>))
110    }
111    fn catalog_index(&self, name: &str) -> StorageBackendResult<Option<CatalogIndexRow>> {
112        self.catalog_index_in_execution(name)
113    }
114    fn resolve_table_name(&self, table: &str) -> StorageBackendResult<Option<String>> {
115        self.resolve_table_name(table)
116    }
117}
118
119impl PhysicalTextRetrieval for Engine {
120    fn validate_text_search_field(&self, table: &str, field: &str) -> Result<(), SQLError> {
121        self.validate_text_search_field(table, field)
122    }
123    fn fts_fields_for_table(&self, table: &str) -> Result<Vec<String>, SQLError> {
124        self.fts_fields_for_table(table)
125    }
126    fn bayesian_params_for_relation(
127        &self,
128        table: &str,
129        signal_table: &str,
130        field: &str,
131    ) -> Result<uqa_scoring::BayesianBM25Params, SQLError> {
132        self.bayesian_params_for_relation_in_execution(table, signal_table, field)
133    }
134    fn search_leaf(
135        &self,
136        table: &str,
137        field: &str,
138        query: &str,
139        mode: &ScoringMode,
140        limit: usize,
141        top_k: Option<TextTopKPlan>,
142    ) -> Result<Vec<ScoredEntry>, SQLError> {
143        self.search_leaf(table, field, query, mode, limit, top_k)
144    }
145}
146
147impl PhysicalVectorRetrieval for Engine {
148    fn knn_search_leaf(
149        &self,
150        table: &str,
151        field: &str,
152        query: &[f32],
153        k: usize,
154        diagnostics: Option<&uqa_execution::query::diagnostics::CapturedDiagnostics>,
155    ) -> Result<Vec<ScoredEntry>, SQLError> {
156        self.knn_search_leaf(table, field, query, k, diagnostics)
157    }
158}
159
160impl RetrievalGraphs for Engine {
161    fn graph_handle(
162        &self,
163        graph: &str,
164    ) -> Result<Option<Arc<uqa_graph::GraphStoreHandle>>, SQLError> {
165        self.graph_handle_in_execution(graph).map_err(|error| {
166            uqa_execution::storage_errors::storage_error("retain graph reader", &error)
167        })
168    }
169}
170
171impl RetrievalModels for Engine {
172    fn load_model(&self, name: &str) -> Result<Option<uqa_ml::DeepModel>, SQLError> {
173        self.load_model_in_execution(name)
174    }
175}
176
177impl Engine {
178    pub(crate) fn physical_driver_context(&self) -> PhysicalDriverContext<'_> {
179        PhysicalDriverContext {
180            runtime: self.query_runtime_view(),
181            relations: self,
182            snapshots: self,
183            indexes: self,
184            text: self,
185            vector: self,
186            graphs: self,
187            models: self,
188            text_catalog: self,
189            text_functions: self,
190            documents: self,
191            vector_pool: self,
192            functions: self,
193        }
194    }
195    pub(crate) fn physical_retrieval_driver<'a>(
196        &'a self,
197        table: &'a str,
198        signal_table: &'a str,
199        params: &'a [SQLParam],
200    ) -> PhysicalRetrievalDriver<'a> {
201        PhysicalRetrievalDriver::new(self.physical_driver_context(), table, signal_table, params)
202    }
203    pub(crate) fn tree_execution_context(
204        &self,
205    ) -> uqa_execution::operator_tree::runtime::TreeExecutionContext<'_> {
206        uqa_execution::operator_tree::runtime::TreeExecutionContext {
207            driver: self.physical_driver_context(),
208            optimizer: self,
209            transaction: self,
210        }
211    }
212}
213
214impl uqa_execution::operator_tree::runtime::RetrievalPlanOptimizer for Engine {
215    fn optimize(
216        &self,
217        table: &str,
218        tree: &uqa_operators::OperatorTree,
219    ) -> Result<uqa_operators::OperatorTree, SQLError> {
220        Ok(
221            uqa_planner::retrieval_planning::query_optimizer(self, table, tree)?
222                .optimize(tree.clone()),
223        )
224    }
225}
226impl uqa_execution::operator_tree::runtime::RetrievalTransactionState for Engine {
227    fn transaction_depth(&self) -> usize {
228        self.transaction_depth()
229    }
230}