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