Skip to main content

uqa_sql/schema/
name_binding.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Static SQL name and type binding over a physical row schema.
8
9use crate::ast::{ColumnType, InternalColumnRef};
10
11use super::{ColumnIdentity, RowSchema, SchemaBuildMetadata, ScoreSource, NULL_SLOT};
12
13impl RowSchema {
14    /// Whether this schema exposes any SQL name or whole-row namespace, including hidden aliases and names without physical slots.
15    pub(crate) fn has_sql_bindings(&self) -> bool {
16        !self.index.columns.is_empty()
17            || self.index.cold.lateral_restrictions.is_some()
18            || !self.index.aliases.is_empty()
19            || !self.index.ambiguous_unqualified.is_empty()
20            || !self.index.ambiguous_qualified.is_empty()
21            || !self.index.cold.binding_only.is_empty()
22            || !self.index.cold.open_qualifiers.is_empty()
23            || self.index.cold.row_types.qualifiers().next().is_some()
24            || !self.index.cold.score_sources.is_empty()
25            || self.whole_row_presences().next().is_some()
26    }
27
28    /// Bind every SQL-visible column to one relation qualifier while preserving executor-only internal attributes and rebinding carried retrieval scores to the same relation boundary.
29    pub fn with_relation_qualifier(input: &Self, qualifier: &str) -> Self {
30        let identities = input
31            .columns()
32            .iter()
33            .cloned()
34            .map(|column| ColumnIdentity::qualified(qualifier, column))
35            .collect();
36        let score_sources = input
37            .index
38            .cold
39            .score_sources
40            .iter()
41            .map(|source| ScoreSource {
42                qualifier: Some(Box::<str>::from(qualifier)),
43                column: source.column,
44            })
45            .collect();
46        Self::from_typed_parts_with_aliases_and_exact_precedence(
47            input.columns().to_vec(),
48            identities,
49            input.column_types().to_vec(),
50            input.index.slots.to_vec(),
51            input.physical_width(),
52            SchemaBuildMetadata {
53                collations: input.index.cold.collations.clone(),
54                row_types: input.index.cold.row_types.requalified(input, qualifier),
55                record_fields: input.index.cold.record_fields.clone(),
56                lateral_restrictions: Self::requalified_column_names(input),
57                internal: input.index.executor_attributes.clone(),
58                internal_types: input.index.cold.executor_attribute_types.clone(),
59                score_sources,
60                open_qualifiers: input
61                    .columns_are_open(None)
62                    .then(|| Some(Box::<str>::from(qualifier)))
63                    .into_iter()
64                    .collect(),
65                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
66                ..SchemaBuildMetadata::default()
67            },
68        )
69    }
70
71    /// Whether a visible or hidden lookup identity belongs to `qualifier`.
72    #[must_use]
73    pub fn has_qualifier(&self, qualifier: &str) -> bool {
74        self.lateral_qualifier_is_ambiguous(qualifier)
75            || self
76                .index
77                .identities
78                .iter()
79                .chain(self.index.aliases.keys())
80                .chain(self.index.cold.binding_only.keys())
81                .any(|identity| identity.qualifier() == Some(qualifier))
82            || self.columns_are_open(Some(qualifier))
83            || self.index.cold.row_types.contains(qualifier)
84            || self.whole_row_presence(qualifier).is_some()
85    }
86
87    /// Whether a visible, aliased, or static binding-only identity contains this exact unqualified column, independently of its declared type.
88    #[must_use]
89    pub fn has_unqualified_column(&self, column: &str) -> bool {
90        let identity = ColumnIdentity::unqualified(column);
91        self.index.unqualified.contains_key(column)
92            || self.index.aliases.contains_key(&identity)
93            || self.index.cold.binding_only.contains_key(&identity)
94    }
95
96    /// Whether a visible or hidden lookup identity contains this exact qualified column, independently of its static type or ambiguity.
97    #[must_use]
98    pub fn has_qualified_column(&self, qualifier: &str, column: &str) -> bool {
99        let identity = ColumnIdentity::qualified(qualifier, column);
100        self.index.qualified.contains_key(&identity)
101            || self.index.aliases.contains_key(&identity)
102            || self.index.cold.binding_only.contains_key(&identity)
103    }
104
105    /// Iterate over static name-binding identities that deliberately have no physical value slot or wildcard visibility.
106    pub fn typed_virtual_identities(
107        &self,
108    ) -> impl Iterator<Item = (&ColumnIdentity, Option<&ColumnType>)> {
109        self.index
110            .cold
111            .binding_only
112            .iter()
113            .map(|(identity, ty)| (identity, ty.as_ref()))
114    }
115
116    /// Iterate over hidden lookup aliases that resolve to physical value slots while retaining their declared SQL types.
117    pub fn typed_physical_alias_identities(
118        &self,
119    ) -> impl Iterator<Item = (&ColumnIdentity, Option<&ColumnType>)> {
120        self.index.aliases.keys().map(|identity| {
121            (
122                identity,
123                self.index
124                    .cold
125                    .aliases
126                    .get(identity)
127                    .and_then(Option::as_ref),
128            )
129        })
130    }
131
132    /// Resolve an unqualified logical identity to its static type.
133    pub fn type_of(&self, name: &str) -> Option<&ColumnType> {
134        if self.index.ambiguous_unqualified.contains(name) {
135            return None;
136        }
137        self.index
138            .unqualified
139            .get(name)
140            .and_then(|logical| self.column_type(*logical))
141            .or_else(|| {
142                self.index
143                    .cold
144                    .aliases
145                    .get(&ColumnIdentity::unqualified(name))
146                    .and_then(Option::as_ref)
147            })
148            .or_else(|| {
149                self.index
150                    .cold
151                    .binding_only
152                    .get(&ColumnIdentity::unqualified(name))
153                    .and_then(Option::as_ref)
154            })
155    }
156
157    /// Resolve a qualified logical identity to its static type.
158    pub fn qualified_type(&self, qualifier: &str, column: &str) -> Option<&ColumnType> {
159        let identity = ColumnIdentity::qualified(qualifier, column);
160        if self.index.ambiguous_qualified.contains(&identity) {
161            return None;
162        }
163        self.index
164            .qualified
165            .get(&identity)
166            .and_then(|logical| self.column_type(*logical))
167            .or_else(|| {
168                self.index
169                    .cold
170                    .aliases
171                    .get(&identity)
172                    .and_then(Option::as_ref)
173            })
174            .or_else(|| {
175                self.index
176                    .cold
177                    .binding_only
178                    .get(&identity)
179                    .and_then(Option::as_ref)
180            })
181    }
182
183    pub fn column_is_ambiguous(&self, name: &str) -> bool {
184        self.index.ambiguous_unqualified.contains(name)
185    }
186
187    pub fn qualified_column_is_ambiguous(&self, qualifier: &str, column: &str) -> bool {
188        self.index
189            .ambiguous_qualified
190            .contains(&ColumnIdentity::qualified(qualifier, column))
191    }
192
193    /// Add hidden structured lookup identities for existing logical positions.
194    pub fn with_identity_aliases(input: &Self, aliases: &[(ColumnIdentity, usize)]) -> Self {
195        let mut collations = input.index.cold.collations.clone();
196        let mut lookup_aliases = input.index.aliases.clone();
197        let mut alias_types = input.index.cold.aliases.clone();
198        for (identity, logical) in aliases {
199            collations.alias(
200                identity,
201                input.inherited_column_collation(*logical),
202                input.column_type(*logical),
203            );
204            lookup_aliases.insert(identity.clone(), input.slot(*logical).unwrap_or(NULL_SLOT));
205            alias_types.insert(identity.clone(), input.column_type(*logical).cloned());
206        }
207        Self::from_typed_parts_with_aliases_and_exact_precedence(
208            input.columns().to_vec(),
209            input.identities().to_vec(),
210            input.column_types().to_vec(),
211            input.index.slots.to_vec(),
212            input.physical_width(),
213            SchemaBuildMetadata {
214                collations,
215                record_fields: input.index.cold.record_fields.clone(),
216                aliases: lookup_aliases,
217                alias_types,
218                internal: input.index.executor_attributes.clone(),
219                internal_types: input.index.cold.executor_attribute_types.clone(),
220                score_sources: input.index.cold.score_sources.clone(),
221                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
222                binding_only: input.index.cold.binding_only.clone(),
223                lateral_restrictions: input.index.cold.lateral_restrictions.clone(),
224                row_types: input.index.cold.row_types.clone(),
225                row_presence: input.index.cold.row_presence.clone(),
226                open_qualifiers: input.index.cold.open_qualifiers.clone(),
227                extra_ambiguous_unqualified: input.index.ambiguous_unqualified.clone(),
228                extra_ambiguous_qualified: input.index.ambiguous_qualified.clone(),
229                ..SchemaBuildMetadata::default()
230            },
231        )
232    }
233
234    /// Add hidden SQL lookup identities that point at explicit physical slots.
235    /// Unlike [`Self::with_identity_aliases`], these slots do not need a
236    /// SQL-visible logical column owner.
237    pub fn with_physical_identity_aliases(
238        input: &Self,
239        aliases: &[(ColumnIdentity, usize, Option<ColumnType>)],
240    ) -> Self {
241        let mut collations = input.index.cold.collations.clone();
242        let mut lookup_aliases = input.index.aliases.clone();
243        let mut alias_types = input.index.cold.aliases.clone();
244        for (identity, slot, ty) in aliases {
245            assert!(
246                *slot < input.physical_width(),
247                "physical identity alias is outside row width"
248            );
249            collations.alias(
250                identity,
251                input.inherited_physical_collation(*slot),
252                ty.as_ref(),
253            );
254            lookup_aliases.insert(identity.clone(), *slot);
255            alias_types.insert(identity.clone(), ty.clone());
256        }
257        Self::from_typed_parts_with_aliases_and_exact_precedence(
258            input.columns().to_vec(),
259            input.identities().to_vec(),
260            input.column_types().to_vec(),
261            input.index.slots.to_vec(),
262            input.physical_width(),
263            SchemaBuildMetadata {
264                collations,
265                record_fields: input.index.cold.record_fields.clone(),
266                aliases: lookup_aliases,
267                alias_types,
268                internal: input.index.executor_attributes.clone(),
269                internal_types: input.index.cold.executor_attribute_types.clone(),
270                score_sources: input.index.cold.score_sources.clone(),
271                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
272                binding_only: input.index.cold.binding_only.clone(),
273                lateral_restrictions: input.index.cold.lateral_restrictions.clone(),
274                row_types: input.index.cold.row_types.clone(),
275                row_presence: input.index.cold.row_presence.clone(),
276                open_qualifiers: input.index.cold.open_qualifiers.clone(),
277                ..SchemaBuildMetadata::default()
278            },
279        )
280    }
281
282    /// Add executor-only relation attributes at explicit physical slots.
283    pub fn with_physical_internal_aliases(
284        input: &Self,
285        aliases: &[(InternalColumnRef, usize, Option<ColumnType>)],
286    ) -> Self {
287        for (_, slot, _) in aliases {
288            assert!(
289                *slot < input.physical_width(),
290                "physical internal alias is outside row width"
291            );
292        }
293        Self::with_internal_alias_slots(input, aliases)
294    }
295
296    /// Capture named attributes under structural identities before a descendant namespace can shadow their SQL spelling. Typed virtual attributes retain their type and absence of a physical slot.
297    pub fn with_named_internal_aliases(
298        input: &Self,
299        aliases: &[(InternalColumnRef, ColumnIdentity)],
300    ) -> Self {
301        let slots: Vec<_> = aliases
302            .iter()
303            .filter_map(|(column, identity)| {
304                if input.has_internal_column(*column) {
305                    return None;
306                }
307                let qualifier = identity.qualifier()?;
308                if !input.has_qualified_column(qualifier, identity.column()) {
309                    return None;
310                }
311                Some((
312                    *column,
313                    input
314                        .qualified_slot(qualifier, identity.column())
315                        .unwrap_or(NULL_SLOT),
316                    input.qualified_type(qualifier, identity.column()).cloned(),
317                ))
318            })
319            .collect();
320        let mut result = Self::with_internal_alias_slots(input, &slots);
321        for (column, identity) in aliases {
322            if input.has_internal_column(*column) {
323                continue;
324            }
325            if let Some(qualifier) = identity.qualifier() {
326                let collation = input.qualified_collation(qualifier, identity.column());
327                let ty = input.qualified_type(qualifier, identity.column());
328                std::sync::Arc::make_mut(&mut result.index)
329                    .cold
330                    .collations
331                    .internal(*column, collation, ty);
332            }
333        }
334        result
335    }
336
337    /// Whether a physical or typed virtual attribute has already been captured.
338    pub fn has_internal_column(&self, column: InternalColumnRef) -> bool {
339        self.index.executor_attributes.contains_key(&column)
340    }
341
342    fn with_internal_alias_slots(
343        input: &Self,
344        aliases: &[(InternalColumnRef, usize, Option<ColumnType>)],
345    ) -> Self {
346        let mut collations = input.index.cold.collations.clone();
347        let mut internal = input.index.executor_attributes.clone();
348        let mut internal_types = input.index.cold.executor_attribute_types.clone();
349        for (column, slot, ty) in aliases {
350            collations.internal(
351                *column,
352                input.inherited_physical_collation(*slot),
353                ty.as_ref(),
354            );
355            internal.insert(*column, *slot);
356            internal_types.insert(*column, ty.clone());
357        }
358        Self::from_typed_parts_with_aliases_and_exact_precedence(
359            input.columns().to_vec(),
360            input.identities().to_vec(),
361            input.column_types().to_vec(),
362            input.index.slots.to_vec(),
363            input.physical_width(),
364            SchemaBuildMetadata {
365                collations,
366                record_fields: input.index.cold.record_fields.clone(),
367                aliases: input.index.aliases.clone(),
368                alias_types: input.index.cold.aliases.clone(),
369                internal,
370                internal_types,
371                score_sources: input.index.cold.score_sources.clone(),
372                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
373                binding_only: input.index.cold.binding_only.clone(),
374                lateral_restrictions: input.index.cold.lateral_restrictions.clone(),
375                local_width: input.index.cold.local_width,
376                row_types: input.index.cold.row_types.clone(),
377                row_presence: input.index.cold.row_presence.clone(),
378                open_qualifiers: input.index.cold.open_qualifiers.clone(),
379                extra_ambiguous_unqualified: input.index.ambiguous_unqualified.clone(),
380                extra_ambiguous_qualified: input.index.ambiguous_qualified.clone(),
381                ..SchemaBuildMetadata::default()
382            },
383        )
384    }
385
386    /// Restore structural identities from a row scope that occupies the trailing physical slots of this schema.
387    pub fn with_trailing_internal_aliases(input: &Self, trailing: &Self) -> Self {
388        let mut collations = input.index.cold.collations.clone();
389        let offset = input
390            .physical_width()
391            .checked_sub(trailing.physical_width())
392            .expect("trailing internal-alias scope exceeds input row width");
393        let mut internal = input.index.executor_attributes.clone();
394        let mut internal_types = input.index.cold.executor_attribute_types.clone();
395        for (column, slot) in &trailing.index.executor_attributes {
396            let slot = if *slot == NULL_SLOT {
397                NULL_SLOT
398            } else {
399                offset + *slot
400            };
401            if let Some(previous) = internal.insert(*column, slot) {
402                assert_eq!(
403                    previous, slot,
404                    "structural identity moved between row scopes"
405                );
406            }
407        }
408        for (column, ty) in &trailing.index.cold.executor_attribute_types {
409            collations.internal(*column, trailing.internal_collation(*column), ty.as_ref());
410            if let Some(previous) = internal_types.insert(*column, ty.clone()) {
411                assert_eq!(
412                    previous, *ty,
413                    "structural identity type changed between row scopes"
414                );
415            }
416        }
417        Self::from_typed_parts_with_aliases_and_exact_precedence(
418            input.columns().to_vec(),
419            input.identities().to_vec(),
420            input.column_types().to_vec(),
421            input.index.slots.to_vec(),
422            input.physical_width(),
423            SchemaBuildMetadata {
424                collations,
425                record_fields: input.index.cold.record_fields.clone(),
426                aliases: input.index.aliases.clone(),
427                alias_types: input.index.cold.aliases.clone(),
428                internal,
429                internal_types,
430                score_sources: input.index.cold.score_sources.clone(),
431                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
432                binding_only: input.index.cold.binding_only.clone(),
433                lateral_restrictions: input.index.cold.lateral_restrictions.clone(),
434                row_types: input.index.cold.row_types.clone(),
435                row_presence: input.index.cold.row_presence.clone(),
436                open_qualifiers: input.index.cold.open_qualifiers.clone(),
437                extra_ambiguous_unqualified: input.index.ambiguous_unqualified.clone(),
438                extra_ambiguous_qualified: input.index.ambiguous_qualified.clone(),
439                ..SchemaBuildMetadata::default()
440            },
441        )
442    }
443
444    /// Mark source-owned logical metadata attributes as explicitly
445    /// addressable but absent from `*` expansion. The identity is positional,
446    /// so an ordinary user column with the same text remains visible.
447    pub fn with_wildcard_hidden_positions(
448        input: &Self,
449        positions: impl IntoIterator<Item = usize>,
450    ) -> Self {
451        let wildcard_hidden = positions.into_iter().collect();
452        Self::from_typed_parts_with_aliases_and_exact_precedence(
453            input.columns().to_vec(),
454            input.identities().to_vec(),
455            input.column_types().to_vec(),
456            input.index.slots.to_vec(),
457            input.physical_width(),
458            SchemaBuildMetadata {
459                collations: input.index.cold.collations.clone(),
460                record_fields: input.index.cold.record_fields.clone(),
461                aliases: input.index.aliases.clone(),
462                alias_types: input.index.cold.aliases.clone(),
463                internal: input.index.executor_attributes.clone(),
464                internal_types: input.index.cold.executor_attribute_types.clone(),
465                score_sources: input.index.cold.score_sources.clone(),
466                wildcard_hidden,
467                binding_only: input.index.cold.binding_only.clone(),
468                lateral_restrictions: input.index.cold.lateral_restrictions.clone(),
469                row_types: input.index.cold.row_types.clone(),
470                row_presence: input.index.cold.row_presence.clone(),
471                open_qualifiers: input.index.cold.open_qualifiers.clone(),
472                ..SchemaBuildMetadata::default()
473            },
474        )
475    }
476
477    #[must_use]
478    pub fn internal_slot(&self, column: InternalColumnRef) -> Option<usize> {
479        self.index
480            .executor_attributes
481            .get(&column)
482            .copied()
483            .filter(|slot| *slot != NULL_SLOT)
484    }
485
486    /// Return the sole executor-only identity attached to a physical slot. Slots with no structural identity or with multiple aliases are intentionally unresolved.
487    #[must_use]
488    pub fn unique_internal_column_for_slot(&self, slot: usize) -> Option<InternalColumnRef> {
489        let mut columns = self
490            .index
491            .executor_attributes
492            .iter()
493            .filter_map(|(column, candidate)| (*candidate == slot).then_some(*column));
494        let column = columns.next()?;
495        columns.next().is_none().then_some(column)
496    }
497
498    #[must_use]
499    pub fn internal_type(&self, column: InternalColumnRef) -> Option<&ColumnType> {
500        self.index
501            .cold
502            .executor_attribute_types
503            .get(&column)
504            .and_then(Option::as_ref)
505    }
506
507    /// Mark an existing internal attribute as the score carried by one retrieval relation. This semantic tag is schema metadata and never enters SQL name lookup or wildcard expansion.
508    pub fn with_score_source(
509        input: &Self,
510        qualifier: Option<&str>,
511        column: InternalColumnRef,
512    ) -> Self {
513        assert!(
514            input.index.executor_attributes.contains_key(&column),
515            "score source must reference an existing internal attribute"
516        );
517        let mut score_sources = input.index.cold.score_sources.clone();
518        score_sources.retain(|source| source.column != column);
519        score_sources.push(ScoreSource {
520            qualifier: qualifier.map(Box::<str>::from),
521            column,
522        });
523        Self::from_typed_parts_with_aliases_and_exact_precedence(
524            input.columns().to_vec(),
525            input.identities().to_vec(),
526            input.column_types().to_vec(),
527            input.index.slots.to_vec(),
528            input.physical_width(),
529            SchemaBuildMetadata {
530                collations: input.index.cold.collations.clone(),
531                record_fields: input.index.cold.record_fields.clone(),
532                aliases: input.index.aliases.clone(),
533                alias_types: input.index.cold.aliases.clone(),
534                internal: input.index.executor_attributes.clone(),
535                internal_types: input.index.cold.executor_attribute_types.clone(),
536                score_sources,
537                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
538                binding_only: input.index.cold.binding_only.clone(),
539                lateral_restrictions: input.index.cold.lateral_restrictions.clone(),
540                row_types: input.index.cold.row_types.clone(),
541                row_presence: input.index.cold.row_presence.clone(),
542                open_qualifiers: input.index.cold.open_qualifiers.clone(),
543                ..SchemaBuildMetadata::default()
544            },
545        )
546    }
547
548    /// Rebind every carried score source at a relation-alias boundary while retaining its opaque internal attribute identity.
549    pub fn with_rebound_score_sources(input: &Self, qualifier: Option<&str>) -> Self {
550        let score_sources = input
551            .index
552            .cold
553            .score_sources
554            .iter()
555            .map(|source| ScoreSource {
556                qualifier: qualifier.map(Box::<str>::from),
557                column: source.column,
558            })
559            .collect();
560        Self::from_typed_parts_with_aliases_and_exact_precedence(
561            input.columns().to_vec(),
562            input.identities().to_vec(),
563            input.column_types().to_vec(),
564            input.index.slots.to_vec(),
565            input.physical_width(),
566            SchemaBuildMetadata {
567                collations: input.index.cold.collations.clone(),
568                record_fields: input.index.cold.record_fields.clone(),
569                aliases: input.index.aliases.clone(),
570                alias_types: input.index.cold.aliases.clone(),
571                internal: input.index.executor_attributes.clone(),
572                internal_types: input.index.cold.executor_attribute_types.clone(),
573                score_sources,
574                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
575                binding_only: input.index.cold.binding_only.clone(),
576                lateral_restrictions: input.index.cold.lateral_restrictions.clone(),
577                row_types: input.index.cold.row_types.clone(),
578                row_presence: input.index.cold.row_presence.clone(),
579                open_qualifiers: input.index.cold.open_qualifiers.clone(),
580                ..SchemaBuildMetadata::default()
581            },
582        )
583    }
584
585    fn matching_score_sources<'a>(
586        &'a self,
587        qualifier: Option<&'a str>,
588    ) -> impl Iterator<Item = InternalColumnRef> + 'a {
589        self.index
590            .cold
591            .score_sources
592            .iter()
593            .filter(move |source| {
594                qualifier.is_none_or(|qualifier| source.qualifier.as_deref() == Some(qualifier))
595            })
596            .map(move |source| source.column)
597    }
598
599    #[must_use]
600    pub fn score_source_column(&self, qualifier: Option<&str>) -> Option<InternalColumnRef> {
601        let mut columns = self.matching_score_sources(qualifier);
602        let column = columns.next()?;
603        columns.next().is_none().then_some(column)
604    }
605
606    #[must_use]
607    pub fn score_source_is_ambiguous(&self, qualifier: Option<&str>) -> bool {
608        let mut columns = self.matching_score_sources(qualifier);
609        columns.next().is_some() && columns.next().is_some()
610    }
611
612    #[must_use]
613    pub fn score_source_slot(&self, qualifier: Option<&str>) -> Option<usize> {
614        self.score_source_column(qualifier)
615            .and_then(|column| self.internal_slot(column))
616    }
617
618    /// Add statically typed hidden lookup identities that have no physical value slot. Visible columns and star expansion remain unchanged, while binders can resolve the identities and their declared SQL types.
619    pub fn with_typed_virtual_identities(
620        input: &Self,
621        identities: &[(ColumnIdentity, Option<ColumnType>)],
622    ) -> Self {
623        Self::with_owned_virtual_identities(input.clone(), identities)
624    }
625
626    pub(super) fn with_owned_virtual_identities(
627        mut input: Self,
628        identities: &[(ColumnIdentity, Option<ColumnType>)],
629    ) -> Self {
630        for (identity, ty) in identities {
631            let already_visible = match identity.qualifier() {
632                Some(qualifier) => input.has_qualified_column(qualifier, identity.column()),
633                None => {
634                    input.column_is_ambiguous(identity.column())
635                        || input.has_unqualified_column(identity.column())
636                }
637            };
638            if already_visible {
639                continue;
640            }
641            std::sync::Arc::make_mut(&mut input.index)
642                .cold
643                .binding_only
644                .entry(identity.clone())
645                .or_insert_with(|| ty.clone());
646        }
647        input
648    }
649
650    /// Whether a column reference resolves to one of the schema's own columns rather than to an enclosing query's column overlaid by [`Self::with_outer_schema`], as `contain_vars_of_level(n, 0)` distinguishes them.
651    pub fn resolves_local_column(&self, qualifier: Option<&str>, column: &str) -> bool {
652        let slot = match qualifier {
653            Some(qualifier) => self.qualified_slot(qualifier, column),
654            None => self.column_slot(column),
655        };
656        slot.is_some_and(|slot| self.slot_is_local(slot))
657    }
658
659    pub(crate) fn slot_is_local(&self, slot: usize) -> bool {
660        self.index.cold.local_width.is_none_or(|width| slot < width)
661    }
662
663    pub(crate) fn internal_identities(
664        &self,
665    ) -> impl Iterator<Item = (InternalColumnRef, usize)> + '_ {
666        self.index
667            .executor_attributes
668            .iter()
669            .filter_map(|(column, slot)| (*slot != super::NULL_SLOT).then_some((*column, *slot)))
670    }
671
672    /// Add binding-only identities and preserve collisions as ambiguous names. This models SQL scopes that expose a hidden generated column for explicit lookup while deliberately excluding it from wildcard expansion.
673    pub fn with_typed_conflicting_virtual_identities(
674        input: &Self,
675        identities: &[(ColumnIdentity, Option<ColumnType>)],
676    ) -> Self {
677        let mut binding_only = input.index.cold.binding_only.clone();
678        let mut ambiguous_unqualified = input.index.ambiguous_unqualified.clone();
679        let mut ambiguous_qualified = input.index.ambiguous_qualified.clone();
680        for (identity, ty) in identities {
681            if input.column_is_ambiguous(identity.column())
682                || input.has_unqualified_column(identity.column())
683            {
684                ambiguous_unqualified.insert(Box::<str>::from(identity.column()));
685            }
686            if let Some(qualifier) = identity.qualifier() {
687                if input.has_qualified_column(qualifier, identity.column()) {
688                    ambiguous_qualified.insert(identity.clone());
689                }
690            }
691            binding_only
692                .entry(identity.clone())
693                .or_insert_with(|| ty.clone());
694        }
695        Self::from_typed_parts_with_aliases_and_exact_precedence(
696            input.columns().to_vec(),
697            input.identities().to_vec(),
698            input.column_types().to_vec(),
699            input.index.slots.to_vec(),
700            input.physical_width(),
701            SchemaBuildMetadata {
702                collations: input.index.cold.collations.clone(),
703                record_fields: input.index.cold.record_fields.clone(),
704                aliases: input.index.aliases.clone(),
705                alias_types: input.index.cold.aliases.clone(),
706                internal: input.index.executor_attributes.clone(),
707                internal_types: input.index.cold.executor_attribute_types.clone(),
708                score_sources: input.index.cold.score_sources.clone(),
709                wildcard_hidden: input.index.cold.wildcard_hidden.clone(),
710                binding_only,
711                row_types: input.index.cold.row_types.clone(),
712                row_presence: input.index.cold.row_presence.clone(),
713                open_qualifiers: input.index.cold.open_qualifiers.clone(),
714                extra_ambiguous_unqualified: ambiguous_unqualified,
715                extra_ambiguous_qualified: ambiguous_qualified,
716                ..SchemaBuildMetadata::default()
717            },
718        )
719    }
720}