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                row_presence: input.index.cold.row_presence.clone(),
128                lateral_restrictions: input.index.cold.lateral_restrictions.clone(),
129                open_qualifiers: input.index.cold.open_qualifiers.clone(),
130                extra_ambiguous_unqualified: outer_ambiguous,
131                extra_ambiguous_qualified: ambiguous_qualified,
132                ..SchemaBuildMetadata::default()
133            },
134        )
135    }
136
137    /// Overlay an existing positional outer scope while preserving its complete structured lookup layout and sharing its physical value fragments.
138    #[expect(
139        clippy::too_many_lines,
140        reason = "outer-scope merge keeps schema and value precedence aligned"
141    )]
142    pub fn with_outer_schema(input: &Self, outer: &Self) -> Self {
143        let mut collations = input.index.cold.collations.clone();
144        let outer_base = input.physical_width();
145        let current_qualifiers = input.relation_qualifiers().collect::<HashSet<_>>();
146        let mut current_unqualified = input
147            .index
148            .unqualified
149            .keys()
150            .map(std::convert::AsRef::as_ref)
151            .collect::<HashSet<_>>();
152        current_unqualified.extend(
153            input
154                .index
155                .aliases
156                .keys()
157                .filter(|identity| identity.qualifier().is_none())
158                .map(ColumnIdentity::column),
159        );
160
161        let shifted_slot = |slot: usize| {
162            if slot == NULL_SLOT {
163                NULL_SLOT
164            } else {
165                outer_base + slot
166            }
167        };
168        let mut aliases = input.index.aliases.clone();
169        let mut alias_types = input.index.cold.aliases.clone();
170        let mut ambiguous_unqualified = input.index.ambiguous_unqualified.clone();
171        let mut ambiguous_qualified = input.index.ambiguous_qualified.clone();
172
173        let qualified_identities = outer
174            .index
175            .qualified
176            .keys()
177            .chain(
178                outer
179                    .index
180                    .aliases
181                    .keys()
182                    .filter(|identity| identity.qualifier().is_some()),
183            )
184            .chain(outer.index.ambiguous_qualified.iter())
185            .cloned()
186            .collect::<HashSet<_>>();
187        for identity in qualified_identities {
188            let qualifier = identity
189                .qualifier()
190                .expect("qualified outer identity has a qualifier");
191            if current_qualifiers.contains(qualifier) {
192                continue;
193            }
194            if outer.qualified_column_is_ambiguous(qualifier, identity.column()) {
195                aliases.remove(&identity);
196                alias_types.remove(&identity);
197                ambiguous_qualified.insert(identity);
198                continue;
199            }
200            let slot = outer
201                .qualified_slot(qualifier, identity.column())
202                .map_or(NULL_SLOT, shifted_slot);
203            let ty = outer.qualified_type(qualifier, identity.column()).cloned();
204            collations.alias(
205                &identity,
206                outer.qualified_collation(qualifier, identity.column()),
207                ty.as_ref(),
208            );
209            aliases.insert(identity.clone(), slot);
210            alias_types.insert(identity, ty);
211        }
212
213        let outer_unqualified = outer
214            .index
215            .unqualified
216            .keys()
217            .map(std::convert::AsRef::as_ref)
218            .chain(
219                outer
220                    .index
221                    .aliases
222                    .keys()
223                    .filter(|identity| identity.qualifier().is_none())
224                    .map(ColumnIdentity::column),
225            )
226            .chain(
227                outer
228                    .index
229                    .ambiguous_unqualified
230                    .iter()
231                    .map(std::convert::AsRef::as_ref),
232            )
233            .collect::<HashSet<_>>();
234        for column in outer_unqualified {
235            if current_unqualified.contains(column) {
236                continue;
237            }
238            let identity = ColumnIdentity::unqualified(column);
239            if outer.column_is_ambiguous(column) {
240                aliases.remove(&identity);
241                alias_types.remove(&identity);
242                ambiguous_unqualified.insert(Box::<str>::from(column));
243                continue;
244            }
245            let slot = outer.column_slot(column).map_or(NULL_SLOT, shifted_slot);
246            aliases.insert(identity.clone(), slot);
247            collations.alias(&identity, outer.collation_of(column), outer.type_of(column));
248            alias_types.insert(identity, outer.type_of(column).cloned());
249        }
250
251        let mut internal = input.index.executor_attributes.clone();
252        let mut internal_types = input.index.cold.executor_attribute_types.clone();
253        for (column, slot) in &outer.index.executor_attributes {
254            internal.insert(*column, shifted_slot(*slot));
255        }
256        for (column, ty) in &outer.index.cold.executor_attribute_types {
257            collations.internal(*column, outer.internal_collation(*column), ty.as_ref());
258            if let Some(existing) = internal_types.get(column) {
259                assert_eq!(
260                    existing, ty,
261                    "structural identity type changed across correlated scopes"
262                );
263            } else {
264                internal_types.insert(*column, ty.clone());
265            }
266        }
267        let mut score_sources = input.index.cold.score_sources.clone();
268        score_sources.extend(outer.index.cold.score_sources.iter().cloned());
269        let mut open_qualifiers = input.index.cold.open_qualifiers.clone();
270        open_qualifiers.extend(
271            outer
272                .index
273                .cold
274                .open_qualifiers
275                .iter()
276                .filter(|qualifier| {
277                    qualifier
278                        .as_deref()
279                        .is_none_or(|qualifier| !input.has_qualifier(qualifier))
280                })
281                .cloned(),
282        );
283
284        let schema = Self::from_typed_parts_with_aliases_and_exact_precedence(
285            input.columns().to_vec(),
286            input.identities().to_vec(),
287            input.column_types().to_vec(),
288            input.index.slots.to_vec(),
289            input.physical_width() + outer.physical_width(),
290            SchemaBuildMetadata {
291                collations,
292                record_fields: Self::joined_record_fields(input, outer, input.physical_width()),
293                aliases,
294                alias_types,
295                internal,
296                internal_types,
297                score_sources,
298                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
299                binding_only: input.index.cold.binding_only.clone(),
300                row_types: super::relation_types::RelationRowTypes::with_outer(input, outer),
301                row_presence: super::relation_presence::RelationPresence::with_outer(input, outer),
302                lateral_restrictions: Self::outer_lateral_restrictions(input, outer),
303                open_qualifiers,
304                extra_ambiguous_unqualified: ambiguous_unqualified,
305                extra_ambiguous_qualified: ambiguous_qualified,
306                local_width: Some(
307                    input
308                        .index
309                        .cold
310                        .local_width
311                        .unwrap_or_else(|| input.physical_width()),
312                ),
313                ..SchemaBuildMetadata::default()
314            },
315        );
316        let virtual_identities = outer
317            .typed_virtual_identities()
318            .filter(|(identity, _)| {
319                identity
320                    .qualifier()
321                    .is_none_or(|qualifier| !current_qualifiers.contains(qualifier))
322            })
323            .map(|(identity, ty)| (identity.clone(), ty.cloned()))
324            .collect::<Vec<_>>();
325        let mut schema = Self::with_owned_virtual_identities(schema, &virtual_identities);
326        let index = std::sync::Arc::make_mut(&mut schema.index);
327        for (identity, _) in &virtual_identities {
328            if input.index.cold.binding_only.contains_key(identity) {
329                continue;
330            }
331            if let Some(ty) = index.cold.binding_only.get(identity) {
332                index.cold.collations.virtual_column(
333                    identity,
334                    outer.virtual_collation(identity),
335                    ty.as_ref(),
336                );
337            }
338        }
339        schema
340    }
341}