Skip to main content

uqa_engine/capabilities/
retrieval_planning.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Supply retained table/index guards and graph snapshots to the retrieval planner.
8
9use crate::{Engine, TableState};
10use parking_lot::RwLockReadGuard;
11use std::sync::Arc;
12use uqa_core::{catalog_index::CatalogIndexSnapshot, Predicate};
13use uqa_planner::{
14    retrieval_planning::{
15        GraphStatisticsSnapshot, RetrievalPlanningCatalog, RetrievalStatisticsTable,
16        TextStatisticsRead, VectorStatisticsRead,
17    },
18    ColumnStatistics,
19};
20use uqa_sql::SQLError;
21use uqa_storage::{read_control::StorageReadControl, InvertedIndex};
22
23struct TableStatistics(Arc<TableState>, StorageReadControl);
24struct TextRead<'a>(
25    RwLockReadGuard<'a, Box<dyn InvertedIndex>>,
26    &'a StorageReadControl,
27);
28struct VectorRead<'a>(
29    RwLockReadGuard<'a, uqa_storage::vector_index::VectorIndexes>,
30    &'a StorageReadControl,
31);
32impl TextStatisticsRead for TextRead<'_> {
33    fn query_doc_freq_with_control(
34        &self,
35        field: Option<&str>,
36        query: &str,
37        control: &uqa_core::memory::ProductionControl<'_>,
38    ) -> Result<u64, SQLError> {
39        control.check()?;
40        let frequency =
41            uqa_storage::inverted_index::query_document_frequency(&**self.0, field, query, self.1)
42                .map_err(|error| {
43                    crate::search::storage_sql_error("execute analyze optimizer query", error)
44                })?;
45        control.check()?;
46        Ok(frequency)
47    }
48
49    fn field_names(&self) -> Result<Option<Vec<String>>, SQLError> {
50        self.0.field_names().map(Some).map_err(|error| {
51            crate::search::storage_sql_error("execute read document frequency", error)
52        })
53    }
54
55    fn analyze_utf16(&self, field: &str, query: &str) -> Result<Vec<Vec<u16>>, SQLError> {
56        Ok(self
57            .0
58            .search_analyzer_revision(field)
59            .map_err(|error| {
60                crate::search::storage_sql_error("execute analyze optimizer query", error)
61            })?
62            .analyze_tokens(query)
63            .map_err(analysis_error)?
64            .tokens()
65            .iter()
66            .map(|token| token.term().utf16().into_owned())
67            .collect())
68    }
69    fn doc_freq_utf16(&self, field: &str, term: &[u16]) -> Result<u64, SQLError> {
70        let key = uqa_storage::TokenTermKey::from_term(&uqa_analysis::TokenTerm::from_utf16(
71            term.to_vec(),
72        ));
73        self.0.doc_freq_key(field, &key).map_err(|error| {
74            crate::search::storage_sql_error("execute read document frequency", error)
75        })
76    }
77
78    fn analyze(&self, field: &str, query: &str) -> Result<Vec<String>, SQLError> {
79        self.0
80            .search_analyzer_revision(field)
81            .map_err(|error| {
82                crate::search::storage_sql_error("execute analyze optimizer query", error)
83            })?
84            .analyze(query)
85            .map_err(analysis_error)
86    }
87    fn doc_freq(&self, field: &str, term: &str) -> Result<u64, SQLError> {
88        self.0.doc_freq(field, term).map_err(|error| {
89            crate::search::storage_sql_error("execute read document frequency", error)
90        })
91    }
92    fn doc_freq_any_field(&self, term: &str) -> Result<u64, SQLError> {
93        self.0.doc_freq_any_field(term).map_err(|error| {
94            crate::search::storage_sql_error("execute read document frequency", error)
95        })
96    }
97}
98fn analysis_error(error: uqa_analysis::AnalysisError) -> SQLError {
99    match error {
100        uqa_analysis::AnalysisError::Memory(error) => {
101            crate::search::storage_sql_error("execute analyze optimizer query", error)
102        }
103        uqa_analysis::AnalysisError::Cancelled => {
104            SQLError::Cancelled(uqa_core::QueryCancelled::USER_REQUEST)
105        }
106        error => SQLError::Internal(format!("execute analyze optimizer query: {error}")),
107    }
108}
109impl VectorStatisticsRead for VectorRead<'_> {
110    fn dimensions(&self, field: &str) -> Option<u32> {
111        self.0.get(field).map(uqa_storage::VectorIndex::dimensions)
112    }
113    fn diskann_index_statistics(
114        &self,
115        field: &str,
116    ) -> Result<Option<uqa_core::DiskANNIndexStats>, SQLError> {
117        let Some(index) = self.0.get(field) else {
118            return Ok(None);
119        };
120        index
121            .diskann_query_metadata(self.1)
122            .and_then(|metadata| {
123                metadata
124                    .map(|metadata| metadata.index_statistics(self.1))
125                    .transpose()
126            })
127            .map_err(|error| {
128                crate::search::storage_sql_error("read physical vector statistics", error)
129            })
130    }
131    fn diskann_query_statistics(
132        &self,
133        field: &str,
134        query: &[f32],
135    ) -> Result<Option<uqa_core::DiskANNQueryStats>, SQLError> {
136        let Some(index) = self.0.get(field) else {
137            return Ok(None);
138        };
139        index
140            .diskann_query_metadata(self.1)
141            .and_then(|metadata| {
142                metadata
143                    .map(|metadata| metadata.query_statistics(query, self.1))
144                    .transpose()
145            })
146            .map_err(|error| {
147                crate::search::storage_sql_error("read physical vector statistics", error)
148            })
149    }
150}
151impl RetrievalStatisticsTable for TableStatistics {
152    fn text_index(&self) -> Box<dyn TextStatisticsRead + '_> {
153        Box::new(TextRead(self.0.inverted_index.read(), &self.1))
154    }
155    fn vector_indexes(&self) -> Box<dyn VectorStatisticsRead + '_> {
156        Box::new(VectorRead(self.0.vector_indexes.read(), &self.1))
157    }
158}
159impl RetrievalPlanningCatalog for Engine {
160    fn production_resources(&self) -> Result<Option<uqa_planner::PlanningResources>, SQLError> {
161        uqa_planner::statement_planning::executable::StatementOptimizationContexts::production_resources(self)
162    }
163
164    fn has_table(&self, table: &str) -> Result<bool, String> {
165        self.has_table_in_execution(table)
166            .map_err(|error| error.to_string())
167    }
168    fn resolve_table_name(&self, table: &str) -> Result<Option<String>, String> {
169        self.resolve_table_name(table)
170            .map_err(|error| error.to_string())
171    }
172    fn list_catalog_indexes(&self) -> Result<CatalogIndexSnapshot, String> {
173        self.catalog_index_snapshot_in_execution()
174            .map_err(|error| error.to_string())
175    }
176    fn value_index_cardinality(
177        &self,
178        table: &str,
179        field: &str,
180        predicate: &Predicate,
181    ) -> Result<Option<usize>, SQLError> {
182        self.value_index_cardinality(table, field, predicate)
183    }
184    fn value_index_supports(
185        &self,
186        table: &str,
187        field: &str,
188        predicate: &Predicate,
189    ) -> Result<bool, String> {
190        self.value_index_supports(table, field, predicate)
191            .map_err(|error| error.to_string())
192    }
193    fn text_top_k_capabilities(
194        &self,
195        table: &str,
196        field: &str,
197        query: &str,
198    ) -> Result<uqa_planner::TextTopKCapabilities, SQLError> {
199        let Some(t) = self.try_query_table(table).map_err(|error| {
200            crate::search::storage_sql_error("resolve text-search table", error)
201        })?
202        else {
203            return Err(SQLError::UnknownTable(table.to_string()));
204        };
205        let index = t.inverted_index.read();
206        let control = self.query_retention_control()?;
207        let analyzed_terms =
208            uqa_storage::inverted_index::query_term_count(&**index, field, query, &control)
209                .map_err(|error| crate::search::storage_sql_error("analyze text query", error))?;
210        let indexed_document_count = index
211            .field_stats_scalar_budgeted(field, &control)
212            .map_err(|error| {
213                crate::search::storage_sql_error("read indexed document count", error)
214            })?
215            .total_docs;
216        Ok(uqa_planner::TextTopKCapabilities {
217            analyzed_term_count: analyzed_terms,
218            indexed_document_count,
219        })
220    }
221
222    fn table_doc_count(&self, table: &str) -> Result<u64, SQLError> {
223        self.table_row_estimate(table)
224    }
225    fn try_query_table(
226        &self,
227        table: &str,
228    ) -> Result<Option<Box<dyn RetrievalStatisticsTable>>, String> {
229        let Some(state) = self
230            .try_query_table(table)
231            .map_err(|error| error.to_string())?
232        else {
233            return Ok(None);
234        };
235        let control = self
236            .query_retention_control()
237            .map_err(|error| error.to_string())?;
238        Ok(Some(Box::new(TableStatistics(state, control))))
239    }
240    fn try_query_column_stats(&self, table: &str) -> Result<ColumnStatistics, String> {
241        self.try_query_column_stats(table)
242            .map_err(|error| error.to_string())
243    }
244    fn graph_snapshot(&self, graph: &str) -> Result<Option<GraphStatisticsSnapshot>, String> {
245        self.graph_statistics_with(graph, |store| {
246            use uqa_graph::GraphStore as _;
247            let vertices = store.vertices_in_graph(graph)?;
248            let edges = store.edges_in_graph(graph)?;
249            let degree_distribution = store.degree_distribution(graph)?;
250            let vertex_label_counts = store.vertex_label_counts(graph)?;
251            Ok::<_, uqa_graph::GraphStoreError>(GraphStatisticsSnapshot {
252                vertices,
253                edges,
254                degree_distribution,
255                vertex_label_counts,
256            })
257        })
258        .map_err(|error| error.to_string())?
259        .transpose()
260        .map_err(|error| error.to_string())
261    }
262}
263
264impl uqa_execution::operator_tree::query::RelationRetrievalPlanner for Engine {
265    fn accelerated_tree(
266        &self,
267        table: &str,
268        expression: &uqa_sql::ScalarExpr,
269        tree: uqa_operators::OperatorTree,
270    ) -> Result<Option<uqa_operators::OperatorTree>, SQLError> {
271        uqa_planner::retrieval_planning::accelerated_tree(self, table, expression, tree)
272    }
273    fn text_top_k(
274        &self,
275        table: &str,
276        tree: uqa_operators::OperatorTree,
277        top_k: usize,
278    ) -> Result<uqa_operators::OperatorTree, SQLError> {
279        uqa_planner::retrieval_planning::plan_bound_text_top_k(self, table, tree, top_k)
280    }
281}