Skip to main content

uqa_sql/schema/
outer_scope.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Correlated outer-scope schema composition.
8
9use std::collections::{HashMap, HashSet};
10
11use crate::ast::ColumnType;
12
13use super::{ColumnIdentity, RowSchema, SchemaBuildMetadata, SchemaSet, NULL_SLOT};
14
15#[cfg(test)]
16mod tests;
17
18impl RowSchema {
19    /// Overlay a statically typed correlated outer scope. The outer columns remain hidden from schema iteration and star expansion, but both qualified and unqualified lookup aliases retain their declared SQL types for expression binding.
20    pub fn with_typed_outer_scope(
21        input: &Self,
22        outer_columns: &[(String, Option<ColumnType>)],
23    ) -> Self {
24        let identities = outer_columns
25            .iter()
26            .map(|(column, ty)| (ColumnIdentity::unqualified(column), ty.clone()))
27            .collect::<Vec<_>>();
28        Self::with_typed_outer_identities(input, &identities)
29    }
30
31    /// Overlay a correlated outer scope carried as structured identities.
32    pub fn with_typed_outer_identities(
33        input: &Self,
34        outer_columns: &[(ColumnIdentity, Option<ColumnType>)],
35    ) -> Self {
36        let outer_base = input.physical_width();
37        let current_qualifiers = input.relation_qualifiers().collect::<HashSet<_>>();
38        let mut current_unqualified = input
39            .identities()
40            .iter()
41            .map(ColumnIdentity::column)
42            .collect::<HashSet<_>>();
43        current_unqualified.extend(
44            input
45                .index
46                .aliases
47                .keys()
48                .filter(|identity| identity.qualifier().is_none())
49                .map(ColumnIdentity::column),
50        );
51
52        let mut aliases = input.index.aliases.clone();
53        let mut alias_types = input.index.cold.aliases.clone();
54        let mut ambiguous_qualified = input.index.ambiguous_qualified.clone();
55        let mut outer_exact = HashSet::<&str>::new();
56        let mut outer_qualified = HashMap::<&str, Vec<usize>>::new();
57        let mut outer_qualified_counts = HashMap::<ColumnIdentity, usize>::new();
58        for (identity, _) in outer_columns {
59            if identity
60                .qualifier()
61                .is_some_and(|qualifier| !current_qualifiers.contains(qualifier))
62            {
63                *outer_qualified_counts.entry(identity.clone()).or_default() += 1;
64            }
65        }
66        for (position, (identity, ty)) in outer_columns.iter().enumerate() {
67            let slot = outer_base + position;
68            if let Some(qualifier) = identity.qualifier() {
69                if !current_qualifiers.contains(qualifier) {
70                    if outer_qualified_counts.get(identity) == Some(&1) {
71                        aliases.insert(identity.clone(), slot);
72                        alias_types.insert(identity.clone(), ty.clone());
73                    } else {
74                        aliases.remove(identity);
75                        alias_types.remove(identity);
76                        ambiguous_qualified.insert(identity.clone());
77                    }
78                }
79                outer_qualified
80                    .entry(identity.column())
81                    .or_default()
82                    .push(position);
83            } else {
84                outer_exact.insert(identity.column());
85                if !current_unqualified.contains(identity.column()) {
86                    aliases.insert(identity.clone(), slot);
87                    alias_types.insert(identity.clone(), ty.clone());
88                }
89            }
90        }
91
92        let mut outer_ambiguous = SchemaSet::default();
93        for (column, positions) in outer_qualified {
94            if current_unqualified.contains(column) || outer_exact.contains(column) {
95                continue;
96            }
97            match positions.as_slice() {
98                [position] => {
99                    let identity = ColumnIdentity::unqualified(column);
100                    aliases.insert(identity.clone(), outer_base + position);
101                    alias_types.insert(identity, outer_columns[*position].1.clone());
102                }
103                [_, _, ..] => {
104                    outer_ambiguous.insert(Box::<str>::from(column));
105                }
106                [] => {}
107            }
108        }
109
110        Self::from_typed_parts_with_aliases_and_exact_precedence(
111            input.columns().to_vec(),
112            input.identities().to_vec(),
113            input.column_types().to_vec(),
114            input.index.slots.to_vec(),
115            input.physical_width() + outer_columns.len(),
116            SchemaBuildMetadata {
117                collations: input.index.cold.collations.clone(),
118                record_fields: input.index.cold.record_fields.clone(),
119                aliases,
120                alias_types,
121                internal: input.index.executor_attributes.clone(),
122                internal_types: input.index.cold.executor_attribute_types.clone(),
123                score_sources: input.index.cold.score_sources.clone(),
124                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
125                binding_only: input.index.cold.binding_only.clone(),
126                row_types: input.index.cold.row_types.clone(),
127                open_qualifiers: input.index.cold.open_qualifiers.clone(),
128                extra_ambiguous_unqualified: outer_ambiguous,
129                extra_ambiguous_qualified: ambiguous_qualified,
130                ..SchemaBuildMetadata::default()
131            },
132        )
133    }
134
135    /// Overlay an existing positional outer scope while preserving its complete structured lookup layout and sharing its physical value fragments.
136    #[expect(
137        clippy::too_many_lines,
138        reason = "outer-scope merge keeps schema and value precedence aligned"
139    )]
140    pub fn with_outer_schema(input: &Self, outer: &Self) -> Self {
141        let mut collations = input.index.cold.collations.clone();
142        let outer_base = input.physical_width();
143        let current_qualifiers = input.relation_qualifiers().collect::<HashSet<_>>();
144        let mut current_unqualified = input
145            .index
146            .unqualified
147            .keys()
148            .map(std::convert::AsRef::as_ref)
149            .collect::<HashSet<_>>();
150        current_unqualified.extend(
151            input
152                .index
153                .aliases
154                .keys()
155                .filter(|identity| identity.qualifier().is_none())
156                .map(ColumnIdentity::column),
157        );
158
159        let shifted_slot = |slot: usize| {
160            if slot == NULL_SLOT {
161                NULL_SLOT
162            } else {
163                outer_base + slot
164            }
165        };
166        let mut aliases = input.index.aliases.clone();
167        let mut alias_types = input.index.cold.aliases.clone();
168        let mut ambiguous_unqualified = input.index.ambiguous_unqualified.clone();
169        let mut ambiguous_qualified = input.index.ambiguous_qualified.clone();
170
171        let qualified_identities = outer
172            .index
173            .qualified
174            .keys()
175            .chain(
176                outer
177                    .index
178                    .aliases
179                    .keys()
180                    .filter(|identity| identity.qualifier().is_some()),
181            )
182            .chain(outer.index.ambiguous_qualified.iter())
183            .cloned()
184            .collect::<HashSet<_>>();
185        for identity in qualified_identities {
186            let qualifier = identity
187                .qualifier()
188                .expect("qualified outer identity has a qualifier");
189            if current_qualifiers.contains(qualifier) {
190                continue;
191            }
192            if outer.qualified_column_is_ambiguous(qualifier, identity.column()) {
193                aliases.remove(&identity);
194                alias_types.remove(&identity);
195                ambiguous_qualified.insert(identity);
196                continue;
197            }
198            let slot = outer
199                .qualified_slot(qualifier, identity.column())
200                .map_or(NULL_SLOT, shifted_slot);
201            let ty = outer.qualified_type(qualifier, identity.column()).cloned();
202            collations.alias(
203                &identity,
204                outer.qualified_collation(qualifier, identity.column()),
205                ty.as_ref(),
206            );
207            aliases.insert(identity.clone(), slot);
208            alias_types.insert(identity, ty);
209        }
210
211        let outer_unqualified = outer
212            .index
213            .unqualified
214            .keys()
215            .map(std::convert::AsRef::as_ref)
216            .chain(
217                outer
218                    .index
219                    .aliases
220                    .keys()
221                    .filter(|identity| identity.qualifier().is_none())
222                    .map(ColumnIdentity::column),
223            )
224            .chain(
225                outer
226                    .index
227                    .ambiguous_unqualified
228                    .iter()
229                    .map(std::convert::AsRef::as_ref),
230            )
231            .collect::<HashSet<_>>();
232        for column in outer_unqualified {
233            if current_unqualified.contains(column) {
234                continue;
235            }
236            let identity = ColumnIdentity::unqualified(column);
237            if outer.column_is_ambiguous(column) {
238                aliases.remove(&identity);
239                alias_types.remove(&identity);
240                ambiguous_unqualified.insert(Box::<str>::from(column));
241                continue;
242            }
243            let slot = outer.column_slot(column).map_or(NULL_SLOT, shifted_slot);
244            aliases.insert(identity.clone(), slot);
245            collations.alias(&identity, outer.collation_of(column), outer.type_of(column));
246            alias_types.insert(identity, outer.type_of(column).cloned());
247        }
248
249        let mut internal = input.index.executor_attributes.clone();
250        let mut internal_types = input.index.cold.executor_attribute_types.clone();
251        for (column, slot) in &outer.index.executor_attributes {
252            internal.insert(*column, shifted_slot(*slot));
253        }
254        for (column, ty) in &outer.index.cold.executor_attribute_types {
255            collations.internal(*column, outer.internal_collation(*column), ty.as_ref());
256            if let Some(existing) = internal_types.get(column) {
257                assert_eq!(
258                    existing, ty,
259                    "structural identity type changed across correlated scopes"
260                );
261            } else {
262                internal_types.insert(*column, ty.clone());
263            }
264        }
265        let mut score_sources = input.index.cold.score_sources.clone();
266        score_sources.extend(outer.index.cold.score_sources.iter().cloned());
267        let mut open_qualifiers = input.index.cold.open_qualifiers.clone();
268        open_qualifiers.extend(
269            outer
270                .index
271                .cold
272                .open_qualifiers
273                .iter()
274                .filter(|qualifier| {
275                    qualifier
276                        .as_deref()
277                        .is_none_or(|qualifier| !input.has_qualifier(qualifier))
278                })
279                .cloned(),
280        );
281
282        let schema = Self::from_typed_parts_with_aliases_and_exact_precedence(
283            input.columns().to_vec(),
284            input.identities().to_vec(),
285            input.column_types().to_vec(),
286            input.index.slots.to_vec(),
287            input.physical_width() + outer.physical_width(),
288            SchemaBuildMetadata {
289                collations,
290                record_fields: Self::joined_record_fields(input, outer, input.physical_width()),
291                aliases,
292                alias_types,
293                internal,
294                internal_types,
295                score_sources,
296                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
297                binding_only: input.index.cold.binding_only.clone(),
298                row_types: super::relation_types::RelationRowTypes::with_outer(input, outer),
299                open_qualifiers,
300                extra_ambiguous_unqualified: ambiguous_unqualified,
301                extra_ambiguous_qualified: ambiguous_qualified,
302                local_width: Some(
303                    input
304                        .index
305                        .cold
306                        .local_width
307                        .unwrap_or_else(|| input.physical_width()),
308                ),
309                ..SchemaBuildMetadata::default()
310            },
311        );
312        let virtual_identities = outer
313            .typed_virtual_identities()
314            .filter(|(identity, _)| {
315                identity
316                    .qualifier()
317                    .is_none_or(|qualifier| !current_qualifiers.contains(qualifier))
318            })
319            .map(|(identity, ty)| (identity.clone(), ty.cloned()))
320            .collect::<Vec<_>>();
321        let mut schema = Self::with_owned_virtual_identities(schema, &virtual_identities);
322        let index = std::sync::Arc::make_mut(&mut schema.index);
323        for (identity, _) in &virtual_identities {
324            if input.index.cold.binding_only.contains_key(identity) {
325                continue;
326            }
327            if let Some(ty) = index.cold.binding_only.get(identity) {
328                index.cold.collations.virtual_column(
329                    identity,
330                    outer.virtual_collation(identity),
331                    ty.as_ref(),
332                );
333            }
334        }
335        schema
336    }
337}