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