Skip to main content

uqa_sql/schema/
schema_layout.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Logical-to-physical layout inspection and wildcard expansion.
8
9use super::{ColumnIdentity, ColumnType, HashSet, RowSchema, NULL_SLOT};
10
11impl RowSchema {
12    /// Compare the complete physical row contract while the original schema retains analysis-only namespaces and record descriptors. A restored row must match this layout before it can reuse the original binding context.
13    pub fn has_same_physical_layout(&self, other: &Self) -> bool {
14        let left = &self.index;
15        let right = &other.index;
16        left.columns == right.columns
17            && left.identities == right.identities
18            && left.slots == right.slots
19            && left.physical_width == right.physical_width
20            && left.aliases == right.aliases
21            && left.executor_attributes == right.executor_attributes
22            && left.cold.columns == right.cold.columns
23            && left.cold.aliases == right.cold.aliases
24            && left.cold.executor_attribute_types == right.cold.executor_attribute_types
25            && left.cold.score_sources == right.cold.score_sources
26            && left.cold.row_presence == right.cold.row_presence
27            && left.cold.wildcard_hidden == right.cold.wildcard_hidden
28            && left
29                .cold
30                .collations
31                .same_physical_bindings(&right.cold.collations)
32    }
33
34    /// Whether one logical source attribute participates in `*` expansion.
35    #[must_use]
36    pub fn wildcard_position_visible(&self, position: usize) -> bool {
37        position < self.len() && !self.index.cold.wildcard_hidden.contains(&position)
38    }
39
40    pub fn columns(&self) -> &[String] {
41        &self.index.columns
42    }
43
44    pub fn len(&self) -> usize {
45        self.index.columns.len()
46    }
47
48    pub fn is_empty(&self) -> bool {
49        self.index.columns.is_empty()
50    }
51
52    pub fn iter(&self) -> std::slice::Iter<'_, String> {
53        self.index.columns.iter()
54    }
55
56    /// Static SQL type at one logical output position.
57    pub fn column_type(&self, logical: usize) -> Option<&ColumnType> {
58        self.index
59            .cold
60            .columns
61            .get(logical)
62            .and_then(Option::as_ref)
63    }
64
65    /// Static SQL types aligned with [`Self::columns`].
66    pub fn column_types(&self) -> &[Option<ColumnType>] {
67        &self.index.cold.columns
68    }
69
70    /// Structured SQL identities aligned with [`Self::columns`].
71    pub fn identities(&self) -> &[ColumnIdentity] {
72        &self.index.identities
73    }
74
75    pub fn identity(&self, logical: usize) -> Option<&ColumnIdentity> {
76        self.index.identities.get(logical)
77    }
78
79    pub fn public_name(&self, logical: usize) -> Option<&str> {
80        self.identity(logical).map(ColumnIdentity::column)
81    }
82
83    pub fn position(&self, name: &str) -> Option<usize> {
84        self.index.exact.get(name).copied()
85    }
86
87    /// Resolve one visible unqualified SQL identity to its logical position. Ambiguous names deliberately do not select an arbitrary owner.
88    pub fn unqualified_position(&self, column: &str) -> Option<usize> {
89        if self.index.ambiguous_unqualified.contains(column) {
90            return None;
91        }
92        self.index.unqualified.get(column).copied()
93    }
94
95    /// Resolve one visible qualified identity to its logical position.
96    pub fn qualified_position(&self, qualifier: &str, column: &str) -> Option<usize> {
97        let identity = ColumnIdentity::qualified(qualifier, column);
98        if self.index.ambiguous_qualified.contains(&identity) {
99            return None;
100        }
101        self.index.qualified.get(&identity).copied()
102    }
103
104    pub fn physical_width(&self) -> usize {
105        self.index.physical_width
106    }
107
108    /// Resolve one logical output position to its flattened physical slot.
109    pub fn physical_slot(&self, logical: usize) -> Option<usize> {
110        self.slot(logical)
111    }
112
113    /// Static type attached to one flattened physical slot, including
114    /// executor-only internal attributes that have no logical SQL position.
115    pub fn physical_type(&self, physical: usize) -> Option<&ColumnType> {
116        self.index
117            .slots
118            .iter()
119            .position(|slot| *slot == physical)
120            .and_then(|logical| self.column_type(logical))
121            .or_else(|| {
122                self.index.aliases.iter().find_map(|(identity, slot)| {
123                    (*slot == physical)
124                        .then(|| {
125                            self.index
126                                .cold
127                                .aliases
128                                .get(identity)
129                                .and_then(Option::as_ref)
130                        })
131                        .flatten()
132                })
133            })
134            .or_else(|| {
135                self.index
136                    .executor_attributes
137                    .iter()
138                    .find_map(|(column, slot)| {
139                        (*slot == physical)
140                            .then(|| {
141                                self.index
142                                    .cold
143                                    .executor_attribute_types
144                                    .get(column)
145                                    .and_then(Option::as_ref)
146                            })
147                            .flatten()
148                    })
149            })
150    }
151
152    /// Resolve a structured SQL identity, including a hidden JOIN USING alias, to its flattened physical slot. Ambiguous identities deliberately return `None` rather than selecting an arbitrary source value.
153    pub fn physical_slot_for_identity(&self, identity: &ColumnIdentity) -> Option<usize> {
154        match identity.qualifier() {
155            Some(qualifier) => self.qualified_slot(qualifier, identity.column()),
156            None => self.column_slot(identity.column()),
157        }
158    }
159
160    pub fn slot(&self, logical: usize) -> Option<usize> {
161        self.index
162            .slots
163            .get(logical)
164            .copied()
165            .filter(|slot| *slot != NULL_SLOT)
166    }
167
168    pub fn exact_slot(&self, name: &str) -> Option<usize> {
169        self.index
170            .exact
171            .get(name)
172            .and_then(|logical| self.slot(*logical))
173            .filter(|slot| *slot != NULL_SLOT)
174    }
175
176    pub(super) fn exact_type(&self, name: &str) -> Option<&ColumnType> {
177        self.index
178            .exact
179            .get(name)
180            .and_then(|logical| self.column_type(*logical))
181    }
182
183    pub fn column_slot(&self, name: &str) -> Option<usize> {
184        if self.index.ambiguous_unqualified.contains(name) {
185            return None;
186        }
187        self.index
188            .unqualified
189            .get(name)
190            .and_then(|logical| self.slot(*logical))
191            .or_else(|| {
192                self.index
193                    .aliases
194                    .get(&ColumnIdentity::unqualified(name))
195                    .copied()
196            })
197            .filter(|slot| *slot != NULL_SLOT)
198    }
199
200    /// Physical projection layout for `qualifier.*` in relation-column order. Hidden identities introduced by `JOIN ... USING` remain selectable, so each side's wildcard retains its own merged-column value.
201    pub fn qualified_star_layout(
202        &self,
203        qualifier: &str,
204    ) -> Vec<(String, usize, Option<ColumnType>)> {
205        self.qualified_star_position_layout(qualifier)
206            .into_iter()
207            .map(|(column, _, slot, ty)| (column, slot, ty))
208            .collect()
209    }
210
211    /// Bound layout for `qualifier.*`. Visible columns retain their logical positions; hidden aliases such as the suppressed side of `JOIN ... USING` expose only their physical slot.
212    pub fn qualified_star_position_layout(
213        &self,
214        qualifier: &str,
215    ) -> Vec<(String, Option<usize>, usize, Option<ColumnType>)> {
216        let mut entries = Vec::new();
217        let mut visible_layout = HashSet::new();
218        for (logical, identity) in self.identities().iter().enumerate() {
219            if identity.qualifier() == Some(qualifier) {
220                let slot = self.slot(logical).unwrap_or(NULL_SLOT);
221                visible_layout.insert((identity.clone(), slot));
222                entries.push((
223                    identity.clone(),
224                    Some(logical),
225                    slot,
226                    self.column_type(logical).cloned(),
227                ));
228            }
229        }
230        for (identity, slot) in &self.index.aliases {
231            if identity.qualifier() == Some(qualifier)
232                && !visible_layout.contains(&(identity.clone(), *slot))
233            {
234                entries.push((
235                    identity.clone(),
236                    None,
237                    *slot,
238                    self.index.cold.aliases.get(identity).cloned().flatten(),
239                ));
240            }
241        }
242        entries.sort_by_key(|(_, _, slot, _)| *slot);
243        entries
244            .into_iter()
245            .map(|(identity, logical, slot, ty)| (identity.column().to_string(), logical, slot, ty))
246            .collect()
247    }
248
249    pub fn qualified_slot(&self, qualifier: &str, column: &str) -> Option<usize> {
250        let identity = ColumnIdentity::qualified(qualifier, column);
251        if self.index.ambiguous_qualified.contains(&identity) {
252            return None;
253        }
254        self.index
255            .qualified
256            .get(&identity)
257            .and_then(|logical| self.slot(*logical))
258            .or_else(|| self.index.aliases.get(&identity).copied())
259            .filter(|slot| *slot != NULL_SLOT)
260    }
261}
262
263impl<'a> IntoIterator for &'a RowSchema {
264    type Item = &'a String;
265    type IntoIter = std::slice::Iter<'a, String>;
266
267    fn into_iter(self) -> Self::IntoIter {
268        self.iter()
269    }
270}