Skip to main content

uqa_sql/schema/
collations.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Selected collation metadata follows logical bindings independently of value slots.
8
9use super::{
10    ColumnIdentity, ColumnType, InternalColumnRef, RowSchema, SchemaLayoutError,
11    SchemaLayoutResult, SchemaMap,
12};
13use crate::catalog::type_metadata::pg_type_collation_oid;
14use uqa_core::memory::OwnedMap as BTreeMap;
15
16pub(super) mod composition;
17mod production;
18
19#[derive(Clone, Debug, Default, PartialEq, Eq)]
20pub(super) struct Collations(Option<Box<Bindings>>);
21
22#[derive(Clone, Debug, Default, PartialEq, Eq)]
23struct Bindings {
24    columns: BTreeMap<usize, u32>,
25    aliases: BTreeMap<ColumnIdentity, u32>,
26    internal: BTreeMap<InternalColumnRef, u32>,
27    virtual_columns: BTreeMap<ColumnIdentity, u32>,
28    memory: super::production::lease::SchemaMemory,
29}
30
31/// A selected collation belongs to a logical identity even when its physical value is NULL or shared with another identity.
32#[derive(Clone, Copy, Debug)]
33pub enum CollationBinding<'a> {
34    Column(usize),
35    Alias(&'a ColumnIdentity),
36    Internal(InternalColumnRef),
37}
38
39fn type_default(ty: Option<&ColumnType>) -> Option<u32> {
40    ty.map(|ty| u32::try_from(pg_type_collation_oid(ty)).expect("type collation identity"))
41}
42
43fn override_value(oid: Option<u32>, ty: Option<&ColumnType>) -> Option<u32> {
44    oid.filter(|oid| {
45        ty.is_some_and(|ty| {
46            crate::schema::composites::type_is_collatable(ty)
47                && type_default(Some(ty)) != Some(*oid)
48        })
49    })
50}
51
52impl Collations {
53    pub(super) fn same_physical_bindings(&self, other: &Self) -> bool {
54        let empty = Bindings::default();
55        let left = self.0.as_deref().unwrap_or(&empty);
56        let right = other.0.as_deref().unwrap_or(&empty);
57        left.columns == right.columns
58            && left.aliases == right.aliases
59            && left.internal == right.internal
60    }
61
62    pub(super) fn joined(left: &RowSchema, right: &RowSchema) -> Self {
63        let mut result = left.index.cold.collations.clone();
64        if let Some(target) = &mut result.0 {
65            if !target.aliases.is_empty() {
66                for identity in right.index.cold.aliases.keys() {
67                    target.aliases.remove(identity);
68                }
69            }
70            if !target.virtual_columns.is_empty() {
71                for identity in right.index.cold.binding_only.keys() {
72                    target.virtual_columns.remove(identity);
73                }
74            }
75        }
76        if let Some(source) = &right.index.cold.collations.0 {
77            let target = result.0.get_or_insert_with(Default::default);
78            target.columns.extend(
79                source
80                    .columns
81                    .iter()
82                    .map(|(position, oid)| (left.len() + position, *oid)),
83            );
84            target.aliases.extend(
85                source
86                    .aliases
87                    .iter()
88                    .map(|(identity, oid)| (identity.clone(), *oid)),
89            );
90            target
91                .internal
92                .extend(source.internal.iter().map(|(column, oid)| (*column, *oid)));
93            target.virtual_columns.extend(
94                source
95                    .virtual_columns
96                    .iter()
97                    .map(|(identity, oid)| (identity.clone(), *oid)),
98            );
99        }
100        result.compact();
101        result
102    }
103
104    fn compact(&mut self) {
105        if self.0.as_ref().is_some_and(|bindings| {
106            bindings.columns.is_empty()
107                && bindings.aliases.is_empty()
108                && bindings.internal.is_empty()
109                && bindings.virtual_columns.is_empty()
110        }) {
111            self.0 = None;
112        }
113    }
114
115    pub(super) fn column(&mut self, position: usize, oid: Option<u32>, ty: Option<&ColumnType>) {
116        let value = override_value(oid, ty);
117        if let Some(value) = value {
118            self.0
119                .get_or_insert_with(Default::default)
120                .columns
121                .insert(position, value);
122        } else if let Some(bindings) = &mut self.0 {
123            bindings.columns.remove(&position);
124        }
125    }
126
127    pub(super) fn alias(
128        &mut self,
129        identity: &ColumnIdentity,
130        oid: Option<u32>,
131        ty: Option<&ColumnType>,
132    ) {
133        let value = override_value(oid, ty);
134        if let Some(value) = value {
135            self.0
136                .get_or_insert_with(Default::default)
137                .aliases
138                .insert(identity.clone(), value);
139        } else if let Some(bindings) = &mut self.0 {
140            bindings.aliases.remove(identity);
141        }
142    }
143
144    pub(super) fn internal(
145        &mut self,
146        column: InternalColumnRef,
147        oid: Option<u32>,
148        ty: Option<&ColumnType>,
149    ) {
150        let value = override_value(oid, ty);
151        if let Some(value) = value {
152            self.0
153                .get_or_insert_with(Default::default)
154                .internal
155                .insert(column, value);
156        } else if let Some(bindings) = &mut self.0 {
157            bindings.internal.remove(&column);
158        }
159    }
160
161    pub(super) fn virtual_column(
162        &mut self,
163        identity: &ColumnIdentity,
164        oid: Option<u32>,
165        ty: Option<&ColumnType>,
166    ) {
167        let value = override_value(oid, ty);
168        if let Some(value) = value {
169            self.0
170                .get_or_insert_with(Default::default)
171                .virtual_columns
172                .insert(identity.clone(), value);
173        } else if let Some(bindings) = &mut self.0 {
174            bindings.virtual_columns.remove(identity);
175        }
176    }
177
178    pub(super) fn clear_columns(&mut self) {
179        if let Some(bindings) = &mut self.0 {
180            bindings.columns.clear();
181        }
182    }
183
184    /// Schema construction discards metadata for removed identities and defaults. Schemas with only type-default collations have no extra allocation.
185    pub(super) fn retain(
186        &mut self,
187        columns: &[Option<ColumnType>],
188        aliases: &SchemaMap<ColumnIdentity, Option<ColumnType>>,
189        internal: &SchemaMap<InternalColumnRef, Option<ColumnType>>,
190        virtual_columns: &SchemaMap<ColumnIdentity, Option<ColumnType>>,
191    ) {
192        let Some(bindings) = &mut self.0 else {
193            return;
194        };
195        bindings.columns.retain(|position, oid| {
196            override_value(Some(*oid), columns.get(*position).and_then(Option::as_ref)).is_some()
197        });
198        bindings.aliases.retain(|identity, oid| {
199            override_value(Some(*oid), aliases.get(identity).and_then(Option::as_ref)).is_some()
200        });
201        bindings.internal.retain(|column, oid| {
202            override_value(Some(*oid), internal.get(column).and_then(Option::as_ref)).is_some()
203        });
204        bindings.virtual_columns.retain(|identity, oid| {
205            override_value(
206                Some(*oid),
207                virtual_columns.get(identity).and_then(Option::as_ref),
208            )
209            .is_some()
210        });
211        if bindings.columns.is_empty()
212            && bindings.aliases.is_empty()
213            && bindings.internal.is_empty()
214            && bindings.virtual_columns.is_empty()
215        {
216            self.0 = None;
217        }
218    }
219}
220
221impl RowSchema {
222    /// Observe retained expression metadata or a direct logical reference, including selected clauses, static bindings and executor attributes without a visible output position.
223    pub fn input_collation(&self, expression: &crate::ScalarExpr) -> Option<u32> {
224        super::ScalarTypeSchema::input_collation(self, expression)
225    }
226
227    /// Bind a direct scalar reference without confusing its SQL identity with another logical column that shares the same physical value. Static binding-only names remain with expression evaluation.
228    pub fn projection_input(&self, expression: &crate::ScalarExpr) -> Option<super::ProjectedSlot> {
229        let (logical, alias) = match expression {
230            crate::ScalarExpr::Column(name) => {
231                if self.column_is_ambiguous(name) {
232                    return None;
233                }
234                let logical = self.unqualified_position(name);
235                (
236                    logical,
237                    logical.is_none().then(|| ColumnIdentity::unqualified(name)),
238                )
239            }
240            crate::ScalarExpr::QualifiedColumn { qualifier, column } => {
241                if self.qualified_column_is_ambiguous(qualifier, column) {
242                    return None;
243                }
244                let logical = self.qualified_position(qualifier, column);
245                (
246                    logical,
247                    logical
248                        .is_none()
249                        .then(|| ColumnIdentity::qualified(qualifier, column)),
250                )
251            }
252            crate::ScalarExpr::Position(position) if *position < self.len() => {
253                (Some(*position), None)
254            }
255            _ => return None,
256        };
257        let (physical, collation) = if let Some(position) = logical {
258            (
259                self.physical_slot(position),
260                self.column_collation(position),
261            )
262        } else {
263            let identity = alias?;
264            let slot = *self.index.aliases.get(&identity)?;
265            (
266                (slot != super::NULL_SLOT).then_some(slot),
267                self.alias_collation(&identity),
268            )
269        };
270        Some(super::ProjectedSlot::BoundInput {
271            physical,
272            collation,
273        })
274    }
275
276    /// Attach already-selected column collations to an owned schema. The width and collatability must match its declared types; catalog name resolution belongs to the caller's SQL analysis.
277    pub fn with_column_collations(
278        mut self,
279        collations: impl IntoIterator<Item = Option<u32>>,
280    ) -> Self {
281        let mut width = 0;
282        let index = std::sync::Arc::make_mut(&mut self.index);
283        for (position, oid) in collations.into_iter().enumerate() {
284            assert!(
285                position < index.columns.len(),
286                "row schema column/collation width mismatch"
287            );
288            let ty = index.cold.columns[position].as_ref();
289            assert!(
290                oid.is_none_or(
291                    |oid| oid == 0 || ty.is_some_and(crate::schema::composites::type_is_collatable)
292                ),
293                "collation requires a collatable column type"
294            );
295            index.cold.collations.column(position, oid, ty);
296            width += 1;
297        }
298        assert_eq!(
299            width,
300            index.columns.len(),
301            "row schema column/collation width mismatch"
302        );
303        index.cold.collations.compact();
304        self
305    }
306
307    /// Select a collation for an existing static binding without adding a physical slot or wildcard output.
308    pub fn with_virtual_collation(
309        mut self,
310        identity: &ColumnIdentity,
311        oid: u32,
312    ) -> SchemaLayoutResult<Self> {
313        let ty = self
314            .index
315            .cold
316            .binding_only
317            .get(identity)
318            .and_then(Option::as_ref);
319        if ty.is_none_or(|ty| !crate::schema::composites::type_is_collatable(ty)) {
320            return Err(SchemaLayoutError(
321                "collation metadata requires an existing collatable virtual binding".into(),
322            ));
323        }
324        let index = std::sync::Arc::make_mut(&mut self.index);
325        index.cold.collations.virtual_column(
326            identity,
327            Some(oid),
328            index
329                .cold
330                .binding_only
331                .get(identity)
332                .and_then(Option::as_ref),
333        );
334        index.cold.collations.compact();
335        Ok(self)
336    }
337
338    pub fn column_collation(&self, position: usize) -> Option<u32> {
339        self.index
340            .cold
341            .collations
342            .0
343            .as_ref()
344            .and_then(|bindings| bindings.columns.get(&position).copied())
345            .or_else(|| type_default(self.column_type(position)))
346    }
347
348    pub fn internal_collation(&self, column: InternalColumnRef) -> Option<u32> {
349        self.index
350            .cold
351            .collations
352            .0
353            .as_ref()
354            .and_then(|bindings| bindings.internal.get(&column).copied())
355            .or_else(|| type_default(self.internal_type(column)))
356    }
357
358    pub fn collation_of(&self, name: &str) -> Option<u32> {
359        if self.column_is_ambiguous(name) {
360            return None;
361        }
362        self.index
363            .unqualified
364            .get(name)
365            .and_then(|position| self.column_collation(*position))
366            .or_else(|| self.hidden_collation(&ColumnIdentity::unqualified(name)))
367    }
368
369    pub fn qualified_collation(&self, qualifier: &str, name: &str) -> Option<u32> {
370        let identity = ColumnIdentity::qualified(qualifier, name);
371        self.qualified_identity_collation(&identity)
372    }
373
374    pub(crate) fn qualified_identity_collation(&self, identity: &ColumnIdentity) -> Option<u32> {
375        if self.index.ambiguous_qualified.contains(identity) {
376            return None;
377        }
378        self.index
379            .qualified
380            .get(identity)
381            .and_then(|position| self.column_collation(*position))
382            .or_else(|| self.hidden_collation(identity))
383    }
384
385    fn hidden_collation(&self, identity: &ColumnIdentity) -> Option<u32> {
386        self.alias_collation(identity)
387            .or_else(|| self.virtual_collation(identity))
388    }
389
390    pub(super) fn virtual_collation(&self, identity: &ColumnIdentity) -> Option<u32> {
391        self.index
392            .cold
393            .collations
394            .0
395            .as_ref()
396            .and_then(|bindings| bindings.virtual_columns.get(identity).copied())
397            .or_else(|| {
398                type_default(
399                    self.index
400                        .cold
401                        .binding_only
402                        .get(identity)
403                        .and_then(Option::as_ref),
404                )
405            })
406    }
407
408    pub(super) fn alias_collation(&self, identity: &ColumnIdentity) -> Option<u32> {
409        self.index
410            .cold
411            .collations
412            .0
413            .as_ref()
414            .and_then(|bindings| bindings.aliases.get(identity).copied())
415            .or_else(|| {
416                type_default(
417                    self.index
418                        .cold
419                        .aliases
420                        .get(identity)
421                        .and_then(Option::as_ref),
422                )
423            })
424    }
425
426    pub(super) fn inherited_column_collation(&self, position: usize) -> Option<u32> {
427        self.column_type(position)
428            .filter(|ty| crate::schema::composites::type_is_collatable(ty))
429            .and_then(|_| self.column_collation(position))
430    }
431
432    pub(super) fn inherited_physical_collation(&self, physical: usize) -> Option<u32> {
433        if physical == super::NULL_SLOT {
434            return None;
435        }
436        self.index
437            .slots
438            .iter()
439            .position(|slot| *slot == physical)
440            .and_then(|position| self.inherited_column_collation(position))
441            .or_else(|| {
442                self.index.aliases.iter().find_map(|(identity, slot)| {
443                    (*slot == physical
444                        && self
445                            .index
446                            .cold
447                            .aliases
448                            .get(identity)
449                            .and_then(Option::as_ref)
450                            .is_some_and(crate::schema::composites::type_is_collatable))
451                    .then(|| self.alias_collation(identity))
452                    .flatten()
453                })
454            })
455            .or_else(|| {
456                self.index
457                    .executor_attributes
458                    .iter()
459                    .find_map(|(column, slot)| {
460                        (*slot == physical
461                            && self
462                                .internal_type(*column)
463                                .is_some_and(crate::schema::composites::type_is_collatable))
464                        .then(|| self.internal_collation(*column))
465                        .flatten()
466                    })
467            })
468    }
469
470    /// Physical spill metadata excludes static name-binding-only identities, like the existing spill type layout. Type defaults need no extra record payload.
471    pub fn collation_overrides(&self) -> impl Iterator<Item = (CollationBinding<'_>, u32)> {
472        self.index.cold.collations.0.iter().flat_map(|bindings| {
473            bindings
474                .columns
475                .iter()
476                .map(|(column, oid)| (CollationBinding::Column(*column), *oid))
477                .chain(
478                    bindings
479                        .aliases
480                        .iter()
481                        .map(|(identity, oid)| (CollationBinding::Alias(identity), *oid)),
482                )
483                .chain(
484                    bindings
485                        .internal
486                        .iter()
487                        .map(|(column, oid)| (CollationBinding::Internal(*column), *oid)),
488                )
489        })
490    }
491
492    /// Restore one selected collation only for a binding that exists in this layout. Invalid spill metadata cannot invent columns or attach a collation to a noncollatable type.
493    pub fn with_collation_override(
494        mut self,
495        binding: CollationBinding<'_>,
496        oid: u32,
497    ) -> SchemaLayoutResult<Self> {
498        let ty = match binding {
499            CollationBinding::Column(position) => self.column_type(position),
500            CollationBinding::Alias(identity) => self
501                .index
502                .cold
503                .aliases
504                .get(identity)
505                .and_then(Option::as_ref),
506            CollationBinding::Internal(column) => self.internal_type(column),
507        };
508        if ty.is_none_or(|ty| !crate::schema::composites::type_is_collatable(ty)) {
509            return Err(SchemaLayoutError(
510                "collation metadata requires an existing collatable binding".into(),
511            ));
512        }
513        let value = override_value(Some(oid), ty);
514        let index = std::sync::Arc::make_mut(&mut self.index);
515        match binding {
516            CollationBinding::Column(position) => {
517                index.cold.collations.column(
518                    position,
519                    value,
520                    index.cold.columns[position].as_ref(),
521                );
522            }
523            CollationBinding::Alias(identity) => index.cold.collations.alias(
524                identity,
525                value,
526                index.cold.aliases.get(identity).and_then(Option::as_ref),
527            ),
528            CollationBinding::Internal(column) => index.cold.collations.internal(
529                column,
530                value,
531                index
532                    .cold
533                    .executor_attribute_types
534                    .get(&column)
535                    .and_then(Option::as_ref),
536            ),
537        }
538        index.cold.collations.compact();
539        Ok(self)
540    }
541}
542
543#[cfg(test)]
544mod tests;