Skip to main content

uqa_execution/operator_tree/driver/
context.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Catalog, snapshot and leaf inputs for physical retrieval execution.
8
9use crate::query::retrieval::context::{RetrievalDocuments, TextRetrieval, VectorPoolRetrieval};
10use std::{collections::BTreeMap, ops::Deref, sync::Arc};
11use uqa_core::{DocId, ScoredEntry, Value};
12use uqa_graph::GraphStoreHandle;
13use uqa_operators::{base::ExecutionContext, TextTopKPlan};
14use uqa_scoring::{BayesianBM25Params, ScoringMode};
15use uqa_sql::{
16    ast::{ColumnDef, ColumnType},
17    expr::EngineHook,
18    semantics::text_indexes::TextMatchCatalog,
19    SQLError,
20};
21use uqa_storage::{
22    document_store::Document, CatalogIndexRow, DocumentStore, InvertedIndex, StorageBackendResult,
23};
24
25pub type TextIndexRead<'a> = Box<dyn Deref<Target = Box<dyn InvertedIndex>> + 'a>;
26pub type VectorIndexRead<'a> =
27    Box<dyn Deref<Target = uqa_storage::vector_index::VectorIndexes> + 'a>;
28
29pub trait RetrievalIndexState: Send + Sync {
30    fn columns(&self) -> Arc<Vec<ColumnDef>>;
31    fn inverted_index(&self) -> TextIndexRead<'_>;
32    fn vector_indexes(&self) -> VectorIndexRead<'_>;
33}
34
35pub trait RetrievalRelations: Sync {
36    fn serializable_read(
37        &self,
38        table: &str,
39    ) -> Result<Option<crate::serializable::SerializableRelationRead>, SQLError>;
40
41    fn try_describe_query_table(&self, table: &str)
42        -> StorageBackendResult<Option<Vec<ColumnDef>>>;
43    fn has_table(&self, table: &str) -> StorageBackendResult<bool>;
44    fn column_type(&self, table: &str, field: &str) -> StorageBackendResult<Option<ColumnType>>;
45    fn table_doc_ids(&self, table: &str) -> Result<Vec<DocId>, SQLError>;
46    fn table_doc_id_page(
47        &self,
48        table: &str,
49        after: Option<DocId>,
50        limit: usize,
51        control: &uqa_storage::read_control::StorageReadControl,
52    ) -> Result<uqa_core::memory::BudgetedVec<DocId>, SQLError>;
53    fn get_document_fields(
54        &self,
55        table: &str,
56        ids: &[DocId],
57        field: &str,
58    ) -> Result<BTreeMap<DocId, Value>, SQLError>;
59    /// Retain the selected projection context and its original read/evaluation ordering while capturing complete filter support.
60    fn capture_document_filter(
61        &self,
62        table: &str,
63        ids: &crate::query::SelectedIds,
64        field: &str,
65        predicate: &uqa_core::Predicate,
66        bytes: usize,
67        cancellation: &uqa_core::CancellationToken,
68    ) -> Result<crate::query::scored_input::CapturedScoredEntries, SQLError> {
69        super::filter::capture(self, table, field, predicate, ids, bytes, cancellation)
70    }
71}
72
73pub trait RetrievalSnapshots: Sync {
74    fn snapshot_context(&self, table: &str) -> Result<Option<ExecutionContext>, SQLError>;
75    /// Retain the relation boundary for already evaluated score signals. Fusion does not read vector indexes; adapters can omit their physical snapshots.
76    fn snapshot_context_for_scores(
77        &self,
78        table: &str,
79    ) -> Result<Option<ExecutionContext>, SQLError> {
80        self.snapshot_context(table)
81    }
82    fn snapshot_context_with_document_store(
83        &self,
84        table: &str,
85        documents: Arc<dyn DocumentStore>,
86    ) -> Result<Option<ExecutionContext>, SQLError>;
87    fn get_documents_with_materialized_projection(
88        &self,
89        table: &str,
90        ids: &[DocId],
91        projection: &[String],
92    ) -> Result<BTreeMap<DocId, Document>, SQLError>;
93}
94
95pub trait RetrievalIndexes: crate::query::indexed_filter::QueryIndexRead {
96    fn query_table_indexes(
97        &self,
98        table: &str,
99    ) -> StorageBackendResult<Option<Box<dyn RetrievalIndexState>>>;
100    fn table_indexes(
101        &self,
102        table: &str,
103    ) -> StorageBackendResult<Option<Box<dyn RetrievalIndexState>>>;
104    fn catalog_index(&self, name: &str) -> StorageBackendResult<Option<CatalogIndexRow>>;
105    fn resolve_table_name(&self, table: &str) -> StorageBackendResult<Option<String>>;
106}
107
108pub trait PhysicalTextRetrieval: Sync {
109    fn validate_text_search_field(&self, table: &str, field: &str) -> Result<(), SQLError>;
110    fn fts_fields_for_table(&self, table: &str) -> Result<Vec<String>, SQLError>;
111    fn bayesian_params_for_relation(
112        &self,
113        table: &str,
114        signal_table: &str,
115        field: &str,
116    ) -> Result<BayesianBM25Params, SQLError>;
117    fn search_leaf(
118        &self,
119        table: &str,
120        field: &str,
121        query: &str,
122        mode: &ScoringMode,
123        limit: usize,
124        top_k: Option<TextTopKPlan>,
125    ) -> Result<Vec<ScoredEntry>, SQLError>;
126    fn visit_search_leaf(
127        &self,
128        table: &str,
129        field: &str,
130        query: &str,
131        mode: &ScoringMode,
132        visitor: &mut dyn FnMut(ScoredEntry) -> Result<(), SQLError>,
133    ) -> Result<(), SQLError>;
134}
135
136pub trait PhysicalVectorRetrieval: Sync {
137    fn knn_search_leaf(
138        &self,
139        table: &str,
140        field: &str,
141        query: &[f32],
142        k: usize,
143        diagnostics: Option<&crate::query::diagnostics::CapturedDiagnostics>,
144    ) -> Result<Vec<ScoredEntry>, SQLError>;
145}
146
147pub trait RetrievalGraphs: Sync {
148    fn graph_handle(&self, graph: &str) -> Result<Option<Arc<GraphStoreHandle>>, SQLError>;
149}
150
151pub trait RetrievalModels: Sync {
152    fn load_model(&self, name: &str) -> Result<Option<uqa_ml::DeepModel>, SQLError>;
153}
154
155#[derive(Clone, Copy)]
156pub struct PhysicalDriverContext<'a> {
157    pub runtime: crate::query::runtime::QueryRuntimeView<'a>,
158    pub parallel: &'a crate::parallel::ParallelExecutor,
159    pub relations: &'a dyn RetrievalRelations,
160    pub snapshots: &'a dyn RetrievalSnapshots,
161    pub indexes: &'a dyn RetrievalIndexes,
162    pub text: &'a dyn PhysicalTextRetrieval,
163    pub vector: &'a dyn PhysicalVectorRetrieval,
164    pub graphs: &'a dyn RetrievalGraphs,
165    pub models: &'a dyn RetrievalModels,
166    pub text_catalog: &'a (dyn TextMatchCatalog + Sync),
167    pub text_functions: &'a (dyn TextRetrieval + Sync),
168    pub documents: &'a (dyn RetrievalDocuments + Sync),
169    pub vector_pool: &'a (dyn VectorPoolRetrieval + Sync),
170    pub functions: &'a (dyn EngineHook + Sync),
171}