Skip to main content

uqa_sql/schema/
schema_construction.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Construction and indexing of immutable row schemas.
8
9use super::{
10    Arc, ColumnIdentity, ColumnType, RowSchema, SchemaBuildMetadata, SchemaColdMetadata,
11    SchemaIndex, NULL_SLOT,
12};
13use crate::ast::InternalRelationId;
14use crate::schema::{SchemaMap, SchemaSet};
15
16#[cfg(test)]
17thread_local! {
18    static SCHEMA_BUILDS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
19}
20
21#[cfg(test)]
22pub(super) fn count_builds<T>(build: impl FnOnce() -> T) -> (T, usize) {
23    let before = SCHEMA_BUILDS.get();
24    let result = build();
25    (result, SCHEMA_BUILDS.get() - before)
26}
27
28impl Default for RowSchema {
29    fn default() -> Self {
30        Self::new(Vec::new())
31    }
32}
33
34impl From<Vec<String>> for RowSchema {
35    fn from(columns: Vec<String>) -> Self {
36        Self::new(columns)
37    }
38}
39
40impl RowSchema {
41    pub fn new(columns: Vec<String>) -> Self {
42        let width = columns.len();
43        let identities = columns
44            .iter()
45            .cloned()
46            .map(ColumnIdentity::unqualified)
47            .collect();
48        Self::from_parts(columns, identities, (0..width).collect(), width)
49    }
50
51    /// Build a positional schema with statically bound SQL types.
52    pub fn with_types(columns: Vec<String>, types: Vec<Option<ColumnType>>) -> Self {
53        let width = columns.len();
54        assert_eq!(width, types.len(), "row schema column/type width mismatch");
55        let identities = columns
56            .iter()
57            .cloned()
58            .map(ColumnIdentity::unqualified)
59            .collect();
60        Self::from_typed_parts_with_aliases_and_exact_precedence(
61            columns,
62            identities,
63            types,
64            (0..width).collect(),
65            width,
66            SchemaBuildMetadata::default(),
67        )
68    }
69
70    /// Build a positional schema whose visible columns all belong to one relation qualifier while retaining their public names verbatim.
71    pub fn with_qualified_types(
72        qualifier: &str,
73        columns: Vec<String>,
74        types: Vec<Option<ColumnType>>,
75    ) -> Self {
76        let identities = columns
77            .iter()
78            .cloned()
79            .map(|column| ColumnIdentity::qualified(qualifier, column))
80            .collect();
81        Self::with_identities(columns, identities, types)
82    }
83
84    /// Build a positional source from its catalog declarations without discarding selected column collations. Attribute numbers remain a catalog identity, independent of these query positions.
85    pub fn with_column_definitions(
86        qualifier: Option<&str>,
87        columns: &[crate::ast::ColumnDef],
88    ) -> Self {
89        Self::with_column_metadata(
90            qualifier,
91            columns.iter().map(|column| {
92                (
93                    column.name.clone(),
94                    Some(column.ty.clone()),
95                    column.collation_oid,
96                )
97            }),
98        )
99    }
100
101    /// Build a positional source while selecting names, types and collations together. This accepts projected, aliased and system columns without a second declaration lookup or a dense collation buffer.
102    pub fn with_column_metadata(
103        qualifier: Option<&str>,
104        columns: impl IntoIterator<Item = (String, Option<ColumnType>, Option<u32>)>,
105    ) -> Self {
106        let columns = columns.into_iter();
107        let capacity = columns.size_hint().0;
108        let mut names = Vec::with_capacity(capacity);
109        let mut identities = Vec::with_capacity(capacity);
110        let mut types = Vec::with_capacity(capacity);
111        let mut metadata = SchemaBuildMetadata::default();
112        for (name, ty, oid) in columns {
113            assert!(
114                oid.is_none_or(|oid| oid == 0
115                    || ty
116                        .as_ref()
117                        .is_some_and(super::composites::type_is_collatable)),
118                "collation requires a collatable column type"
119            );
120            metadata.collations.column(names.len(), oid, ty.as_ref());
121            identities.push(qualifier.map_or_else(
122                || ColumnIdentity::unqualified(&name),
123                |qualifier| ColumnIdentity::qualified(qualifier, &name),
124            ));
125            names.push(name);
126            types.push(ty);
127        }
128        let width = names.len();
129        Self::from_typed_parts_with_aliases_and_exact_precedence(
130            names,
131            identities,
132            types,
133            (0..width).collect(),
134            width,
135            metadata,
136        )
137    }
138
139    /// Build a positional schema from explicit structured identities.
140    pub fn with_identities(
141        columns: Vec<String>,
142        identities: Vec<ColumnIdentity>,
143        types: Vec<Option<ColumnType>>,
144    ) -> Self {
145        let width = columns.len();
146        assert_eq!(
147            width,
148            identities.len(),
149            "row schema column/identity width mismatch"
150        );
151        assert_eq!(width, types.len(), "row schema column/type width mismatch");
152        Self::from_typed_parts_with_aliases_and_exact_precedence(
153            columns,
154            identities,
155            types,
156            (0..width).collect(),
157            width,
158            SchemaBuildMetadata::default(),
159        )
160    }
161
162    /// Build a physical row layout whose values are addressable only through
163    /// an opaque internal relation identity. It contributes no SQL-visible
164    /// columns and therefore cannot affect `*` expansion or name binding.
165    pub fn with_internal_relation_types(
166        relation: InternalRelationId,
167        types: Vec<Option<ColumnType>>,
168    ) -> Self {
169        Self::with_internal_relation_metadata(relation, types.into_iter().map(|ty| (ty, None)))
170    }
171
172    /// Build executor-only inputs with the selected collation of each logical attribute, including NULL values.
173    pub fn with_internal_relation_metadata(
174        relation: InternalRelationId,
175        columns: impl IntoIterator<Item = (Option<ColumnType>, Option<u32>)>,
176    ) -> Self {
177        let mut metadata = SchemaBuildMetadata::default();
178        let mut width = 0;
179        for (position, (ty, oid)) in columns.into_iter().enumerate() {
180            assert!(
181                oid.is_none_or(|oid| oid == 0
182                    || ty
183                        .as_ref()
184                        .is_some_and(super::composites::type_is_collatable)),
185                "collation requires a collatable column type"
186            );
187            let column = relation.column(position);
188            metadata.collations.internal(column, oid, ty.as_ref());
189            metadata.internal.insert(column, position);
190            metadata.internal_types.insert(column, ty);
191            width += 1;
192        }
193        Self::from_typed_parts_with_aliases_and_exact_precedence(
194            Vec::new(),
195            Vec::new(),
196            Vec::new(),
197            Vec::new(),
198            width,
199            metadata,
200        )
201    }
202
203    /// Build the lookup semantics of a named compatibility row. An exact bare
204    /// key in a map is authoritative even when qualified metadata keys share
205    /// its suffix; physical relational schemas continue to treat multiple
206    /// visible owners as ambiguous.
207    pub fn from_named_columns(columns: Vec<String>) -> Self {
208        let width = columns.len();
209        let identities = columns
210            .iter()
211            .cloned()
212            .map(ColumnIdentity::unqualified)
213            .collect();
214        Self::from_parts_with_aliases_and_exact_precedence(
215            columns,
216            identities,
217            (0..width).collect(),
218            width,
219            SchemaBuildMetadata {
220                exact_unqualified_precedence: true,
221                ..SchemaBuildMetadata::default()
222            },
223        )
224    }
225
226    fn from_parts(
227        columns: Vec<String>,
228        identities: Vec<ColumnIdentity>,
229        slots: Vec<usize>,
230        physical_width: usize,
231    ) -> Self {
232        Self::from_parts_with_aliases(
233            columns,
234            identities,
235            slots,
236            physical_width,
237            SchemaMap::default(),
238        )
239    }
240
241    fn from_parts_with_aliases(
242        columns: Vec<String>,
243        identities: Vec<ColumnIdentity>,
244        slots: Vec<usize>,
245        physical_width: usize,
246        aliases: SchemaMap<ColumnIdentity, usize>,
247    ) -> Self {
248        Self::from_parts_with_aliases_and_exact_precedence(
249            columns,
250            identities,
251            slots,
252            physical_width,
253            SchemaBuildMetadata {
254                aliases,
255                ..SchemaBuildMetadata::default()
256            },
257        )
258    }
259
260    fn from_parts_with_aliases_and_exact_precedence(
261        columns: Vec<String>,
262        identities: Vec<ColumnIdentity>,
263        slots: Vec<usize>,
264        physical_width: usize,
265        metadata: SchemaBuildMetadata,
266    ) -> Self {
267        let types = vec![None; columns.len()];
268        Self::from_typed_parts_with_aliases_and_exact_precedence(
269            columns,
270            identities,
271            types,
272            slots,
273            physical_width,
274            metadata,
275        )
276    }
277
278    pub(super) fn from_typed_parts_with_aliases_and_exact_precedence(
279        columns: Vec<String>,
280        identities: Vec<ColumnIdentity>,
281        types: Vec<Option<ColumnType>>,
282        slots: Vec<usize>,
283        physical_width: usize,
284        metadata: SchemaBuildMetadata,
285    ) -> Self {
286        #[cfg(test)]
287        SCHEMA_BUILDS.set(SCHEMA_BUILDS.get() + 1);
288        let SchemaBuildMetadata {
289            mut collations,
290            row_types,
291            record_fields,
292            aliases,
293            alias_types,
294            internal,
295            internal_types,
296            score_sources,
297            wildcard_hidden,
298            binding_only,
299            open_qualifiers,
300            exact_unqualified_precedence,
301            extra_ambiguous_unqualified,
302            extra_ambiguous_qualified,
303            local_width,
304        } = metadata;
305        collations.retain(&types, &alias_types, &internal_types, &binding_only);
306        debug_assert_eq!(columns.len(), slots.len());
307        debug_assert_eq!(columns.len(), identities.len());
308        debug_assert_eq!(columns.len(), types.len());
309        debug_assert!(wildcard_hidden
310            .iter()
311            .all(|position| *position < columns.len()));
312        let identity_layout = physical_width == columns.len()
313            && slots
314                .iter()
315                .enumerate()
316                .all(|(position, slot)| position == *slot);
317        let hasher = ahash::RandomState::default;
318        let mut exact = SchemaMap::with_capacity_and_hasher(columns.len(), hasher());
319        let mut unqualified = SchemaMap::with_capacity_and_hasher(columns.len(), hasher());
320        let mut qualified = SchemaMap::with_capacity_and_hasher(columns.len(), hasher());
321        // A name owned by more than one logical column is ambiguous; the replaced entry of each lookup map records the repetition without a second map per name.
322        let mut ambiguous_unqualified = SchemaSet::with_hasher(hasher());
323        let mut ambiguous_qualified = SchemaSet::with_hasher(hasher());
324        for (logical, (name, identity)) in columns.iter().zip(&identities).enumerate() {
325            // Later writes to the same named field replace the value in a
326            // ResultRow. Schema transforms preserve that contract.
327            exact.insert(Box::<str>::from(name.as_str()), logical);
328            if unqualified
329                .insert(identity.column.clone(), logical)
330                .is_some()
331            {
332                ambiguous_unqualified.insert(identity.column.clone());
333            }
334            if identity.qualifier.is_some() && qualified.insert(identity.clone(), logical).is_some()
335            {
336                ambiguous_qualified.insert(identity.clone());
337            }
338        }
339        for slot in aliases.values() {
340            debug_assert!(*slot == NULL_SLOT || *slot < physical_width);
341        }
342        for slot in internal.values() {
343            debug_assert!(*slot == NULL_SLOT || *slot < physical_width);
344        }
345        if exact_unqualified_precedence {
346            ambiguous_unqualified.retain(|column| {
347                !identities
348                    .iter()
349                    .any(|identity| identity.qualifier.is_none() && identity.column == *column)
350            });
351        }
352        ambiguous_unqualified.extend(extra_ambiguous_unqualified);
353        ambiguous_qualified.extend(extra_ambiguous_qualified);
354        Self {
355            index: Arc::new(SchemaIndex {
356                columns: columns.into_boxed_slice(),
357                identities: identities.into_boxed_slice(),
358                slots: slots.into_boxed_slice(),
359                physical_width,
360                exact,
361                unqualified,
362                qualified,
363                aliases,
364                executor_attributes: internal,
365                ambiguous_unqualified,
366                ambiguous_qualified,
367                cold: Box::new(SchemaColdMetadata {
368                    collations,
369                    row_types,
370                    record_fields,
371                    columns: types.into_boxed_slice(),
372                    aliases: alias_types,
373                    executor_attribute_types: internal_types,
374                    score_sources,
375                    wildcard_hidden,
376                    binding_only,
377                    open_qualifiers,
378                    identity_layout,
379                    local_width,
380                }),
381            }),
382        }
383    }
384}