Skip to main content

uqa_sql/schema/
record_fields.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Statically known anonymous-record descriptors follow their physical value slots through query analysis.
8
9use super::{Arc, ColumnType, RowSchema, SchemaMap};
10
11/// A record's analyzed field types. Runtime values cannot distinguish SQL integer widths or a NULL field's declared type.
12pub type RecordFields = Arc<[Option<ColumnType>]>;
13
14/// Comparison field types and a selectable tuple descriptor are independent. A set operation can select fields through its left input even when its rows do not share field types.
15#[derive(Debug, Clone, PartialEq, Eq)]
16pub(crate) struct RecordMetadata {
17    pub types: Option<RecordFields>,
18    pub descriptor: Option<Arc<RecordDescriptor>>,
19}
20
21#[derive(Debug, Clone, Copy, PartialEq, Eq)]
22pub(crate) struct RecordFieldMetadata {
23    pub collation_oid: u32,
24    pub sql_unknown: bool,
25}
26
27/// A tuple shape available to parser field selection. Anonymous names are generated only when looked up, without allocating an `fN` string for every field.
28#[derive(Debug, PartialEq, Eq)]
29pub(crate) struct RecordDescriptor {
30    pub types: RecordFields,
31    pub names: Option<Box<[String]>>,
32    pub fields: Box<[RecordFieldMetadata]>,
33}
34
35impl RecordDescriptor {
36    pub fn position(&self, name: &str) -> Option<usize> {
37        self.names.as_ref().map_or_else(
38            || {
39                crate::type_resolution::field_selection::anonymous_field_position(
40                    name,
41                    self.types.len(),
42                )
43            },
44            |names| names.iter().position(|candidate| candidate == name),
45        )
46    }
47}
48
49impl RowSchema {
50    pub fn record_fields(&self, logical: usize) -> Option<&RecordFields> {
51        self.slot(logical)
52            .and_then(|slot| self.physical_record_fields(slot))
53    }
54
55    pub fn physical_record_fields(&self, slot: usize) -> Option<&RecordFields> {
56        self.physical_record_metadata(slot)?.types.as_ref()
57    }
58
59    pub(crate) fn physical_record_metadata(&self, slot: usize) -> Option<&RecordMetadata> {
60        self.index.cold.record_fields.get(&slot)
61    }
62
63    pub(crate) fn record_metadata(&self, logical: usize) -> Option<&RecordMetadata> {
64        self.slot(logical)
65            .and_then(|slot| self.index.cold.record_fields.get(&slot))
66    }
67
68    pub(crate) fn input_record_metadata(
69        &self,
70        expression: &crate::ScalarExpr,
71    ) -> Option<&RecordMetadata> {
72        let slot = match expression {
73            crate::ScalarExpr::Column(name) => self.column_slot(name),
74            crate::ScalarExpr::QualifiedColumn { qualifier, column } => {
75                self.qualified_slot(qualifier, column)
76            }
77            crate::ScalarExpr::InternalColumn(column) => self.internal_slot(*column),
78            crate::ScalarExpr::Position(position) => self.slot(*position),
79            _ => None,
80        }?;
81        self.index.cold.record_fields.get(&slot)
82    }
83
84    /// Attach comparison field types to logical columns without declaring a selectable tuple descriptor or changing slot identity.
85    pub fn with_record_fields(
86        self,
87        fields: impl IntoIterator<Item = (usize, RecordFields)>,
88    ) -> Self {
89        self.with_record_metadata(fields.into_iter().map(|(position, types)| {
90            (
91                position,
92                RecordMetadata {
93                    types: Some(types),
94                    descriptor: None,
95                },
96            )
97        }))
98    }
99
100    pub(crate) fn with_record_metadata(
101        mut self,
102        fields: impl IntoIterator<Item = (usize, RecordMetadata)>,
103    ) -> Self {
104        for (logical, fields) in fields {
105            if let Some(slot) = self.slot(logical) {
106                Arc::make_mut(&mut self.index)
107                    .cold
108                    .record_fields
109                    .insert(slot, fields);
110            }
111        }
112        self
113    }
114
115    pub(crate) fn with_physical_record_metadata(
116        mut self,
117        fields: impl IntoIterator<Item = (usize, RecordMetadata)>,
118    ) -> Self {
119        for (slot, fields) in fields {
120            assert!(
121                slot < self.physical_width(),
122                "record metadata requires a physical slot"
123            );
124            Arc::make_mut(&mut self.index)
125                .cold
126                .record_fields
127                .insert(slot, fields);
128        }
129        self
130    }
131
132    /// Preserve descriptors when a namespace boundary rebuilds the same logical columns in a compact physical row.
133    pub fn with_record_fields_from(self, input: &Self) -> Self {
134        let width = self.len().min(input.len());
135        self.with_record_metadata((0..width).filter_map(|index| {
136            input
137                .record_metadata(index)
138                .cloned()
139                .map(|fields| (index, fields))
140        }))
141    }
142
143    pub(super) fn joined_record_fields(
144        left: &Self,
145        right: &Self,
146        right_base: usize,
147    ) -> SchemaMap<usize, RecordMetadata> {
148        let mut fields = left.index.cold.record_fields.clone();
149        fields.extend(
150            right
151                .index
152                .cold
153                .record_fields
154                .iter()
155                .map(|(slot, fields)| (right_base + slot, fields.clone())),
156        );
157        fields
158    }
159}
160
161#[cfg(test)]
162mod tests {
163    use super::*;
164
165    #[test]
166    fn projection_alias_join_and_compaction_preserve_record_field_slots() {
167        let fields: RecordFields =
168            vec![Some(ColumnType::Integer), Some(ColumnType::BigInteger)].into();
169        let descriptor = Arc::new(RecordDescriptor {
170            types: fields.clone(),
171            names: None,
172            fields: vec![
173                RecordFieldMetadata {
174                    collation_oid: 0,
175                    sql_unknown: false
176                };
177                2
178            ]
179            .into(),
180        });
181        let input = RowSchema::with_types(
182            vec!["discard".into(), "value".into()],
183            vec![Some(ColumnType::Text), Some(ColumnType::Record)],
184        )
185        .with_record_metadata([(
186            1,
187            RecordMetadata {
188                types: Some(fields.clone()),
189                descriptor: Some(descriptor.clone()),
190            },
191        )]);
192        let selected = RowSchema::select(&input, &[("renamed".into(), "value".into())]);
193        assert_eq!(selected.record_fields(0), Some(&fields));
194        let qualified = RowSchema::with_relation_qualifier(&selected, "r");
195        assert_eq!(
196            qualified.physical_record_fields(qualified.qualified_slot("r", "renamed").unwrap()),
197            Some(&fields)
198        );
199        let (compact, _) = qualified.canonical_projection();
200        assert_eq!(compact.record_fields(0), Some(&fields));
201        let public = qualified.for_result_columns(qualified.columns());
202        assert_eq!(public.physical_width(), 1);
203        assert_eq!(public.qualified_slot("r", "renamed"), None);
204        assert_eq!(public.position("discard"), None);
205        let outer = RowSchema::with_outer_schema(&RowSchema::default(), &compact);
206        assert_eq!(
207            outer.physical_record_fields(outer.qualified_slot("r", "renamed").unwrap()),
208            Some(&fields)
209        );
210        for schema in [&selected, &qualified, &compact, &public] {
211            assert!(Arc::ptr_eq(
212                &descriptor,
213                schema
214                    .record_metadata(0)
215                    .unwrap()
216                    .descriptor
217                    .as_ref()
218                    .unwrap()
219            ));
220            assert!(Arc::ptr_eq(&fields, schema.record_fields(0).unwrap()));
221        }
222        assert!(Arc::ptr_eq(
223            &descriptor,
224            outer
225                .physical_record_metadata(outer.qualified_slot("r", "renamed").unwrap())
226                .unwrap()
227                .descriptor
228                .as_ref()
229                .unwrap()
230        ));
231    }
232}