Skip to main content

uqa_sql/schema/
schema_projection.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Projection, canonicalization, and position remapping for row schemas.
8
9use super::{
10    ColumnIdentity, ColumnType, HashMap, PhysicalLayout, ProjectedSlot, RowSchema,
11    SchemaBuildMetadata, SchemaLayoutError, SchemaLayoutResult, SchemaMap, ScoreSource, NULL_SLOT,
12};
13
14impl RowSchema {
15    /// Capture positional outputs through opaque identities without retaining their SQL names or copying values. Existing internal score and record metadata remain attached to their physical slots. An implicit NULL output owns one appended NULL slot, which the physical selector must materialize.
16    pub fn capture_output(input: &Self, relation: crate::ast::InternalRelationId) -> Self {
17        Self::capture_output_with_control(
18            input,
19            relation,
20            &uqa_core::memory::ProductionControl::uncontrolled(),
21        )
22        .expect("ordinary positional output capture")
23    }
24
25    /// Remove selected executor-only identities after their consumer has run.
26    /// The physical fragments remain shareable until the next canonical
27    /// boundary, where now-unreferenced slots are naturally discarded.
28    pub fn without_internal_attributes(
29        input: &Self,
30        columns: &[crate::ast::InternalColumnRef],
31    ) -> Self {
32        let mut internal = input.index.executor_attributes.clone();
33        let mut internal_types = input.index.cold.executor_attribute_types.clone();
34        for column in columns {
35            internal.remove(column);
36            internal_types.remove(column);
37        }
38        let score_sources = input
39            .index
40            .cold
41            .score_sources
42            .iter()
43            .filter(|source| internal.contains_key(&source.column))
44            .cloned()
45            .collect();
46        let row_presence = input
47            .index
48            .cold
49            .row_presence
50            .retaining(|marker| internal.contains_key(&marker));
51        Self::from_typed_parts_with_aliases_and_exact_precedence(
52            input.columns().to_vec(),
53            input.identities().to_vec(),
54            input.column_types().to_vec(),
55            input.index.slots.to_vec(),
56            input.physical_width(),
57            SchemaBuildMetadata {
58                collations: input.index.cold.collations.clone(),
59                record_fields: input.index.cold.record_fields.clone(),
60                aliases: input.index.aliases.clone(),
61                alias_types: input.index.cold.aliases.clone(),
62                internal,
63                internal_types,
64                score_sources,
65                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
66                binding_only: input.index.cold.binding_only.clone(),
67                row_types: input.index.cold.row_types.clone(),
68                row_presence,
69                open_qualifiers: input.index.cold.open_qualifiers.clone(),
70                ..SchemaBuildMetadata::default()
71            },
72        )
73    }
74
75    /// Select and optionally rename logical columns while retaining the
76    /// child's physical fragments.
77    pub fn select(input: &Self, columns: &[(String, String)]) -> Self {
78        let mut collations = input.index.cold.collations.clone();
79        collations.clear_columns();
80        for (position, (_, source)) in columns.iter().enumerate() {
81            let oid = input
82                .position(source)
83                .and_then(|position| input.inherited_column_collation(position));
84            collations.column(position, oid, input.exact_type(source));
85        }
86        let output_names = columns
87            .iter()
88            .map(|(output, _)| output.clone())
89            .collect::<Vec<_>>();
90        let slots = columns
91            .iter()
92            .map(|(_, source)| input.exact_slot(source).unwrap_or(NULL_SLOT))
93            .collect();
94        let types = columns
95            .iter()
96            .map(|(_, source)| input.exact_type(source).cloned())
97            .collect();
98        let identities = output_names
99            .iter()
100            .cloned()
101            .map(ColumnIdentity::unqualified)
102            .collect();
103        Self::from_typed_parts_with_aliases_and_exact_precedence(
104            output_names,
105            identities,
106            types,
107            slots,
108            input.physical_width(),
109            SchemaBuildMetadata {
110                collations,
111                record_fields: input.index.cold.record_fields.clone(),
112                aliases: SchemaMap::default(),
113                alias_types: SchemaMap::default(),
114                internal: input.index.executor_attributes.clone(),
115                internal_types: input.index.cold.executor_attribute_types.clone(),
116                score_sources: input.index.cold.score_sources.clone(),
117                binding_only: SchemaMap::default(),
118                ..SchemaBuildMetadata::default()
119            },
120        )
121    }
122
123    /// Build a scalar-projection schema without rebuilding direct input values. A non-pass-through projection hides child identities logically while retaining their physical fragments; an appending projection preserves the child schema and replaces duplicate labels with `PostgreSQL` map-insertion semantics.
124    pub fn project_with_sources(
125        input: &Self,
126        projected: Vec<(String, Option<ColumnType>, ProjectedSlot)>,
127        projected_internal: Vec<(
128            crate::ast::InternalColumnRef,
129            Option<ColumnType>,
130            ProjectedSlot,
131        )>,
132        computed_count: usize,
133        pass_through: bool,
134    ) -> Self {
135        let mut collations = input.index.cold.collations.clone();
136        let resolve_slot = |source: ProjectedSlot| match source {
137            ProjectedSlot::Input(slot) | ProjectedSlot::BoundInput { physical: slot, .. } => {
138                slot.unwrap_or(NULL_SLOT)
139            }
140            ProjectedSlot::Computed { position, .. } => input.physical_width() + position,
141        };
142        let source_collation = |source: ProjectedSlot| match source {
143            ProjectedSlot::Input(Some(slot)) => input.inherited_physical_collation(slot),
144            ProjectedSlot::BoundInput { collation, .. }
145            | ProjectedSlot::Computed { collation, .. } => collation,
146            ProjectedSlot::Input(None) => None,
147        };
148        let physical_width = input.physical_width() + computed_count;
149        let mut internal = input.index.executor_attributes.clone();
150        let mut internal_types = input.index.cold.executor_attribute_types.clone();
151        for (column, ty, source) in projected_internal {
152            collations.internal(column, source_collation(source), ty.as_ref());
153            internal.insert(column, resolve_slot(source));
154            internal_types.insert(column, ty);
155        }
156
157        if pass_through {
158            let mut columns = input.columns().to_vec();
159            let mut identities = input.identities().to_vec();
160            let mut types = input.column_types().to_vec();
161            let mut slots = input.index.slots.to_vec();
162            let mut wildcard_hidden = input.index.cold.wildcard_hidden.clone();
163            for (name, ty, source) in projected {
164                let slot = resolve_slot(source);
165                if let Some(position) = columns.iter().position(|column| column == &name) {
166                    slots[position] = slot;
167                    identities[position] = ColumnIdentity::unqualified(name);
168                    collations.column(position, source_collation(source), ty.as_ref());
169                    types[position] = ty;
170                    wildcard_hidden.remove(&position);
171                } else {
172                    identities.push(ColumnIdentity::unqualified(name.clone()));
173                    columns.push(name);
174                    collations.column(types.len(), source_collation(source), ty.as_ref());
175                    types.push(ty);
176                    slots.push(slot);
177                }
178            }
179            return Self::from_typed_parts_with_aliases_and_exact_precedence(
180                columns,
181                identities,
182                types,
183                slots,
184                physical_width,
185                SchemaBuildMetadata {
186                    collations,
187                    record_fields: input.index.cold.record_fields.clone(),
188                    aliases: input.index.aliases.clone(),
189                    alias_types: input.index.cold.aliases.clone(),
190                    internal,
191                    internal_types,
192                    score_sources: input.index.cold.score_sources.clone(),
193                    wildcard_hidden: wildcard_hidden.into_iter().collect(),
194                    binding_only: input.index.cold.binding_only.clone(),
195                    row_types: input.index.cold.row_types.clone(),
196                    row_presence: input.index.cold.row_presence.clone(),
197                    open_qualifiers: input.index.cold.open_qualifiers.clone(),
198                    ..SchemaBuildMetadata::default()
199                },
200            );
201        }
202
203        collations.clear_columns();
204        let mut columns = Vec::with_capacity(projected.len());
205        let mut identities = Vec::with_capacity(projected.len());
206        let mut types = Vec::with_capacity(projected.len());
207        let mut slots = Vec::with_capacity(projected.len());
208        for (name, ty, source) in projected {
209            slots.push(resolve_slot(source));
210            identities.push(ColumnIdentity::unqualified(name.clone()));
211            columns.push(name);
212            collations.column(types.len(), source_collation(source), ty.as_ref());
213            types.push(ty);
214        }
215        Self::from_typed_parts_with_aliases_and_exact_precedence(
216            columns,
217            identities,
218            types,
219            slots,
220            physical_width,
221            SchemaBuildMetadata {
222                collations,
223                record_fields: input.index.cold.record_fields.clone(),
224                aliases: SchemaMap::default(),
225                alias_types: SchemaMap::default(),
226                internal,
227                internal_types,
228                score_sources: input.index.cold.score_sources.clone(),
229                binding_only: SchemaMap::default(),
230                ..SchemaBuildMetadata::default()
231            },
232        )
233    }
234
235    /// Build a compact positional layout for a blocking or spill boundary.
236    /// Logical columns and hidden lookup aliases are remapped to a deduplicated
237    /// list of referenced physical slots; projecting a row through the returned
238    /// slot list shares its existing value fragments without cloning values.
239    pub fn canonical_projection(&self) -> (Self, Vec<usize>) {
240        fn remap_slot(
241            slot: usize,
242            source_slots: &mut Vec<usize>,
243            positions: &mut HashMap<usize, usize>,
244        ) -> usize {
245            if slot == NULL_SLOT {
246                return NULL_SLOT;
247            }
248            if let Some(position) = positions.get(&slot) {
249                return *position;
250            }
251            let position = source_slots.len();
252            source_slots.push(slot);
253            positions.insert(slot, position);
254            position
255        }
256
257        let mut source_slots = Vec::new();
258        let mut positions = HashMap::new();
259        let slots = self
260            .index
261            .slots
262            .iter()
263            .map(|slot| remap_slot(*slot, &mut source_slots, &mut positions))
264            .collect();
265        let mut source_aliases = self.index.aliases.iter().collect::<Vec<_>>();
266        source_aliases.sort_unstable_by_key(|(left, _)| *left);
267        let aliases = source_aliases
268            .into_iter()
269            .map(|(name, slot)| {
270                (
271                    name.clone(),
272                    remap_slot(*slot, &mut source_slots, &mut positions),
273                )
274            })
275            .collect();
276        let mut source_internal = self.index.executor_attributes.iter().collect::<Vec<_>>();
277        source_internal.sort_unstable_by_key(|(column, _)| **column);
278        let internal = source_internal
279            .into_iter()
280            .map(|(column, slot)| {
281                (
282                    *column,
283                    remap_slot(*slot, &mut source_slots, &mut positions),
284                )
285            })
286            .collect();
287        (
288            Self::from_typed_parts_with_aliases_and_exact_precedence(
289                self.columns().to_vec(),
290                self.identities().to_vec(),
291                self.column_types().to_vec(),
292                slots,
293                source_slots.len(),
294                SchemaBuildMetadata {
295                    collations: self.index.cold.collations.clone(),
296                    record_fields: self
297                        .index
298                        .cold
299                        .record_fields
300                        .iter()
301                        .filter_map(|(slot, fields)| {
302                            positions.get(slot).map(|mapped| (*mapped, fields.clone()))
303                        })
304                        .collect(),
305                    aliases,
306                    alias_types: self.index.cold.aliases.clone(),
307                    internal,
308                    internal_types: self.index.cold.executor_attribute_types.clone(),
309                    score_sources: self.index.cold.score_sources.clone(),
310                    wildcard_hidden: self.index.cold.wildcard_hidden.clone(),
311                    binding_only: self.index.cold.binding_only.clone(),
312                    row_types: self.index.cold.row_types.clone(),
313                    row_presence: self.index.cold.row_presence.clone(),
314                    open_qualifiers: self.index.cold.open_qualifiers.clone(),
315                    ..SchemaBuildMetadata::default()
316                },
317            ),
318            source_slots,
319        )
320    }
321
322    /// Rebuild a schema decoded from a positional spill record.
323    ///
324    /// `None` represents a logical or alias identity whose source was absent
325    /// and therefore resolves to SQL NULL. Every physical slot is validated
326    /// before the derived lookup indexes are constructed.
327    #[expect(
328        clippy::too_many_lines,
329        reason = "projection keeps schema and physical column positions aligned"
330    )]
331    pub fn from_physical_layout(layout: PhysicalLayout) -> SchemaLayoutResult<Self> {
332        let PhysicalLayout {
333            columns,
334            identities,
335            types,
336            slots,
337            physical_width,
338            aliases,
339            internal,
340            score_sources,
341            wildcard_hidden,
342        } = layout;
343        if columns.len() != slots.len() {
344            return Err(SchemaLayoutError(format!(
345                "physical schema has {} columns but {} logical slots",
346                columns.len(),
347                slots.len()
348            )));
349        }
350        if columns.len() != types.len() {
351            return Err(SchemaLayoutError(format!(
352                "physical schema has {} columns but {} logical types",
353                columns.len(),
354                types.len()
355            )));
356        }
357        if columns.len() != identities.len() {
358            return Err(SchemaLayoutError(format!(
359                "physical schema has {} columns but {} logical identities",
360                columns.len(),
361                identities.len()
362            )));
363        }
364        if wildcard_hidden
365            .iter()
366            .any(|position| *position >= columns.len())
367        {
368            return Err(SchemaLayoutError(
369                "physical schema wildcard-hidden position is outside logical width".into(),
370            ));
371        }
372        let slots = slots
373            .into_iter()
374            .map(|slot| match slot {
375                Some(slot) if slot < physical_width => Ok(slot),
376                Some(slot) => Err(SchemaLayoutError(format!(
377                    "physical schema logical slot {slot} is outside width {physical_width}"
378                ))),
379                None => Ok(NULL_SLOT),
380            })
381            .collect::<SchemaLayoutResult<Vec<_>>>()?;
382        let mut lookup_aliases =
383            SchemaMap::with_capacity_and_hasher(aliases.len(), ahash::RandomState::default());
384        let mut alias_types =
385            SchemaMap::with_capacity_and_hasher(aliases.len(), ahash::RandomState::default());
386        for (identity, slot, ty) in aliases {
387            let slot = match slot {
388                Some(slot) if slot < physical_width => slot,
389                Some(slot) => {
390                    return Err(SchemaLayoutError(format!(
391                        "physical schema alias `{identity:?}` slot {slot} is outside width {physical_width}"
392                    )))
393                }
394                None => NULL_SLOT,
395            };
396            if lookup_aliases.insert(identity.clone(), slot).is_some() {
397                return Err(SchemaLayoutError(format!(
398                    "physical schema contains duplicate alias `{identity:?}`"
399                )));
400            }
401            alias_types.insert(identity, ty);
402        }
403        let mut internal_slots =
404            SchemaMap::with_capacity_and_hasher(internal.len(), ahash::RandomState::default());
405        let mut internal_types =
406            SchemaMap::with_capacity_and_hasher(internal.len(), ahash::RandomState::default());
407        for (column, slot, ty) in internal {
408            let slot = match slot {
409                Some(slot) if slot < physical_width => slot,
410                Some(slot) => {
411                    return Err(SchemaLayoutError(format!(
412                        "physical schema internal attribute `{column:?}` slot {slot} is outside width {physical_width}"
413                    )))
414                }
415                None => NULL_SLOT,
416            };
417            if internal_slots.insert(column, slot).is_some() {
418                return Err(SchemaLayoutError(format!(
419                    "physical schema contains duplicate internal attribute `{column:?}`"
420                )));
421            }
422            internal_types.insert(column, ty);
423        }
424        let score_sources = score_sources
425            .into_iter()
426            .map(|(qualifier, column)| {
427                if !internal_slots.contains_key(&column) {
428                    return Err(SchemaLayoutError(format!(
429                        "physical schema score source references missing internal attribute `{column:?}`"
430                    )));
431                }
432                Ok(ScoreSource {
433                    qualifier: qualifier.map(Box::<str>::from),
434                    column,
435                })
436            })
437            .collect::<SchemaLayoutResult<Vec<_>>>()?;
438        Ok(Self::from_typed_parts_with_aliases_and_exact_precedence(
439            columns,
440            identities,
441            types,
442            slots,
443            physical_width,
444            SchemaBuildMetadata {
445                aliases: lookup_aliases,
446                alias_types,
447                internal: internal_slots,
448                internal_types,
449                score_sources,
450                wildcard_hidden: wildcard_hidden.into_iter().collect(),
451                binding_only: SchemaMap::default(),
452                ..SchemaBuildMetadata::default()
453            },
454        ))
455    }
456
457    pub fn lookup_aliases(&self) -> Vec<(&ColumnIdentity, Option<usize>)> {
458        let mut aliases = self
459            .index
460            .aliases
461            .iter()
462            .map(|(identity, slot)| (identity, (*slot != NULL_SLOT).then_some(*slot)))
463            .collect::<Vec<_>>();
464        aliases.sort_unstable_by_key(|(identity, _)| *identity);
465        aliases
466    }
467
468    pub fn lookup_aliases_with_types(
469        &self,
470    ) -> Vec<(&ColumnIdentity, Option<usize>, Option<&ColumnType>)> {
471        self.lookup_aliases()
472            .into_iter()
473            .map(|(identity, slot)| {
474                (
475                    identity,
476                    slot,
477                    self.index
478                        .cold
479                        .aliases
480                        .get(identity)
481                        .and_then(Option::as_ref),
482                )
483            })
484            .collect()
485    }
486
487    pub fn internal_columns_with_types(
488        &self,
489    ) -> Vec<(
490        crate::ast::InternalColumnRef,
491        Option<usize>,
492        Option<&ColumnType>,
493    )> {
494        let mut columns = self
495            .index
496            .executor_attributes
497            .iter()
498            .map(|(column, slot)| {
499                (
500                    *column,
501                    (*slot != NULL_SLOT).then_some(*slot),
502                    self.index
503                        .cold
504                        .executor_attribute_types
505                        .get(column)
506                        .and_then(Option::as_ref),
507                )
508            })
509            .collect::<Vec<_>>();
510        columns.sort_unstable_by_key(|(column, _, _)| *column);
511        columns
512    }
513
514    pub fn score_sources(
515        &self,
516    ) -> impl Iterator<Item = (Option<&str>, crate::ast::InternalColumnRef)> {
517        self.index
518            .cold
519            .score_sources
520            .iter()
521            .map(|source| (source.qualifier.as_deref(), source.column))
522    }
523
524    pub fn wildcard_hidden_positions(&self) -> impl Iterator<Item = usize> + '_ {
525        self.index.cold.wildcard_hidden.iter().copied()
526    }
527
528    /// Select logical input positions and attach hidden lookup identities without copying their physical values. Existing hidden aliases are retained, so nested join qualification survives another remap.
529    pub fn remap_positions(
530        input: &Self,
531        columns: &[(String, usize)],
532        aliases: &[(ColumnIdentity, usize)],
533    ) -> Self {
534        let columns = columns
535            .iter()
536            .map(|(name, logical)| (name.clone(), *logical, input.column_type(*logical).cloned()))
537            .collect::<Vec<_>>();
538        Self::remap_typed_positions(input, &columns, aliases)
539    }
540
541    /// Select logical positions with explicit output types. This is used when a binder inserts an implicit coercion and the output identity no longer has the input slot's declared type.
542    pub fn remap_typed_positions(
543        input: &Self,
544        columns: &[(String, usize, Option<ColumnType>)],
545        aliases: &[(ColumnIdentity, usize)],
546    ) -> Self {
547        let mut collations = input.index.cold.collations.clone();
548        collations.clear_columns();
549        for (position, (_, source, ty)) in columns.iter().enumerate() {
550            collations.column(
551                position,
552                input.inherited_column_collation(*source),
553                ty.as_ref(),
554            );
555        }
556        let output_names = columns
557            .iter()
558            .map(|(output, _, _)| output.clone())
559            .collect::<Vec<_>>();
560        let slots = columns
561            .iter()
562            .map(|(_, logical, _)| input.slot(*logical).unwrap_or(NULL_SLOT))
563            .collect();
564        let types = columns.iter().map(|(_, _, ty)| ty.clone()).collect();
565        let identities = output_names
566            .iter()
567            .cloned()
568            .map(ColumnIdentity::unqualified)
569            .collect();
570        let wildcard_hidden = columns
571            .iter()
572            .enumerate()
573            .filter_map(|(output, (_, logical, _))| {
574                input
575                    .index
576                    .cold
577                    .wildcard_hidden
578                    .contains(logical)
579                    .then_some(output)
580            })
581            .collect();
582        let mut lookup_aliases = input.index.aliases.clone();
583        let mut alias_types = input.index.cold.aliases.clone();
584        for (identity, logical) in aliases {
585            collations.alias(
586                identity,
587                input.inherited_column_collation(*logical),
588                input.column_type(*logical),
589            );
590            lookup_aliases.insert(identity.clone(), input.slot(*logical).unwrap_or(NULL_SLOT));
591            alias_types.insert(identity.clone(), input.column_type(*logical).cloned());
592        }
593        Self::from_typed_parts_with_aliases_and_exact_precedence(
594            output_names,
595            identities,
596            types,
597            slots,
598            input.physical_width(),
599            SchemaBuildMetadata {
600                collations,
601                record_fields: input.index.cold.record_fields.clone(),
602                aliases: lookup_aliases,
603                alias_types,
604                internal: input.index.executor_attributes.clone(),
605                internal_types: input.index.cold.executor_attribute_types.clone(),
606                score_sources: input.index.cold.score_sources.clone(),
607                wildcard_hidden,
608                binding_only: input.index.cold.binding_only.clone(),
609                row_types: input.index.cold.row_types.clone(),
610                row_presence: input.index.cold.row_presence.clone(),
611                open_qualifiers: input.index.cold.open_qualifiers.clone(),
612                ..SchemaBuildMetadata::default()
613            },
614        )
615    }
616}
617
618#[cfg(test)]
619mod capture_tests {
620    use super::*;
621    use crate::ast::InternalRelationId;
622
623    #[test]
624    fn output_capture_keeps_positional_metadata_without_sql_aliases() {
625        let fields: crate::schema::RecordFields = vec![Some(ColumnType::SmallInteger)].into();
626        let input = RowSchema::with_qualified_types(
627            "source",
628            vec!["unused".into(), "text".into(), "record".into()],
629            vec![
630                Some(ColumnType::Integer),
631                Some(ColumnType::Text),
632                Some(ColumnType::Record),
633            ],
634        )
635        .with_column_collations([None, Some(950), None])
636        .with_record_fields([(2, fields.clone())]);
637        let selected =
638            RowSchema::remap_positions(&input, &[("same".into(), 2), ("same".into(), 1)], &[]);
639        let relation = InternalRelationId::allocate();
640        let captured = RowSchema::capture_output(&selected, relation);
641        assert!(captured.is_empty());
642        assert_eq!(captured.physical_width(), 3);
643        assert_eq!(captured.internal_slot(relation.column(0)), Some(2));
644        assert_eq!(captured.internal_slot(relation.column(1)), Some(1));
645        assert_eq!(
646            captured.internal_type(relation.column(0)),
647            Some(&ColumnType::Record)
648        );
649        assert_eq!(captured.internal_collation(relation.column(1)), Some(950));
650        assert!(crate::schema::RecordFields::shares_storage(
651            captured.physical_record_fields(2).unwrap(),
652            &fields
653        ));
654        assert_eq!(captured.qualified_slot("source", "record"), None);
655        assert_eq!(captured.position("same"), None);
656        let other = InternalRelationId::allocate();
657        let second = RowSchema::capture_output(&selected, other);
658        let joined = RowSchema::join(&captured, &second, []);
659        assert_eq!(joined.internal_slot(relation.column(0)), Some(2));
660        assert_eq!(joined.internal_slot(other.column(0)), Some(5));
661    }
662
663    #[test]
664    fn output_capture_assigns_a_slot_to_implicit_null_values() {
665        let input = RowSchema::new(vec!["present".into()]);
666        let selected = RowSchema::select(&input, &[("missing".into(), "absent".into())]);
667        let relation = InternalRelationId::allocate();
668        let captured = RowSchema::capture_output(&selected, relation);
669        assert_eq!(captured.internal_slot(relation.column(0)), Some(1));
670        assert_eq!(captured.physical_width(), 2);
671        assert!(captured.is_empty());
672    }
673}