Skip to main content

uqa_sql/expr/composites/
constructor.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Evaluate retained row positions against the current composite descriptor.
8
9use crate::{
10    ast::{ColumnType, CompositeRowBinding},
11    expr::EngineHook,
12    SQLError,
13};
14use uqa_core::{
15    memory::{Produced, ProductionControl, ProductionVec},
16    Value,
17};
18
19mod state;
20pub use state::CompositeConstructorState;
21
22pub fn evaluate_with_control(
23    binding: &CompositeRowBinding,
24    arguments: usize,
25    engine: Option<&dyn EngineHook>,
26    control: &ProductionControl<'_>,
27    evaluate: impl FnMut(usize) -> Result<Produced<Value>, SQLError>,
28) -> Result<Produced<Value>, SQLError> {
29    evaluate_with_state(binding, arguments, engine, control, None, evaluate)
30}
31
32pub fn evaluate_with_state(
33    binding: &CompositeRowBinding,
34    arguments: usize,
35    engine: Option<&dyn EngineHook>,
36    control: &ProductionControl<'_>,
37    state: Option<&CompositeConstructorState>,
38    evaluate: impl FnMut(usize) -> Result<Produced<Value>, SQLError>,
39) -> Result<Produced<Value>, SQLError> {
40    control.check()?;
41    let engine =
42        engine.ok_or_else(|| SQLError::Internal("composite constructor has no catalog".into()))?;
43    let resolved = engine.resolve_type_name_with_control(&binding.ty, control)?;
44    control.check()?;
45    let Some(ColumnType::Composite(reference)) = resolved.as_deref() else {
46        return Err(SQLError::Internal(
47            "composite constructor type disappeared".into(),
48        ));
49    };
50    let descriptor = super::descriptor(engine.composite_types(), reference.oid)?;
51    let value = construct_with_state(binding, arguments, &descriptor, control, state, evaluate)?;
52    let Value::Record(record) = &*value else {
53        unreachable!("named composite producer");
54    };
55    super::retention::retain_record(record, &descriptor, engine.composite_types(), control)
56}
57
58/// Form a row using a resolved descriptor, after checking all surviving argument types and before evaluating any argument.
59pub fn construct_with_control(
60    binding: &CompositeRowBinding,
61    arguments: usize,
62    descriptor: &super::CompositeTypeDescriptor,
63    control: &ProductionControl<'_>,
64    evaluate: impl FnMut(usize) -> Result<Produced<Value>, SQLError>,
65) -> Result<Produced<Value>, SQLError> {
66    construct_with_state(binding, arguments, descriptor, control, None, evaluate)
67}
68
69pub fn construct_with_state(
70    binding: &CompositeRowBinding,
71    arguments: usize,
72    descriptor: &super::CompositeTypeDescriptor,
73    control: &ProductionControl<'_>,
74    state: Option<&CompositeConstructorState>,
75    mut evaluate: impl FnMut(usize) -> Result<Produced<Value>, SQLError>,
76) -> Result<Produced<Value>, SQLError> {
77    control.check()?;
78    if binding.attributes.len() != arguments
79        || binding.attributes.iter().any(|number| *number <= 0)
80        || binding.attributes.windows(2).any(|pair| pair[0] >= pair[1])
81    {
82        return Err(SQLError::Internal(
83            "invalid stored composite constructor positions".into(),
84        ));
85    }
86    if let Some(types) = &binding.argument_types {
87        if types.len() != arguments {
88            return Err(SQLError::Internal(
89                "invalid stored composite constructor types".into(),
90            ));
91        }
92        for attribute in &descriptor.attributes {
93            control.check()?;
94            if let Ok(index) = binding.attributes.binary_search(&attribute.number) {
95                let source = &types[index];
96                if crate::catalog::type_metadata::pg_type_oid(source)
97                    != crate::catalog::type_metadata::pg_type_oid(&attribute.ty)
98                {
99                    return Err(SQLError::Routine {
100                        sqlstate: "42804".into(),
101                        message: format!(
102                            "ROW() column has type {} instead of type {}",
103                            source.display_name(),
104                            attribute.ty.display_name()
105                        ),
106                    });
107                }
108            }
109        }
110    }
111    produce(descriptor, control, state, |_, attribute| {
112        match binding.attributes.binary_search(&attribute.number) {
113            Ok(index) => evaluate(index),
114            Err(_) => Ok(control.finish(Value::Null, control.empty_reservation())?),
115        }
116    })
117}
118
119/// Construct a newly admitted record from exactly the current live attributes. The caller binds and coerces each positional input; no stored-expression binding is required.
120pub fn construct_current_with_control(
121    descriptor: &super::CompositeTypeDescriptor,
122    catalog: Option<&dyn super::CompositeTypeCatalog>,
123    control: &ProductionControl<'_>,
124    mut evaluate: impl FnMut(usize) -> Result<Produced<Value>, SQLError>,
125) -> Result<Produced<Value>, SQLError> {
126    let value = produce(descriptor, control, None, |index, _| evaluate(index))?;
127    let Value::Record(record) = &*value else {
128        unreachable!("named composite producer")
129    };
130    super::retention::retain_record(record, descriptor, catalog, control)
131}
132
133fn produce(
134    descriptor: &super::CompositeTypeDescriptor,
135    control: &ProductionControl<'_>,
136    state: Option<&CompositeConstructorState>,
137    mut evaluate: impl FnMut(usize, &super::CompositeAttribute) -> Result<Produced<Value>, SQLError>,
138) -> Result<Produced<Value>, SQLError> {
139    control.check()?;
140    let shared = state.and_then(|state| state.shared(descriptor));
141    let mut names = ProductionVec::new(*control);
142    let mut values = ProductionVec::new(*control);
143    values.reserve(descriptor.attributes.len())?;
144    if shared.is_none() {
145        names.reserve(descriptor.attributes.len())?;
146    }
147    for (index, attribute) in descriptor.attributes.iter().enumerate() {
148        let value = evaluate(index, attribute)?;
149        if shared.is_none() {
150            names.push_produced(control.copy_text(&attribute.name)?)?;
151        }
152        values.push_produced(value)?;
153    }
154    let record = if let Some(shared) = shared {
155        uqa_core::RecordValue::with_shared_control(values.finish()?, shared, control)?
156    } else {
157        let descriptor = uqa_core::RecordDescriptor::with_control(
158            names.finish()?,
159            Some(descriptor.type_oid),
160            control,
161        )?;
162        uqa_core::RecordValue::with_descriptor_control(values.finish()?, descriptor, control)?
163    };
164    if let Some(state) = state {
165        state.remember(record.descriptor(), control)?;
166    }
167    let (record, memory) = record.into_parts();
168    control
169        .finish(Value::Record(record), memory)
170        .map_err(Into::into)
171}
172
173/// Bind predecessor constructor metadata while its original descriptor is still current. Attribute removal cannot make a discarded argument run again.
174pub fn retain_argument_types(
175    binding: &mut CompositeRowBinding,
176    types: &dyn crate::type_resolution::FunctionTypeResolver,
177    catalog: Option<&dyn super::CompositeTypeCatalog>,
178) -> Result<bool, SQLError> {
179    if binding.argument_types.is_some() {
180        return Ok(false);
181    }
182    let Some(ColumnType::Composite(reference)) = types.resolve_type_name(&binding.ty)? else {
183        return Err(SQLError::Internal(
184            "composite constructor type disappeared".into(),
185        ));
186    };
187    let descriptor = super::descriptor(catalog, reference.oid)?;
188    binding.argument_types = Some(
189        binding
190            .attributes
191            .iter()
192            .map(|number| {
193                descriptor
194                    .attributes
195                    .iter()
196                    .find(|attribute| attribute.number == *number)
197                    .map_or(ColumnType::Integer, |attribute| attribute.ty.clone())
198            })
199            .collect(),
200    );
201    Ok(true)
202}
203
204#[cfg(test)]
205mod tests {
206    use super::*;
207    use crate::ast::CompositeTypeReference;
208    use crate::expr::composites::{
209        CompositeAttribute, CompositeTypeCatalog, CompositeTypeDescriptor,
210    };
211    use std::sync::Arc;
212    use uqa_core::{memory::MemoryBudget, CancellationToken};
213
214    struct Catalog;
215    fn reference() -> ColumnType {
216        ColumnType::Composite(CompositeTypeReference {
217            schema: "public".into(),
218            name: "pair".into(),
219            oid: 20_001,
220            array_oid: 20_002,
221            relation_oid: 20_003,
222        })
223    }
224    impl CompositeTypeCatalog for Catalog {
225        fn composite_type(&self, _: u32) -> Result<Option<Arc<CompositeTypeDescriptor>>, SQLError> {
226            Ok(Some(Arc::new(CompositeTypeDescriptor {
227                dropped: Vec::new(),
228                type_oid: 20_001,
229                relation_oid: 20_003,
230                attributes: [1, 3, 4]
231                    .into_iter()
232                    .map(|number| CompositeAttribute {
233                        collation_oid: None,
234                        name: format!("a{number}"),
235                        ty: ColumnType::Integer,
236                        number,
237                    })
238                    .collect(),
239            })))
240        }
241    }
242    impl EngineHook for Catalog {
243        fn nextval(&self, _: &str) -> Result<i64, SQLError> {
244            unreachable!()
245        }
246        fn currval(&self, _: &str) -> Result<i64, SQLError> {
247            unreachable!()
248        }
249        fn setval(&self, _: &str, _: i64, _: bool) -> Result<i64, SQLError> {
250            unreachable!()
251        }
252        fn resolve_type_name(&self, _: &str) -> Result<Option<ColumnType>, String> {
253            Ok(Some(reference()))
254        }
255        fn composite_types(&self) -> Option<&dyn CompositeTypeCatalog> {
256            Some(self)
257        }
258    }
259
260    #[test]
261    fn stored_positions_extend_nulls_without_evaluating_removed_fields() {
262        let budget = MemoryBudget::new(4096);
263        let cancellation = CancellationToken::new();
264        let control = ProductionControl::new(&budget, &cancellation, &cancellation);
265        let binding = CompositeRowBinding {
266            layout: None,
267            argument_types: Some(vec![
268                ColumnType::Integer,
269                ColumnType::Text,
270                ColumnType::Integer,
271            ]),
272            ty: "composite#20001".into(),
273            attributes: vec![1, 2, 3],
274        };
275        let mut evaluated = Vec::new();
276        let value = evaluate_with_control(&binding, 3, Some(&Catalog), &control, |index| {
277            evaluated.push(index);
278            control
279                .finish(Value::Int(index as i64), control.empty_reservation())
280                .map_err(Into::into)
281        })
282        .unwrap();
283        assert_eq!(evaluated, vec![0, 2]);
284        let Value::Datum(datum) = &*value else {
285            panic!("retained constructor output");
286        };
287        assert_eq!(datum.type_oid(), 20_001);
288        for (name, expected) in [
289            ("a1", Value::Int(0)),
290            ("a3", Value::Int(2)),
291            ("a4", Value::Null),
292        ] {
293            let field = crate::expr::datums::read_composite_field_with_control(
294                datum,
295                name,
296                Some(&Catalog),
297                &control,
298            )
299            .unwrap();
300            let decoded = match &*field {
301                Value::Datum(datum) => {
302                    crate::expr::datums::read_with_control(datum, &control).unwrap()
303                }
304                value => control.copy_value(value).unwrap(),
305            };
306            assert_eq!(*decoded, expected);
307        }
308        assert!(budget.used() > 0);
309        drop(value);
310        assert_eq!(budget.used(), 0);
311    }
312
313    #[test]
314    fn retained_argument_types_are_checked_before_any_argument_effect() {
315        let control = ProductionControl::uncontrolled();
316        let binding = CompositeRowBinding {
317            layout: None,
318            ty: "composite#20001".into(),
319            attributes: vec![1, 2, 3],
320            argument_types: Some(vec![
321                ColumnType::Integer,
322                ColumnType::Text,
323                ColumnType::Real,
324            ]),
325        };
326        let error = evaluate_with_control(&binding, 3, Some(&Catalog), &control, |_| {
327            panic!("a type mismatch must precede every argument effect")
328        })
329        .unwrap_err();
330        assert_eq!(error.sqlstate(), Some("42804"));
331        assert_eq!(
332            error.to_string(),
333            "ROW() column has type real instead of type integer"
334        );
335    }
336
337    #[test]
338    fn constructor_checks_cancellation_and_admission_before_evaluating_arguments() {
339        let budget = MemoryBudget::new(0);
340        let cancellation = CancellationToken::new();
341        let control = ProductionControl::new(&budget, &cancellation, &cancellation);
342        let binding = CompositeRowBinding {
343            layout: None,
344            argument_types: None,
345            ty: "composite#20001".into(),
346            attributes: vec![1],
347        };
348        let error =
349            evaluate_with_control(&binding, 1, Some(&Catalog), &control, |_| unreachable!())
350                .unwrap_err();
351        assert_eq!(error.sqlstate(), Some("53200"));
352        cancellation.cancel();
353        let error =
354            evaluate_with_control(&binding, 1, Some(&Catalog), &control, |_| unreachable!())
355                .unwrap_err();
356        assert_eq!(error.sqlstate(), Some("57014"));
357    }
358    #[test]
359    fn composite_only_embedding_keeps_comparison_metadata_without_enum_support() {
360        let value = Value::Record(uqa_core::RecordValue::from_parts(
361            vec![
362                ("a1".into(), Value::Int(1)),
363                ("a3".into(), Value::Int(2)),
364                ("a4".into(), Value::Null),
365            ],
366            Some(20_001),
367        ));
368        let expression = crate::ast::Expr::Binary {
369            op: crate::ast::BinaryOp::Equal,
370            lhs: Box::new(crate::ast::Expr::Literal(value.clone())),
371            rhs: Box::new(crate::ast::Expr::Literal(value)),
372        };
373        assert!(Catalog.enum_labels().is_none());
374        let context = crate::expr::EvalContext::new(None, &[]).with_engine(&Catalog);
375        assert_eq!(
376            crate::expr::eval(&expression, &context).unwrap(),
377            Value::Bool(true)
378        );
379    }
380    #[test]
381    fn repeated_composite_constructors_share_names_with_live_descriptor_validation() {
382        let budget = MemoryBudget::new(8 << 20);
383        let token = CancellationToken::new();
384        let control = ProductionControl::new(&budget, &token, &token);
385        let state = CompositeConstructorState::default();
386        let mut descriptor = (*Catalog.composite_type(20_001).unwrap().unwrap()).clone();
387        for attribute in &mut descriptor.attributes {
388            attribute.name = format!("{}{}", attribute.number, "n".repeat(8192));
389        }
390        let binding = CompositeRowBinding {
391            layout: None,
392            ty: "composite#20001".into(),
393            attributes: vec![1, 3, 4],
394            argument_types: Some(vec![ColumnType::Integer; 3]),
395        };
396        let make = |descriptor: &CompositeTypeDescriptor| {
397            construct_with_state(&binding, 3, descriptor, &control, Some(&state), |index| {
398                Ok(control.finish(Value::Int(index as i64), control.empty_reservation())?)
399            })
400        };
401        let first = make(&descriptor).unwrap();
402        let Value::Record(first_record) = &*first else {
403            panic!("record")
404        };
405        let mut last = None;
406        let allocations = allocation_counter::measure(|| {
407            last = Some(make(&descriptor).unwrap());
408        });
409        let last = last.unwrap();
410        let Value::Record(last_record) = &*last else {
411            panic!("record")
412        };
413        assert!(first_record
414            .descriptor()
415            .shares_storage_with(last_record.descriptor()));
416        assert!(
417            allocations.bytes_total < 4096,
418            "warm construction must not copy long names: {allocations:?}"
419        );
420        assert_eq!(*first, *last);
421        descriptor.attributes[0].name = "renamed".into();
422        let renamed = make(&descriptor).unwrap();
423        let Value::Record(renamed_record) = &*renamed else {
424            panic!("record")
425        };
426        assert!(!first_record
427            .descriptor()
428            .shares_storage_with(renamed_record.descriptor()));
429        assert_eq!(renamed_record.descriptor().field_names()[0], "renamed");
430        descriptor.attributes[0].ty = ColumnType::Text;
431        let error = construct_with_state(&binding, 3, &descriptor, &control, Some(&state), |_| {
432            panic!("live validation precedes argument evaluation")
433        })
434        .unwrap_err();
435        assert_eq!(error.sqlstate(), Some("42804"));
436        drop((first, renamed, state));
437        assert_eq!(budget.used(), last.reserved_bytes());
438        drop(last);
439        assert_eq!(budget.used(), 0);
440    }
441
442    #[test]
443    fn composite_descriptor_reuse_preserves_drop_add_type_identity_and_cancellation() {
444        let control = ProductionControl::uncontrolled();
445        let state = CompositeConstructorState::default();
446        let binding = CompositeRowBinding {
447            layout: None,
448            ty: "composite#20001".into(),
449            attributes: vec![1, 2, 3],
450            argument_types: Some(vec![ColumnType::Integer; 3]),
451        };
452        let mut descriptor = (*Catalog.composite_type(20_001).unwrap().unwrap()).clone();
453        let evaluate = |_: usize| Ok(control.finish(Value::Int(1), control.empty_reservation())?);
454        let first =
455            construct_with_state(&binding, 3, &descriptor, &control, Some(&state), evaluate)
456                .unwrap();
457        descriptor.type_oid = 20_009;
458        let mut calls = Vec::new();
459        let output =
460            construct_with_state(&binding, 3, &descriptor, &control, Some(&state), |index| {
461                calls.push(index);
462                evaluate(index)
463            })
464            .unwrap();
465        assert_eq!(calls, [0, 2]);
466        let Value::Record(record) = &*output else {
467            panic!("record")
468        };
469        assert_eq!(record.type_oid(), Some(20_009));
470        assert_eq!(record.values()[2], Value::Null);
471        assert!(!first.has_same_representation(&output));
472        let budget = MemoryBudget::new(1 << 20);
473        let token = CancellationToken::new();
474        let controlled = ProductionControl::new(&budget, &token, &token);
475        token.cancel();
476        assert_eq!(
477            construct_with_state(
478                &binding,
479                3,
480                &descriptor,
481                &controlled,
482                Some(&state),
483                |_| panic!("cancelled")
484            )
485            .unwrap_err()
486            .sqlstate(),
487            Some("57014")
488        );
489        assert_eq!(budget.used(), 0);
490    }
491}