Skip to main content

uqa_execution/operator_tree/driver/
joins.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Text, vector, hybrid, and cross-paradigm join execution.
8
9use super::{
10    first_structured_field, require_graph_name, require_shared_structured_field,
11    require_shared_vector_field, require_text_field, require_vector_field, DriverResult,
12    GeneralizedPostingList, HybridJoinFields, OperatorTree, PhysicalRetrievalDriver, PostingEntry,
13    PostingList, SQLError,
14};
15
16impl PhysicalRetrievalDriver<'_> {
17    pub(super) fn execute_text_similarity_join(
18        &self,
19        left: &OperatorTree,
20        right: &OperatorTree,
21        threshold: f64,
22    ) -> DriverResult<GeneralizedPostingList> {
23        if !threshold.is_finite() || !(0.0..=1.0).contains(&threshold) {
24            return Err(SQLError::TypeMismatch(format!(
25                "TextSimilarityJoin.threshold must be finite and in [0, 1], got {threshold}"
26            )));
27        }
28        let left_field = require_text_field(left, "TextSimilarityJoin.left")?;
29        let right_field = require_text_field(right, "TextSimilarityJoin.right")?;
30        let left_source = self.execute_posting_node(left)?;
31        let right_source = self.execute_posting_node(right)?;
32        self.join_text_similarity_postings(
33            self,
34            &left_source,
35            &left_field,
36            &right_source,
37            &right_field,
38            threshold,
39        )
40    }
41
42    pub fn join_text_similarity_postings(
43        &self,
44        right_driver: &PhysicalRetrievalDriver<'_>,
45        left_source: &PostingList,
46        left_field: &str,
47        right_source: &PostingList,
48        right_field: &str,
49        threshold: f64,
50    ) -> DriverResult<GeneralizedPostingList> {
51        let left = self.prepare_join_operand(left_source, left_field, "_join_text")?;
52        let right = right_driver.prepare_join_operand(right_source, right_field, "_join_text")?;
53        uqa_joins::TextSimilarityJoin::new(
54            left.entries(),
55            right.entries(),
56            "_join_text",
57            "_join_text",
58        )
59        .threshold(threshold)
60        .execute()
61        .map_err(|error| SQLError::Internal(format!("execute TextSimilarityJoin: {error}")))
62    }
63
64    pub(super) fn execute_vector_similarity_join(
65        &self,
66        left: &OperatorTree,
67        right: &OperatorTree,
68        threshold: f64,
69    ) -> DriverResult<GeneralizedPostingList> {
70        if !threshold.is_finite() || !(-1.0..=1.0).contains(&threshold) {
71            return Err(SQLError::TypeMismatch(format!(
72                "VectorSimilarityJoin.threshold must be finite and in [-1, 1], got {threshold}"
73            )));
74        }
75        let left_field = require_vector_field(left, "VectorSimilarityJoin.left")?;
76        let right_field = require_vector_field(right, "VectorSimilarityJoin.right")?;
77        let left_source = self.execute_posting_node(left)?;
78        let right_source = self.execute_posting_node(right)?;
79        self.join_vector_similarity_postings(
80            self,
81            &left_source,
82            &left_field,
83            &right_source,
84            &right_field,
85            threshold,
86        )
87    }
88
89    pub fn join_vector_similarity_postings(
90        &self,
91        right_driver: &PhysicalRetrievalDriver<'_>,
92        left_source: &PostingList,
93        left_field: &str,
94        right_source: &PostingList,
95        right_field: &str,
96        threshold: f64,
97    ) -> DriverResult<GeneralizedPostingList> {
98        let left = self.prepare_join_operand(left_source, left_field, "_join_vector")?;
99        let right = right_driver.prepare_join_operand(right_source, right_field, "_join_vector")?;
100        uqa_joins::VectorSimilarityJoin::new(
101            left.entries(),
102            right.entries(),
103            "_join_vector",
104            "_join_vector",
105        )
106        .threshold(threshold)
107        .execute()
108        .map_err(|error| SQLError::Internal(format!("execute VectorSimilarityJoin: {error}")))
109    }
110
111    pub(super) fn execute_hybrid_join(
112        &self,
113        left: &OperatorTree,
114        right: &OperatorTree,
115    ) -> DriverResult<GeneralizedPostingList> {
116        let structured_field = require_shared_structured_field(left, right, "HybridJoin")?;
117        let vector_field = require_shared_vector_field(left, right, "HybridJoin")?;
118        let left_result = self.execute_posting_node(left)?;
119        let right_result = self.execute_posting_node(right)?;
120        self.join_hybrid_postings(
121            self,
122            &left_result,
123            &right_result,
124            HybridJoinFields {
125                left_structured: &structured_field.0,
126                left_vector: &vector_field.0,
127                right_structured: &structured_field.1,
128                right_vector: &vector_field.1,
129            },
130        )
131    }
132
133    pub fn join_hybrid_postings(
134        &self,
135        right_driver: &PhysicalRetrievalDriver<'_>,
136        left_result: &PostingList,
137        right_result: &PostingList,
138        fields: HybridJoinFields<'_>,
139    ) -> DriverResult<GeneralizedPostingList> {
140        let left_keyed =
141            self.prepare_join_operand(left_result, fields.left_structured, "_join_key")?;
142        let left_result =
143            self.prepare_join_operand(&left_keyed, fields.left_vector, "_join_vector")?;
144        let right_keyed = right_driver.prepare_join_operand(
145            right_result,
146            fields.right_structured,
147            "_join_key",
148        )?;
149        let right_result =
150            right_driver.prepare_join_operand(&right_keyed, fields.right_vector, "_join_vector")?;
151        uqa_joins::HybridJoin::new(
152            left_result.entries(),
153            right_result.entries(),
154            "_join_key",
155            "_join_vector",
156        )
157        .execute()
158        .map_err(|error| SQLError::Internal(format!("execute HybridJoin: {error}")))
159    }
160
161    pub(super) fn execute_cross_paradigm_join(
162        &self,
163        left: &OperatorTree,
164        right: &OperatorTree,
165    ) -> DriverResult<GeneralizedPostingList> {
166        let graph = require_graph_name(left, "CrossParadigmJoin.left")?;
167        let vertex_field = first_structured_field(left)
168            .or_else(|| first_structured_field(right))
169            .ok_or_else(|| {
170                SQLError::TypeMismatch(
171                    "CrossParadigmJoin operands do not identify a join property".to_string(),
172                )
173            })?;
174        let doc_field = first_structured_field(right).unwrap_or_else(|| vertex_field.clone());
175        let left_result = self.execute_posting_node(left)?;
176        let right_source = self.execute_posting_node(right)?;
177        self.join_cross_paradigm_postings(
178            self,
179            &left_result,
180            &right_source,
181            &graph,
182            &vertex_field,
183            &doc_field,
184        )
185    }
186
187    pub fn join_cross_paradigm_postings(
188        &self,
189        right_driver: &PhysicalRetrievalDriver<'_>,
190        left_result: &PostingList,
191        right_source: &PostingList,
192        graph: &str,
193        vertex_field: &str,
194        doc_field: &str,
195    ) -> DriverResult<GeneralizedPostingList> {
196        let right_result =
197            right_driver.prepare_join_operand(right_source, doc_field, "_join_document")?;
198        self.with_graph(graph, |store| {
199            uqa_joins::CrossParadigmJoin::new(
200                left_result.entries(),
201                right_result.entries(),
202                store,
203                vertex_field,
204                "_join_document",
205            )
206            .execute()
207            .map_err(|error| SQLError::Internal(format!("execute CrossParadigmJoin: {error}")))
208        })
209    }
210
211    pub(super) fn prepare_join_operand(
212        &self,
213        source: &PostingList,
214        field: &str,
215        alias: &str,
216    ) -> DriverResult<PostingList> {
217        let lookup_doc_ids = source
218            .entries()
219            .iter()
220            .filter(|entry| !entry.payload.fields.contains_key(field))
221            .map(|entry| entry.doc_id)
222            .collect::<Vec<_>>();
223        let projected = if lookup_doc_ids.is_empty() {
224            std::collections::BTreeMap::new()
225        } else {
226            self.require_column(field)?;
227            self.context
228                .relations
229                .get_document_fields(self.table, &lookup_doc_ids, field)?
230        };
231        let mut entries = Vec::with_capacity(source.len());
232        for entry in source.entries() {
233            let mut payload = entry.payload.clone();
234            let value = if let Some(value) = payload.fields.get(field) {
235                value.clone()
236            } else if let Some(value) = projected.get(&entry.doc_id) {
237                value.clone()
238            } else {
239                return Err(SQLError::Internal(format!(
240                    "join operand references document {} missing from table `{}`",
241                    entry.doc_id, self.table
242                )));
243            };
244            payload.fields.insert(alias.to_string(), value);
245            entries.push(PostingEntry::new(entry.doc_id, payload));
246        }
247        Ok(PostingList::from_sorted_unchecked(entries))
248    }
249}