Skip to main content

uqa_execution/operator_tree/driver/
dispatch.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Exhaustive physical dispatch for every operator-tree variant.
8
9use super::{
10    sparse_threshold_inline, DriverResult, OperatorOutput, OperatorTree, OperatorTreeDriver,
11    PhysicalRetrievalDriver, PositiveEvidencePoolExecution, PostingList, SQLError,
12    WeightedPathExecution,
13};
14
15impl OperatorTreeDriver for PhysicalRetrievalDriver<'_> {
16    type Error = SQLError;
17
18    // Keep one exhaustive physical-dispatch match: adding an IR variant must
19    // fail compilation here instead of falling through a category wildcard.
20    #[allow(clippy::match_same_arms)]
21    #[expect(
22        clippy::too_many_lines,
23        reason = "preserves exhaustive IR variant order"
24    )]
25    fn execute_node(&self, op: &OperatorTree) -> DriverResult<OperatorOutput> {
26        let posting = match op {
27            OperatorTree::Empty => Ok(PostingList::new()),
28            OperatorTree::Term {
29                query,
30                field,
31                scoring,
32                top_k,
33            } => self.execute_term(query, field.as_deref(), *scoring, *top_k),
34            OperatorTree::Phrase {
35                query,
36                field,
37                scoring,
38            } => self.execute_phrase(query, field.as_deref(), *scoring),
39            OperatorTree::BayesianScore { source, field } => {
40                self.execute_bayesian_score(source, field.as_deref())
41            }
42            OperatorTree::BayesianMatchWithPrior {
43                field,
44                query,
45                prior_field,
46                mode,
47            } => self.execute_bayesian_match_with_prior(field, query, prior_field, *mode),
48            OperatorTree::KNN {
49                query_vector,
50                k,
51                field,
52            } => self.execute_knn(query_vector, *k, field),
53            OperatorTree::CalibratedVectorMatch {
54                query_vector,
55                k,
56                field,
57                threshold,
58            } => self.execute_calibrated_vector_match(field, query_vector, *k, *threshold),
59            OperatorTree::Filter {
60                field,
61                predicate,
62                source,
63            } => self.execute_filter(field, predicate, source.as_deref()),
64            OperatorTree::Facet { field, source } => self.execute_facet(field, source.as_deref()),
65            OperatorTree::Score {
66                scorer,
67                source,
68                query_terms,
69                field,
70            } => self.execute_score(scorer, source, query_terms, field),
71            OperatorTree::Intersect(parts) => return self.execute_intersect(parts),
72            OperatorTree::Union(parts) => return self.execute_union(parts),
73            OperatorTree::Complement(inner) => self.execute_complement(inner),
74            OperatorTree::Composed(parts) => return self.execute_composed(parts),
75            OperatorTree::EncodeGraphPosting { source } => {
76                return match self.execute_node(source)? {
77                    OperatorOutput::Graph(result) => Ok(OperatorOutput::Posting(
78                        uqa_graph::GraphPostingCodec::encode(result),
79                    )),
80                    OperatorOutput::Posting(_) => Err(SQLError::TypeMismatch(
81                        "EncodeGraphPosting requires a graph posting carrier".to_string(),
82                    )),
83                    OperatorOutput::Generalized(_) => Err(SQLError::TypeMismatch(
84                        "EncodeGraphPosting cannot encode a tuple carrier".to_string(),
85                    )),
86                };
87            }
88            OperatorTree::VectorSimilarity {
89                query_vector,
90                threshold,
91                field,
92            } => self.execute_vector_similarity(query_vector, *threshold, field),
93            OperatorTree::BayesianEvidenceFusion { signals, base_rate } => {
94                self.execute_bayesian_evidence_fusion(signals, *base_rate)
95            }
96            OperatorTree::RobustPositiveEvidencePool {
97                signals,
98                alpha,
99                gating,
100                weights,
101                logit_min,
102                logit_max,
103                adaptive_weights,
104            } => self.execute_positive_evidence_pool(PositiveEvidencePoolExecution {
105                signals,
106                alpha: *alpha,
107                gating,
108                weights: weights.as_deref(),
109                logit_min: logit_min.as_deref(),
110                logit_max: logit_max.as_deref(),
111                adaptive_weights: *adaptive_weights,
112            }),
113            OperatorTree::ProbBoolFusion { signals, mode } => {
114                self.execute_prob_bool_fusion(signals, *mode)
115            }
116            OperatorTree::ProbNot {
117                signal,
118                default_prob,
119            } => self.execute_prob_not(signal, *default_prob),
120            OperatorTree::IndexScan {
121                index_name,
122                field,
123                predicate,
124            } => self.execute_index_scan(index_name, field, predicate),
125            OperatorTree::Aggregate {
126                source,
127                field,
128                monoid,
129            } => self.execute_aggregate(source.as_deref(), field, monoid),
130            OperatorTree::GroupBy {
131                source,
132                group_field,
133                agg_field,
134                monoid,
135            } => self.execute_group_by(source, group_field, agg_field, monoid),
136            OperatorTree::HybridTextVector {
137                term_op,
138                vector_op,
139                alpha,
140            } => self.execute_hybrid_text_vector(term_op, vector_op, *alpha),
141            OperatorTree::SemanticFilter { source, vector_op } => {
142                self.execute_semantic_filter(source, vector_op)
143            }
144            OperatorTree::VectorExclusion { positive, negative } => {
145                self.execute_vector_exclusion(positive, negative)
146            }
147            OperatorTree::FacetVector {
148                vector_op,
149                facet_field,
150            } => self.execute_facet_vector(vector_op, facet_field),
151            OperatorTree::CosineProbability(source) => self.execute_cosine_probability(source),
152            OperatorTree::AttentionFusion {
153                signals,
154                attention,
155                query_features,
156            } => self.execute_attention_fusion(signals, attention, query_features),
157            OperatorTree::LearnedFusion { signals, learned } => {
158                self.execute_learned_fusion(signals, learned)
159            }
160            OperatorTree::SparseThreshold { source, threshold } => {
161                let source = self.execute_posting_node(source)?;
162                sparse_threshold_inline(&source, *threshold)
163            }
164            OperatorTree::MultiFieldSearch {
165                fields,
166                queries,
167                weights,
168            } => self.execute_multi_field_search(fields, queries, weights.as_deref()),
169            OperatorTree::MultiStage { stages } => self.execute_multi_stage(stages),
170            OperatorTree::Traverse {
171                start_vertex,
172                graph,
173                label,
174                max_hops,
175                vertex_predicate,
176            } => {
177                return self
178                    .execute_traverse(
179                        *start_vertex,
180                        graph,
181                        label.as_deref(),
182                        *max_hops,
183                        vertex_predicate.as_ref(),
184                    )
185                    .map(OperatorOutput::Graph);
186            }
187            OperatorTree::GraphNeighbors {
188                vertex,
189                graph,
190                label,
191                direction,
192            } => self.execute_graph_neighbors(*vertex, graph, label.as_deref(), *direction),
193            OperatorTree::GraphEdges { graph, label } => {
194                self.execute_graph_edges(graph, label.as_deref())
195            }
196            OperatorTree::PatternMatch { pattern, graph } => {
197                return self
198                    .execute_pattern_match(pattern, graph)
199                    .map(OperatorOutput::Graph);
200            }
201            OperatorTree::RegularPathQuery {
202                rpq_source,
203                start_vertex,
204                graph,
205            } => {
206                return self
207                    .execute_regular_path_query(rpq_source, *start_vertex, graph)
208                    .map(OperatorOutput::Graph);
209            }
210            OperatorTree::GraphJoin {
211                left,
212                right,
213                label,
214                graph,
215            } => {
216                return self
217                    .execute_graph_join(left, right, label.as_deref(), graph)
218                    .map(OperatorOutput::Generalized);
219            }
220            OperatorTree::VertexAggregation { source, monoid } => {
221                self.execute_vertex_aggregation(source, monoid)
222            }
223            OperatorTree::WeightedPathQuery {
224                rpq_source,
225                start_vertex,
226                graph,
227                weight_property,
228                default_edge_weight,
229                max_hops,
230                predicate,
231                predicate_selectivity,
232                score,
233            } => {
234                return self
235                    .execute_weighted_path_query(WeightedPathExecution {
236                        rpq_source,
237                        start_vertex: *start_vertex,
238                        graph,
239                        weight_property,
240                        default_edge_weight: *default_edge_weight,
241                        max_hops: *max_hops,
242                        predicate,
243                        predicate_selectivity: *predicate_selectivity,
244                        score: *score,
245                    })
246                    .map(OperatorOutput::Graph);
247            }
248            OperatorTree::MessagePassing { source } => {
249                return self
250                    .execute_message_passing(source)
251                    .map(OperatorOutput::Graph);
252            }
253            OperatorTree::GraphEmbedding { source } => {
254                return self
255                    .execute_graph_embedding(source)
256                    .map(OperatorOutput::Graph);
257            }
258            OperatorTree::PageRank { graph } => {
259                return self.execute_page_rank(graph).map(OperatorOutput::Graph);
260            }
261            OperatorTree::HITS { graph } => {
262                return self.execute_hits(graph).map(OperatorOutput::Graph);
263            }
264            OperatorTree::BetweennessCentrality { graph } => {
265                return self
266                    .execute_betweenness_centrality(graph)
267                    .map(OperatorOutput::Graph);
268            }
269            OperatorTree::TextSimilarityJoin {
270                left,
271                right,
272                threshold,
273            } => {
274                return self
275                    .execute_text_similarity_join(left, right, *threshold)
276                    .map(OperatorOutput::Generalized);
277            }
278            OperatorTree::VectorSimilarityJoin {
279                left,
280                right,
281                threshold,
282            } => {
283                return self
284                    .execute_vector_similarity_join(left, right, *threshold)
285                    .map(OperatorOutput::Generalized);
286            }
287            OperatorTree::HybridJoin { left, right } => {
288                return self
289                    .execute_hybrid_join(left, right)
290                    .map(OperatorOutput::Generalized);
291            }
292            OperatorTree::CrossParadigmJoin { left, right } => {
293                return self
294                    .execute_cross_paradigm_join(left, right)
295                    .map(OperatorOutput::Generalized);
296            }
297            OperatorTree::TemporalTraverse {
298                start_vertex,
299                graph,
300                label,
301                max_hops,
302                temporal_filter,
303            } => {
304                return self
305                    .execute_temporal_traverse(
306                        *start_vertex,
307                        graph,
308                        label.as_deref(),
309                        *max_hops,
310                        temporal_filter.as_ref(),
311                    )
312                    .map(OperatorOutput::Graph);
313            }
314            OperatorTree::TemporalPatternMatch {
315                pattern,
316                graph,
317                temporal_filter,
318            } => {
319                return self
320                    .execute_temporal_pattern_match(pattern, graph, temporal_filter.as_ref())
321                    .map(OperatorOutput::Graph);
322            }
323            OperatorTree::ProgressiveFusion {
324                stages,
325                alpha,
326                gating,
327            } => self.execute_progressive_fusion(stages, *alpha, gating),
328            OperatorTree::DeepFusion {
329                layers,
330                alpha,
331                gating,
332            } => self.execute_deep_fusion(layers, *alpha, gating),
333            OperatorTree::DeepPredict { model } => self.execute_deep_predict(model),
334            OperatorTree::Opaque {
335                kind,
336                children,
337                meta,
338            } => Self::execute_opaque(kind, children, meta),
339        }?;
340        Ok(OperatorOutput::Posting(posting))
341    }
342}