Skip to main content

uqa_sql/schema/
schema_composition.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Schema append, join, view, and physical relayout operations.
8
9use super::{
10    ColumnIdentity, ColumnType, RowSchema, SchemaBuildMetadata, SchemaLayoutError,
11    SchemaLayoutResult, NULL_SLOT,
12};
13
14impl RowSchema {
15    /// Append freshly-computed values to an existing physical row. Reusing an
16    /// existing output name replaces its logical slot just like map insertion.
17    pub fn append(input: &Self, names: &[String]) -> Self {
18        let columns = names
19            .iter()
20            .cloned()
21            .map(|name| (name, None))
22            .collect::<Vec<_>>();
23        Self::append_typed(input, &columns)
24    }
25
26    /// Append freshly computed values with static SQL output types.
27    pub fn append_typed(input: &Self, names: &[(String, Option<ColumnType>)]) -> Self {
28        let mut collations = input.index.cold.collations.clone();
29        let mut columns = input.columns().to_vec();
30        let mut identities = input.identities().to_vec();
31        let mut types = input.column_types().to_vec();
32        let mut slots = input.index.slots.to_vec();
33        let mut wildcard_hidden = input.index.cold.wildcard_hidden.clone();
34        let base = input.physical_width();
35        for (offset, (name, ty)) in names.iter().enumerate() {
36            let slot = base + offset;
37            if let Some(position) = columns.iter().position(|column| column == name) {
38                slots[position] = slot;
39                identities[position] = ColumnIdentity::unqualified(name);
40                types[position].clone_from(ty);
41                collations.column(position, None, ty.as_ref());
42                wildcard_hidden.remove(&position);
43            } else {
44                columns.push(name.clone());
45                identities.push(ColumnIdentity::unqualified(name));
46                types.push(ty.clone());
47                slots.push(slot);
48            }
49        }
50        Self::from_typed_parts_with_aliases_and_exact_precedence(
51            columns,
52            identities,
53            types,
54            slots,
55            base + names.len(),
56            SchemaBuildMetadata {
57                collations,
58                record_fields: input.index.cold.record_fields.clone(),
59                aliases: input.index.aliases.clone(),
60                alias_types: input.index.cold.aliases.clone(),
61                internal: input.index.executor_attributes.clone(),
62                internal_types: input.index.cold.executor_attribute_types.clone(),
63                score_sources: input.index.cold.score_sources.clone(),
64                wildcard_hidden,
65                binding_only: input.index.cold.binding_only.clone(),
66                row_types: input.index.cold.row_types.clone(),
67                row_presence: input.index.cold.row_presence.clone(),
68                open_qualifiers: input.index.cold.open_qualifiers.clone(),
69                ..SchemaBuildMetadata::default()
70            },
71        )
72    }
73
74    /// Extend the physical row with anonymous values that have no SQL name or
75    /// wildcard presence. Callers may attach structured SQL identities or
76    /// internal relation attributes to the resulting physical slots.
77    pub fn append_hidden_typed(input: &Self, types: &[Option<ColumnType>]) -> Self {
78        Self::from_typed_parts_with_aliases_and_exact_precedence(
79            input.columns().to_vec(),
80            input.identities().to_vec(),
81            input.column_types().to_vec(),
82            input.index.slots.to_vec(),
83            input.physical_width() + types.len(),
84            SchemaBuildMetadata {
85                collations: input.index.cold.collations.clone(),
86                record_fields: input.index.cold.record_fields.clone(),
87                aliases: input.index.aliases.clone(),
88                alias_types: input.index.cold.aliases.clone(),
89                internal: input.index.executor_attributes.clone(),
90                internal_types: input.index.cold.executor_attribute_types.clone(),
91                score_sources: input.index.cold.score_sources.clone(),
92                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
93                binding_only: input.index.cold.binding_only.clone(),
94                row_types: input.index.cold.row_types.clone(),
95                row_presence: input.index.cold.row_presence.clone(),
96                open_qualifiers: input.index.cold.open_qualifiers.clone(),
97                ..SchemaBuildMetadata::default()
98            },
99        )
100    }
101
102    /// Append computed executor attributes under structural identities while
103    /// keeping them out of the SQL name and wildcard namespaces.
104    pub fn append_internal_typed(
105        input: &Self,
106        columns: &[(crate::ast::InternalColumnRef, Option<ColumnType>)],
107    ) -> Self {
108        let mut collations = input.index.cold.collations.clone();
109        let base = input.physical_width();
110        let mut internal = input.index.executor_attributes.clone();
111        let mut internal_types = input.index.cold.executor_attribute_types.clone();
112        for (offset, (column, ty)) in columns.iter().enumerate() {
113            collations.internal(*column, None, ty.as_ref());
114            internal.insert(*column, base + offset);
115            internal_types.insert(*column, ty.clone());
116        }
117        Self::from_typed_parts_with_aliases_and_exact_precedence(
118            input.columns().to_vec(),
119            input.identities().to_vec(),
120            input.column_types().to_vec(),
121            input.index.slots.to_vec(),
122            base + columns.len(),
123            SchemaBuildMetadata {
124                collations,
125                record_fields: input.index.cold.record_fields.clone(),
126                aliases: input.index.aliases.clone(),
127                alias_types: input.index.cold.aliases.clone(),
128                internal,
129                internal_types,
130                score_sources: input.index.cold.score_sources.clone(),
131                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
132                binding_only: input.index.cold.binding_only.clone(),
133                row_types: input.index.cold.row_types.clone(),
134                row_presence: input.index.cold.row_presence.clone(),
135                open_qualifiers: input.index.cold.open_qualifiers.clone(),
136                ..SchemaBuildMetadata::default()
137            },
138        )
139    }
140
141    /// Compose two child layouts while retaining duplicate logical labels.
142    /// Qualified and positional resolution can then distinguish both input
143    /// slots without copying either value fragment.
144    pub fn join(
145        left: &Self,
146        right: &Self,
147        extra_columns: impl IntoIterator<Item = String>,
148    ) -> Self {
149        let collations = super::Collations::joined(left, right);
150        let mut columns = left.columns().to_vec();
151        let mut identities = left.identities().to_vec();
152        let mut types = left.column_types().to_vec();
153        let mut slots = left.index.slots.to_vec();
154        let right_base = left.physical_width();
155        let mut aliases = left.index.aliases.clone();
156        let mut alias_types = left.index.cold.aliases.clone();
157        let mut internal = left.index.executor_attributes.clone();
158        let mut internal_types = left.index.cold.executor_attribute_types.clone();
159        let mut score_sources = left.index.cold.score_sources.clone();
160        let mut wildcard_hidden = left.index.cold.wildcard_hidden.clone();
161        let open_qualifiers = &left.index.cold.open_qualifiers | &right.index.cold.open_qualifiers;
162        let mut binding_only = left.index.cold.binding_only.clone();
163        aliases.extend(right.index.aliases.iter().map(|(name, slot)| {
164            (
165                name.clone(),
166                if *slot == NULL_SLOT {
167                    NULL_SLOT
168                } else {
169                    right_base + *slot
170                },
171            )
172        }));
173        let right_aliases = right.index.cold.aliases.iter();
174        alias_types.extend(right_aliases.map(|(name, ty)| (name.clone(), ty.clone())));
175        for (column, slot) in &right.index.executor_attributes {
176            let shifted = if *slot == NULL_SLOT {
177                NULL_SLOT
178            } else {
179                right_base + *slot
180            };
181            assert!(
182                internal.insert(*column, shifted).is_none(),
183                "duplicate internal relation attribute in joined row"
184            );
185        }
186        for (column, ty) in &right.index.cold.executor_attribute_types {
187            assert!(
188                internal_types.insert(*column, ty.clone()).is_none(),
189                "duplicate internal relation attribute type in joined row"
190            );
191        }
192        score_sources.extend(right.index.cold.score_sources.iter().cloned());
193        wildcard_hidden.extend(
194            right
195                .index
196                .cold
197                .wildcard_hidden
198                .iter()
199                .map(|position| left.len() + *position),
200        );
201        binding_only.extend(
202            right
203                .index
204                .cold
205                .binding_only
206                .iter()
207                .map(|(identity, ty)| (identity.clone(), ty.clone())),
208        );
209        for (right_logical, column) in right.columns().iter().enumerate() {
210            let slot = right
211                .slot(right_logical)
212                .map_or(NULL_SLOT, |slot| right_base + slot);
213            columns.push(column.clone());
214            identities.push(right.identities()[right_logical].clone());
215            types.push(right.column_type(right_logical).cloned());
216            slots.push(slot);
217        }
218        for column in extra_columns {
219            if !columns.contains(&column) {
220                identities.push(ColumnIdentity::unqualified(column.clone()));
221                columns.push(column);
222                types.push(None);
223                slots.push(NULL_SLOT);
224            }
225        }
226        Self::from_typed_parts_with_aliases_and_exact_precedence(
227            columns,
228            identities,
229            types,
230            slots,
231            left.physical_width() + right.physical_width(),
232            SchemaBuildMetadata {
233                collations,
234                record_fields: Self::joined_record_fields(left, right, right_base),
235                aliases,
236                alias_types,
237                internal,
238                internal_types,
239                score_sources,
240                wildcard_hidden,
241                binding_only,
242                row_types: super::relation_types::RelationRowTypes::joined(left, right),
243                row_presence: super::relation_presence::RelationPresence::joined(left, right),
244                lateral_restrictions: Self::joined_diagnostic_names(left, right),
245                open_qualifiers,
246                ..SchemaBuildMetadata::default()
247            },
248        )
249    }
250
251    /// Map logical and hidden identities into `target`'s complete slot layout. Visible columns are matched by logical position; hidden lookup aliases are matched by their structured identity. This is used when two equivalent operator pipelines expose the same logical row through different physical slot arrangements.
252    pub fn relayout_slots(&self, target: &Self) -> SchemaLayoutResult<Vec<usize>> {
253        fn assign(
254            source_slots: &mut [Option<usize>],
255            target_slot: usize,
256            source_slot: usize,
257        ) -> SchemaLayoutResult<()> {
258            if target_slot == NULL_SLOT {
259                return Ok(());
260            }
261            match source_slots[target_slot] {
262                Some(existing) if existing != source_slot => Err(SchemaLayoutError(format!(
263                    "physical relayout maps target slot {target_slot} to both source slots {existing} and {source_slot}"
264                ))),
265                Some(_) => Ok(()),
266                None => {
267                    source_slots[target_slot] = Some(source_slot);
268                    Ok(())
269                }
270            }
271        }
272
273        if self.len() != target.len() {
274            return Err(SchemaLayoutError(format!(
275                "cannot relayout {} logical columns as {} logical columns",
276                self.len(),
277                target.len()
278            )));
279        }
280
281        let mut source_slots = vec![None; target.physical_width()];
282
283        for logical in 0..target.len() {
284            assign(
285                &mut source_slots,
286                target.index.slots[logical],
287                self.index.slots[logical],
288            )?;
289        }
290
291        for (identity, target_slot) in &target.index.aliases {
292            if *target_slot == NULL_SLOT {
293                continue;
294            }
295            let mut matching_slots = self
296                .index
297                .identities
298                .iter()
299                .enumerate()
300                .filter_map(|(logical, candidate)| {
301                    (candidate == identity).then_some(self.index.slots[logical])
302                })
303                .chain(self.index.aliases.get(identity).copied())
304                .collect::<Vec<_>>();
305            matching_slots.sort_unstable();
306            matching_slots.dedup();
307            let source_slot = match matching_slots.as_slice() {
308                [source_slot] => *source_slot,
309                [] => {
310                    return Err(SchemaLayoutError(format!(
311                        "physical relayout source is missing lookup identity `{identity:?}`"
312                    )))
313                }
314                _ => {
315                    return Err(SchemaLayoutError(format!(
316                        "physical relayout source has ambiguous lookup identity `{identity:?}`"
317                    )))
318                }
319            };
320            assign(&mut source_slots, *target_slot, source_slot)?;
321        }
322
323        for (column, target_slot) in &target.index.executor_attributes {
324            if *target_slot == NULL_SLOT {
325                continue;
326            }
327            // An internal target entry may be another structural identity for a slot already mapped through the public target list. A rebuilt EvalPlanQual subtree receives fresh internal relation IDs, but its visible resno layout remains the same; the existing slot assignment is therefore already authoritative.
328            if source_slots[*target_slot].is_some() {
329                continue;
330            }
331            let source_slot = self
332                .internal_slot(*column)
333                .or_else(|| {
334                    target
335                        .index
336                        .cold
337                        .score_sources
338                        .iter()
339                        .find(|source| source.column == *column)
340                        .map(|source| source.qualifier.as_deref())
341                        .and_then(|qualifier| self.score_source_slot(qualifier))
342                })
343                .or_else(|| self.relayout_presence_slot(target, *column))
344                .ok_or_else(|| {
345                    SchemaLayoutError(format!(
346                        "physical relayout source is missing internal relation attribute `{column:?}`"
347                    ))
348                })?;
349            assign(&mut source_slots, *target_slot, source_slot)?;
350        }
351
352        let source_slots = source_slots
353            .into_iter()
354            .map(|slot| slot.unwrap_or(NULL_SLOT))
355            .collect::<Vec<_>>();
356        Ok(source_slots)
357    }
358}