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        let mut schema = Self::with_identities(columns, identities, types);
82        if schema.is_empty() {
83            Arc::make_mut(&mut schema.index).cold.row_types =
84                super::relation_types::RelationRowTypes::anonymous(qualifier);
85        }
86        schema
87    }
88
89    /// Build a positional source from its catalog declarations without discarding selected column collations. Attribute numbers remain a catalog identity, independent of these query positions.
90    pub fn with_column_definitions(
91        qualifier: Option<&str>,
92        columns: &[crate::ast::ColumnDef],
93    ) -> Self {
94        Self::with_column_metadata(
95            qualifier,
96            columns.iter().map(|column| {
97                (
98                    column.name.clone(),
99                    Some(column.ty.clone()),
100                    column.collation_oid,
101                )
102            }),
103        )
104    }
105
106    /// 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.
107    pub fn with_column_metadata(
108        qualifier: Option<&str>,
109        columns: impl IntoIterator<Item = (String, Option<ColumnType>, Option<u32>)>,
110    ) -> Self {
111        let columns = columns.into_iter();
112        let capacity = columns.size_hint().0;
113        let mut names = Vec::with_capacity(capacity);
114        let mut identities = Vec::with_capacity(capacity);
115        let mut types = Vec::with_capacity(capacity);
116        let mut metadata = SchemaBuildMetadata::default();
117        for (name, ty, oid) in columns {
118            assert!(
119                oid.is_none_or(|oid| oid == 0
120                    || ty
121                        .as_ref()
122                        .is_some_and(super::composites::type_is_collatable)),
123                "collation requires a collatable column type"
124            );
125            metadata.collations.column(names.len(), oid, ty.as_ref());
126            identities.push(qualifier.map_or_else(
127                || ColumnIdentity::unqualified(&name),
128                |qualifier| ColumnIdentity::qualified(qualifier, &name),
129            ));
130            names.push(name);
131            types.push(ty);
132        }
133        let width = names.len();
134        if let Some(qualifier) = qualifier.filter(|_| width == 0) {
135            metadata.row_types = super::relation_types::RelationRowTypes::anonymous(qualifier);
136        }
137        Self::from_typed_parts_with_aliases_and_exact_precedence(
138            names,
139            identities,
140            types,
141            (0..width).collect(),
142            width,
143            metadata,
144        )
145    }
146
147    /// Build a positional schema from explicit structured identities.
148    pub fn with_identities(
149        columns: Vec<String>,
150        identities: Vec<ColumnIdentity>,
151        types: Vec<Option<ColumnType>>,
152    ) -> Self {
153        let width = columns.len();
154        assert_eq!(
155            width,
156            identities.len(),
157            "row schema column/identity width mismatch"
158        );
159        assert_eq!(width, types.len(), "row schema column/type width mismatch");
160        Self::from_typed_parts_with_aliases_and_exact_precedence(
161            columns,
162            identities,
163            types,
164            (0..width).collect(),
165            width,
166            SchemaBuildMetadata::default(),
167        )
168    }
169
170    /// Build a physical row layout whose values are addressable only through
171    /// an opaque internal relation identity. It contributes no SQL-visible
172    /// columns and therefore cannot affect `*` expansion or name binding.
173    pub fn with_internal_relation_types(
174        relation: InternalRelationId,
175        types: Vec<Option<ColumnType>>,
176    ) -> Self {
177        Self::with_internal_relation_metadata(relation, types.into_iter().map(|ty| (ty, None)))
178    }
179
180    /// Build executor-only inputs with the selected collation of each logical attribute, including NULL values.
181    pub fn with_internal_relation_metadata(
182        relation: InternalRelationId,
183        columns: impl IntoIterator<Item = (Option<ColumnType>, Option<u32>)>,
184    ) -> Self {
185        let mut metadata = SchemaBuildMetadata::default();
186        let mut width = 0;
187        for (position, (ty, oid)) in columns.into_iter().enumerate() {
188            assert!(
189                oid.is_none_or(|oid| oid == 0
190                    || ty
191                        .as_ref()
192                        .is_some_and(super::composites::type_is_collatable)),
193                "collation requires a collatable column type"
194            );
195            let column = relation.column(position);
196            metadata.collations.internal(column, oid, ty.as_ref());
197            metadata.internal.insert(column, position);
198            metadata.internal_types.insert(column, ty);
199            width += 1;
200        }
201        Self::from_typed_parts_with_aliases_and_exact_precedence(
202            Vec::new(),
203            Vec::new(),
204            Vec::new(),
205            Vec::new(),
206            width,
207            metadata,
208        )
209    }
210
211    /// Build the lookup semantics of a named compatibility row. An exact bare
212    /// key in a map is authoritative even when qualified metadata keys share
213    /// its suffix; physical relational schemas continue to treat multiple
214    /// visible owners as ambiguous.
215    pub fn from_named_columns(columns: Vec<String>) -> Self {
216        let width = columns.len();
217        let identities = columns
218            .iter()
219            .cloned()
220            .map(ColumnIdentity::unqualified)
221            .collect();
222        Self::from_parts_with_aliases_and_exact_precedence(
223            columns,
224            identities,
225            (0..width).collect(),
226            width,
227            SchemaBuildMetadata {
228                exact_unqualified_precedence: true,
229                ..SchemaBuildMetadata::default()
230            },
231        )
232    }
233
234    fn from_parts(
235        columns: Vec<String>,
236        identities: Vec<ColumnIdentity>,
237        slots: Vec<usize>,
238        physical_width: usize,
239    ) -> Self {
240        Self::from_parts_with_aliases(
241            columns,
242            identities,
243            slots,
244            physical_width,
245            SchemaMap::default(),
246        )
247    }
248
249    fn from_parts_with_aliases(
250        columns: Vec<String>,
251        identities: Vec<ColumnIdentity>,
252        slots: Vec<usize>,
253        physical_width: usize,
254        aliases: SchemaMap<ColumnIdentity, usize>,
255    ) -> Self {
256        Self::from_parts_with_aliases_and_exact_precedence(
257            columns,
258            identities,
259            slots,
260            physical_width,
261            SchemaBuildMetadata {
262                aliases,
263                ..SchemaBuildMetadata::default()
264            },
265        )
266    }
267
268    fn from_parts_with_aliases_and_exact_precedence(
269        columns: Vec<String>,
270        identities: Vec<ColumnIdentity>,
271        slots: Vec<usize>,
272        physical_width: usize,
273        metadata: SchemaBuildMetadata,
274    ) -> Self {
275        let types = vec![None; columns.len()];
276        Self::from_typed_parts_with_aliases_and_exact_precedence(
277            columns,
278            identities,
279            types,
280            slots,
281            physical_width,
282            metadata,
283        )
284    }
285
286    pub(super) fn from_typed_parts_with_aliases_and_exact_precedence(
287        columns: Vec<String>,
288        identities: Vec<ColumnIdentity>,
289        types: Vec<Option<ColumnType>>,
290        slots: Vec<usize>,
291        physical_width: usize,
292        metadata: SchemaBuildMetadata,
293    ) -> Self {
294        #[cfg(test)]
295        SCHEMA_BUILDS.set(SCHEMA_BUILDS.get() + 1);
296        let SchemaBuildMetadata {
297            mut collations,
298            row_types,
299            row_presence,
300            record_fields,
301            aliases,
302            alias_types,
303            internal,
304            internal_types,
305            score_sources,
306            wildcard_hidden,
307            binding_only,
308            open_qualifiers,
309            exact_unqualified_precedence,
310            extra_ambiguous_unqualified,
311            extra_ambiguous_qualified,
312            local_width,
313            lateral_restrictions,
314        } = metadata;
315        collations.retain(&types, &alias_types, &internal_types, &binding_only);
316        debug_assert_eq!(columns.len(), slots.len());
317        debug_assert_eq!(columns.len(), identities.len());
318        debug_assert_eq!(columns.len(), types.len());
319        debug_assert!(wildcard_hidden
320            .iter()
321            .all(|position| *position < columns.len()));
322        let identity_layout = physical_width == columns.len()
323            && slots
324                .iter()
325                .enumerate()
326                .all(|(position, slot)| position == *slot);
327        let hasher = ahash::RandomState::default;
328        let mut exact = SchemaMap::with_capacity_and_hasher(columns.len(), hasher());
329        let mut unqualified = SchemaMap::with_capacity_and_hasher(columns.len(), hasher());
330        let mut qualified = SchemaMap::with_capacity_and_hasher(columns.len(), hasher());
331        // 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.
332        let mut ambiguous_unqualified = SchemaSet::with_hasher(hasher());
333        let mut ambiguous_qualified = SchemaSet::with_hasher(hasher());
334        for (logical, (name, identity)) in columns.iter().zip(&identities).enumerate() {
335            // Later writes to the same named field replace the value in a
336            // ResultRow. Schema transforms preserve that contract.
337            exact.insert(Box::<str>::from(name.as_str()), logical);
338            if unqualified
339                .insert(identity.column.clone(), logical)
340                .is_some()
341            {
342                ambiguous_unqualified.insert(identity.column.clone());
343            }
344            if identity.qualifier.is_some() && qualified.insert(identity.clone(), logical).is_some()
345            {
346                ambiguous_qualified.insert(identity.clone());
347            }
348        }
349        for slot in aliases.values() {
350            debug_assert!(*slot == NULL_SLOT || *slot < physical_width);
351        }
352        for slot in internal.values() {
353            debug_assert!(*slot == NULL_SLOT || *slot < physical_width);
354        }
355        if exact_unqualified_precedence {
356            ambiguous_unqualified.retain(|column| {
357                !identities
358                    .iter()
359                    .any(|identity| identity.qualifier.is_none() && identity.column == *column)
360            });
361        }
362        ambiguous_unqualified.extend(extra_ambiguous_unqualified);
363        ambiguous_qualified.extend(extra_ambiguous_qualified);
364        Self {
365            index: Arc::new(SchemaIndex {
366                columns: columns.into_boxed_slice(),
367                identities: identities.into_boxed_slice(),
368                slots: slots.into_boxed_slice(),
369                physical_width,
370                exact,
371                unqualified,
372                qualified,
373                aliases,
374                executor_attributes: internal,
375                ambiguous_unqualified,
376                ambiguous_qualified,
377                cold: Box::new(SchemaColdMetadata {
378                    collations,
379                    row_types,
380                    row_presence,
381                    record_fields,
382                    columns: types.into_boxed_slice(),
383                    aliases: alias_types,
384                    executor_attribute_types: internal_types,
385                    score_sources,
386                    wildcard_hidden,
387                    binding_only,
388                    open_qualifiers,
389                    identity_layout,
390                    local_width,
391                    lateral_restrictions,
392                }),
393            }),
394        }
395    }
396}