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        Self::append_internal_typed_with_control(
109            input,
110            columns.iter().map(|(column, ty)| (*column, ty.as_ref())),
111            &uqa_core::memory::ProductionControl::uncontrolled(),
112        )
113        .expect("ordinary internal attributes")
114    }
115
116    /// Compose two child layouts while retaining duplicate logical labels.
117    /// Qualified and positional resolution can then distinguish both input
118    /// slots without copying either value fragment.
119    pub fn join(
120        left: &Self,
121        right: &Self,
122        extra_columns: impl IntoIterator<Item = String>,
123    ) -> Self {
124        let collations = super::Collations::joined(left, right);
125        let mut columns = left.columns().to_vec();
126        let mut identities = left.identities().to_vec();
127        let mut types = left.column_types().to_vec();
128        let mut slots = left.index.slots.to_vec();
129        let right_base = left.physical_width();
130        let mut aliases = left.index.aliases.clone();
131        let mut alias_types = left.index.cold.aliases.clone();
132        let mut internal = left.index.executor_attributes.clone();
133        let mut internal_types = left.index.cold.executor_attribute_types.clone();
134        let mut score_sources = left.index.cold.score_sources.clone();
135        let mut wildcard_hidden = left.index.cold.wildcard_hidden.clone();
136        let open_qualifiers = &left.index.cold.open_qualifiers | &right.index.cold.open_qualifiers;
137        let mut binding_only = left.index.cold.binding_only.clone();
138        aliases.extend(right.index.aliases.iter().map(|(name, slot)| {
139            (
140                name.clone(),
141                if *slot == NULL_SLOT {
142                    NULL_SLOT
143                } else {
144                    right_base + *slot
145                },
146            )
147        }));
148        let right_aliases = right.index.cold.aliases.iter();
149        alias_types.extend(right_aliases.map(|(name, ty)| (name.clone(), ty.clone())));
150        for (column, slot) in &right.index.executor_attributes {
151            let shifted = if *slot == NULL_SLOT {
152                NULL_SLOT
153            } else {
154                right_base + *slot
155            };
156            assert!(
157                internal.insert(*column, shifted).is_none(),
158                "duplicate internal relation attribute in joined row"
159            );
160        }
161        for (column, ty) in &right.index.cold.executor_attribute_types {
162            assert!(
163                internal_types.insert(*column, ty.clone()).is_none(),
164                "duplicate internal relation attribute type in joined row"
165            );
166        }
167        score_sources.extend(right.index.cold.score_sources.iter().cloned());
168        wildcard_hidden.extend(
169            right
170                .index
171                .cold
172                .wildcard_hidden
173                .iter()
174                .map(|position| left.len() + *position),
175        );
176        binding_only.extend(
177            right
178                .index
179                .cold
180                .binding_only
181                .iter()
182                .map(|(identity, ty)| (identity.clone(), ty.clone())),
183        );
184        for (right_logical, column) in right.columns().iter().enumerate() {
185            let slot = right
186                .slot(right_logical)
187                .map_or(NULL_SLOT, |slot| right_base + slot);
188            columns.push(column.clone());
189            identities.push(right.identities()[right_logical].clone());
190            types.push(right.column_type(right_logical).cloned());
191            slots.push(slot);
192        }
193        for column in extra_columns {
194            if !columns.contains(&column) {
195                identities.push(ColumnIdentity::unqualified(column.clone()));
196                columns.push(column);
197                types.push(None);
198                slots.push(NULL_SLOT);
199            }
200        }
201        Self::from_typed_parts_with_aliases_and_exact_precedence(
202            columns,
203            identities,
204            types,
205            slots,
206            left.physical_width() + right.physical_width(),
207            SchemaBuildMetadata {
208                collations,
209                record_fields: Self::joined_record_fields(left, right, right_base),
210                aliases,
211                alias_types,
212                internal,
213                internal_types,
214                score_sources,
215                wildcard_hidden,
216                binding_only,
217                row_types: super::relation_types::RelationRowTypes::joined(left, right),
218                row_presence: super::relation_presence::RelationPresence::joined(left, right),
219                lateral_restrictions: Self::joined_diagnostic_names(left, right),
220                open_qualifiers,
221                ..SchemaBuildMetadata::default()
222            },
223        )
224    }
225
226    /// 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.
227    pub fn relayout_slots(&self, target: &Self) -> SchemaLayoutResult<Vec<usize>> {
228        fn assign(
229            source_slots: &mut [Option<usize>],
230            target_slot: usize,
231            source_slot: usize,
232        ) -> SchemaLayoutResult<()> {
233            if target_slot == NULL_SLOT {
234                return Ok(());
235            }
236            match source_slots[target_slot] {
237                Some(existing) if existing != source_slot => Err(SchemaLayoutError(format!(
238                    "physical relayout maps target slot {target_slot} to both source slots {existing} and {source_slot}"
239                ))),
240                Some(_) => Ok(()),
241                None => {
242                    source_slots[target_slot] = Some(source_slot);
243                    Ok(())
244                }
245            }
246        }
247
248        if self.len() != target.len() {
249            return Err(SchemaLayoutError(format!(
250                "cannot relayout {} logical columns as {} logical columns",
251                self.len(),
252                target.len()
253            )));
254        }
255
256        let mut source_slots = vec![None; target.physical_width()];
257
258        for logical in 0..target.len() {
259            assign(
260                &mut source_slots,
261                target.index.slots[logical],
262                self.index.slots[logical],
263            )?;
264        }
265
266        for (identity, target_slot) in &target.index.aliases {
267            if *target_slot == NULL_SLOT {
268                continue;
269            }
270            let mut matching_slots = self
271                .index
272                .identities
273                .iter()
274                .enumerate()
275                .filter_map(|(logical, candidate)| {
276                    (candidate == identity).then_some(self.index.slots[logical])
277                })
278                .chain(self.index.aliases.get(identity).copied())
279                .collect::<Vec<_>>();
280            matching_slots.sort_unstable();
281            matching_slots.dedup();
282            let source_slot = match matching_slots.as_slice() {
283                [source_slot] => *source_slot,
284                [] => {
285                    return Err(SchemaLayoutError(format!(
286                        "physical relayout source is missing lookup identity `{identity:?}`"
287                    )))
288                }
289                _ => {
290                    return Err(SchemaLayoutError(format!(
291                        "physical relayout source has ambiguous lookup identity `{identity:?}`"
292                    )))
293                }
294            };
295            assign(&mut source_slots, *target_slot, source_slot)?;
296        }
297
298        for (column, target_slot) in &target.index.executor_attributes {
299            if *target_slot == NULL_SLOT {
300                continue;
301            }
302            // 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.
303            if source_slots[*target_slot].is_some() {
304                continue;
305            }
306            let source_slot = self
307                .internal_slot(*column)
308                .or_else(|| {
309                    target
310                        .index
311                        .cold
312                        .score_sources
313                        .iter()
314                        .find(|source| source.column == *column)
315                        .map(|source| source.qualifier.as_deref())
316                        .and_then(|qualifier| self.score_source_slot(qualifier))
317                })
318                .or_else(|| self.relayout_presence_slot(target, *column))
319                .ok_or_else(|| {
320                    SchemaLayoutError(format!(
321                        "physical relayout source is missing internal relation attribute `{column:?}`"
322                    ))
323                })?;
324            assign(&mut source_slots, *target_slot, source_slot)?;
325        }
326
327        let source_slots = source_slots
328            .into_iter()
329            .map(|slot| slot.unwrap_or(NULL_SLOT))
330            .collect::<Vec<_>>();
331        Ok(source_slots)
332    }
333}