uqa_operators/
base.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! `Operator` trait, [`ExecutionContext`] holding storage backends, and
8//! the monoidal [`ComposedOperator`].
9
10use std::collections::BTreeMap;
11use std::sync::Arc;
12
13use uqa_core::{FieldName, IndexStats, PostingList};
14use uqa_storage::{
15    DocumentStore, InvertedIndex, StorageBackendError, StorageBackendResult, VectorIndex,
16};
17
18pub type OperatorResult = StorageBackendResult<PostingList>;
19
20pub(crate) fn missing_backend(backend: &str, operation: &str) -> StorageBackendError {
21    StorageBackendError::Other(format!(
22        "{operation} requires an execution-context {backend} backend"
23    ))
24}
25
26pub(crate) fn require_finite_score(score: f64, operation: &str) -> StorageBackendResult<()> {
27    if score.is_finite() {
28        Ok(())
29    } else {
30        Err(StorageBackendError::Other(format!(
31            "{operation} received a non-finite score {score}"
32        )))
33    }
34}
35
36pub(crate) fn require_probability(probability: f64, operation: &str) -> StorageBackendResult<()> {
37    if probability.is_finite() && (0.0..=1.0).contains(&probability) {
38        Ok(())
39    } else {
40        Err(StorageBackendError::Other(format!(
41            "{operation} requires probability scores in [0, 1], got {probability}"
42        )))
43    }
44}
45
46/// Storage handles passed to every operator's `execute` call.
47///
48/// Holding `Arc<dyn ...>` rather than borrows keeps the operator tree
49/// independent of how the engine owns its stores. The trade-off is one
50/// `Arc::clone` per operator at engine boundary; per-operator dispatch
51/// remains a single virtual call.
52#[derive(Default, Clone)]
53pub struct ExecutionContext {
54    pub document_store: Option<Arc<dyn DocumentStore>>,
55    pub inverted_index: Option<Arc<dyn InvertedIndex>>,
56    pub vector_indexes: BTreeMap<FieldName, Arc<dyn VectorIndex>>,
57    pub stats: Option<IndexStats>,
58    /// Optional named graph (label-only neighbor lookup) for the
59    /// graph-aware deep-fusion layers (`Propagate`, `Conv`, `Pool`).
60    /// Held as a generic neighbor-lookup callback so this crate stays
61    /// independent of `uqa-graph`.
62    pub graph: Option<Arc<dyn GraphNeighborLookup>>,
63}
64
65/// Minimal trait capturing the only graph operation deep-fusion's
66/// graph layers need: enumerate the neighbors of a vertex along a
67/// label in a chosen direction.
68///
69/// An empty `label` is the explicit wildcard and must enumerate neighbors
70/// across every edge label. This lets IR nodes represent an omitted edge
71/// label without inventing a separate sentinel at each engine boundary.
72pub trait GraphNeighborLookup: Send + Sync {
73    fn neighbors(
74        &self,
75        vertex: u64,
76        label: &str,
77        direction: Direction,
78    ) -> StorageBackendResult<Vec<u64>>;
79}
80
81pub use uqa_core::retrieval::Direction;
82
83impl ExecutionContext {
84    pub fn new() -> Self {
85        Self::default()
86    }
87
88    pub fn with_inverted_index(mut self, idx: Arc<dyn InvertedIndex>) -> Self {
89        self.inverted_index = Some(idx);
90        self
91    }
92
93    pub fn with_document_store(mut self, ds: Arc<dyn DocumentStore>) -> Self {
94        self.document_store = Some(ds);
95        self
96    }
97
98    pub fn with_vector_index(
99        mut self,
100        field: impl Into<FieldName>,
101        idx: Arc<dyn VectorIndex>,
102    ) -> Self {
103        self.vector_indexes.insert(field.into(), idx);
104        self
105    }
106
107    pub fn with_stats(mut self, stats: IndexStats) -> Self {
108        self.stats = Some(stats);
109        self
110    }
111
112    pub fn with_graph(mut self, graph: Arc<dyn GraphNeighborLookup>) -> Self {
113        self.graph = Some(graph);
114        self
115    }
116}
117
118pub trait Operator: Send + Sync {
119    fn execute(&self, ctx: &ExecutionContext) -> OperatorResult;
120
121    fn cost_estimate(&self, stats: &IndexStats) -> f64 {
122        stats.total_docs as f64
123    }
124}
125
126/// Sequential composition: the right-hand operand's result wins. Used as
127/// the monoidal product for the operator monoid; the empty composition is
128/// the identity.
129pub struct ComposedOperator {
130    pub operands: Vec<Arc<dyn Operator>>,
131}
132
133impl ComposedOperator {
134    pub fn new(operands: Vec<Arc<dyn Operator>>) -> Self {
135        Self { operands }
136    }
137}
138
139impl Operator for ComposedOperator {
140    fn execute(&self, ctx: &ExecutionContext) -> OperatorResult {
141        let mut result = PostingList::new();
142        for op in &self.operands {
143            result = op.execute(ctx)?;
144        }
145        Ok(result)
146    }
147
148    fn cost_estimate(&self, stats: &IndexStats) -> f64 {
149        self.operands.iter().map(|op| op.cost_estimate(stats)).sum()
150    }
151}
uqa_operators/base.rs

uqa_operators/
base.rs
