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::{collections::BTreeMap, sync::Arc};
12use uqa_core::{catalog_index::CatalogIndexRow, Predicate};
13use uqa_planner::{
14    retrieval_planning::{
15        GraphStatisticsSnapshot, RetrievalPlanningCatalog, RetrievalStatisticsTable,
16        TextStatisticsRead, VectorStatisticsRead,
17    },
18    ColumnStats,
19};
20use uqa_sql::SQLError;
21use uqa_storage::{read_control::StorageReadControl, InvertedIndex};
22
23struct TableStatistics(Arc<TableState>, StorageReadControl);
24struct TextRead<'a>(RwLockReadGuard<'a, Box<dyn InvertedIndex>>);
25struct VectorRead<'a>(
26    RwLockReadGuard<'a, uqa_storage::vector_index::VectorIndexes>,
27    &'a StorageReadControl,
28);
29impl TextStatisticsRead for TextRead<'_> {
30    fn field_names(&self) -> Result<Option<Vec<String>>, String> {
31        self.0
32            .field_names()
33            .map(Some)
34            .map_err(|error| error.to_string())
35    }
36
37    fn analyze_utf16(&self, field: &str, query: &str) -> Result<Vec<Vec<u16>>, String> {
38        Ok(self
39            .0
40            .search_analyzer_revision(field)
41            .map_err(|error| error.to_string())?
42            .analyze_tokens(query)
43            .map_err(|error| error.to_string())?
44            .tokens()
45            .iter()
46            .map(|token| token.term().utf16().into_owned())
47            .collect())
48    }
49    fn doc_freq_utf16(&self, field: &str, term: &[u16]) -> Result<u64, String> {
50        let key = uqa_storage::TokenTermKey::from_term(&uqa_analysis::TokenTerm::from_utf16(
51            term.to_vec(),
52        ));
53        self.0
54            .doc_freq_key(field, &key)
55            .map_err(|error| error.to_string())
56    }
57
58    fn analyze(&self, field: &str, query: &str) -> Result<Vec<String>, String> {
59        self.0
60            .search_analyzer_revision(field)
61            .map_err(|error| error.to_string())?
62            .analyze(query)
63            .map_err(|error| error.to_string())
64    }
65    fn doc_freq(&self, field: &str, term: &str) -> Result<u64, String> {
66        self.0
67            .doc_freq(field, term)
68            .map_err(|error| error.to_string())
69    }
70    fn doc_freq_any_field(&self, term: &str) -> Result<u64, String> {
71        self.0
72            .doc_freq_any_field(term)
73            .map_err(|error| error.to_string())
74    }
75}
76impl VectorStatisticsRead for VectorRead<'_> {
77    fn dimensions(&self, field: &str) -> Option<u32> {
78        self.0.get(field).map(uqa_storage::VectorIndex::dimensions)
79    }
80    fn diskann_index_statistics(
81        &self,
82        field: &str,
83    ) -> Result<Option<uqa_core::DiskANNIndexStats>, SQLError> {
84        let Some(index) = self.0.get(field) else {
85            return Ok(None);
86        };
87        index
88            .diskann_query_metadata(self.1)
89            .and_then(|metadata| {
90                metadata
91                    .map(|metadata| metadata.index_statistics(self.1))
92                    .transpose()
93            })
94            .map_err(|error| {
95                crate::search::storage_sql_error("read physical vector statistics", error)
96            })
97    }
98    fn diskann_query_statistics(
99        &self,
100        field: &str,
101        query: &[f32],
102    ) -> Result<Option<uqa_core::DiskANNQueryStats>, SQLError> {
103        let Some(index) = self.0.get(field) else {
104            return Ok(None);
105        };
106        index
107            .diskann_query_metadata(self.1)
108            .and_then(|metadata| {
109                metadata
110                    .map(|metadata| metadata.query_statistics(query, self.1))
111                    .transpose()
112            })
113            .map_err(|error| {
114                crate::search::storage_sql_error("read physical vector statistics", error)
115            })
116    }
117}
118impl RetrievalStatisticsTable for TableStatistics {
119    fn text_index(&self) -> Box<dyn TextStatisticsRead + '_> {
120        Box::new(TextRead(self.0.inverted_index.read()))
121    }
122    fn vector_indexes(&self) -> Box<dyn VectorStatisticsRead + '_> {
123        Box::new(VectorRead(self.0.vector_indexes.read(), &self.1))
124    }
125}
126impl RetrievalPlanningCatalog for Engine {
127    fn has_table(&self, table: &str) -> Result<bool, String> {
128        self.has_table_in_execution(table)
129            .map_err(|error| error.to_string())
130    }
131    fn resolve_table_name(&self, table: &str) -> Result<Option<String>, String> {
132        self.resolve_table_name(table)
133            .map_err(|error| error.to_string())
134    }
135    fn list_catalog_indexes(&self) -> Result<Vec<CatalogIndexRow>, String> {
136        self.catalog_indexes_in_execution()
137            .map_err(|error| error.to_string())
138    }
139    fn value_index_cardinality(
140        &self,
141        table: &str,
142        field: &str,
143        predicate: &Predicate,
144    ) -> Result<Option<usize>, SQLError> {
145        self.value_index_cardinality(table, field, predicate)
146    }
147    fn value_index_supports(
148        &self,
149        table: &str,
150        field: &str,
151        predicate: &Predicate,
152    ) -> Result<bool, String> {
153        self.value_index_supports(table, field, predicate)
154            .map_err(|error| error.to_string())
155    }
156    fn text_top_k_capabilities(
157        &self,
158        table: &str,
159        field: &str,
160        query: &str,
161    ) -> Result<uqa_planner::TextTopKCapabilities, SQLError> {
162        let Some(t) = self.try_query_table(table).map_err(|error| {
163            crate::search::storage_sql_error("resolve text-search table", error)
164        })?
165        else {
166            return Err(SQLError::UnknownTable(table.to_string()));
167        };
168        let index = t.inverted_index.read();
169        let analyzer = index.search_analyzer_revision(field).map_err(|error| {
170            crate::search::storage_sql_error("resolve text analyzer revision", error)
171        })?;
172        let analyzed_terms = analyzer
173            .analyze_tokens(query)
174            .map_err(|error| crate::search::storage_sql_error("analyze text query", error))?
175            .tokens()
176            .len();
177        let indexed_document_count = index.field_doc_count(field).map_err(|error| {
178            crate::search::storage_sql_error("read indexed document count", error)
179        })?;
180        Ok(uqa_planner::TextTopKCapabilities {
181            analyzed_term_count: analyzed_terms,
182            indexed_document_count,
183        })
184    }
185
186    fn table_doc_count(&self, table: &str) -> Result<u64, SQLError> {
187        self.table_row_estimate(table)
188    }
189    fn try_query_table(
190        &self,
191        table: &str,
192    ) -> Result<Option<Box<dyn RetrievalStatisticsTable>>, String> {
193        let Some(state) = self
194            .try_query_table(table)
195            .map_err(|error| error.to_string())?
196        else {
197            return Ok(None);
198        };
199        let control = self
200            .query_retention_control()
201            .map_err(|error| error.to_string())?;
202        Ok(Some(Box::new(TableStatistics(state, control))))
203    }
204    fn try_query_column_stats(&self, table: &str) -> Result<BTreeMap<String, ColumnStats>, String> {
205        self.try_query_column_stats(table)
206            .map_err(|error| error.to_string())
207    }
208    fn graph_snapshot(&self, graph: &str) -> Result<Option<GraphStatisticsSnapshot>, String> {
209        self.graph_statistics_with(graph, |store| {
210            use uqa_graph::GraphStore as _;
211            let vertices = store.vertices_in_graph(graph)?;
212            let edges = store.edges_in_graph(graph)?;
213            let degree_distribution = store.degree_distribution(graph)?;
214            let vertex_label_counts = store.vertex_label_counts(graph)?;
215            Ok::<_, uqa_graph::GraphStoreError>(GraphStatisticsSnapshot {
216                vertices,
217                edges,
218                degree_distribution,
219                vertex_label_counts,
220            })
221        })
222        .map_err(|error| error.to_string())?
223        .transpose()
224        .map_err(|error| error.to_string())
225    }
226}
227
228impl uqa_execution::operator_tree::query::RelationRetrievalPlanner for Engine {
229    fn accelerated_tree(
230        &self,
231        table: &str,
232        expression: &uqa_sql::ScalarExpr,
233        tree: uqa_operators::OperatorTree,
234    ) -> Result<Option<uqa_operators::OperatorTree>, SQLError> {
235        uqa_planner::retrieval_planning::accelerated_tree(self, table, expression, tree)
236    }
237    fn text_top_k(
238        &self,
239        table: &str,
240        tree: uqa_operators::OperatorTree,
241        top_k: usize,
242    ) -> Result<uqa_operators::OperatorTree, SQLError> {
243        uqa_planner::retrieval_planning::plan_bound_text_top_k(self, table, tree, top_k)
244    }
245}