uqa_execution/operator_tree/driver/
joins.rs1use 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}