Skip to main content

uqa_sql/
params.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bind parameters for `Engine::sql(query, params)`.
8
9use crate::SQLError;
10use uqa_core::{
11    memory::{Produced, ProductionControl, ProductionVec},
12    Value,
13};
14
15use crate::ast::ColumnType;
16
17mod record;
18pub use record::create_record_parameter_with_control;
19mod range;
20pub use range::{
21    create_multirange_parameter_with_control, create_range_parameter_with_control,
22    RangeParameterBounds,
23};
24mod array;
25mod input;
26pub use array::create_array_parameter_with_control;
27pub use input::create_typed_parameter_with_control;
28mod binding;
29mod packed;
30mod tensor;
31pub use binding::{
32    bind_declared_parameter_types, bind_parameter_type_with_control, bind_parameter_types,
33};
34pub use tensor::SQLTensor;
35
36/// Value bound to a `$N` placeholder.
37#[derive(Debug, Clone)]
38pub enum SQLParam {
39    Scalar(Value),
40    /// A scalar value whose declared SQL type must survive runtime [`Value`] carrier normalization.
41    TypedScalar {
42        value: Value,
43        ty: ColumnType,
44    },
45    /// A procedural parameter whose retained type is known but whose current
46    /// value is invalid. Raise only if execution evaluates this parameter.
47    #[doc(hidden)]
48    DeferredError {
49        ty: ColumnType,
50        error: Box<crate::ast::DeferredSQLError>,
51    },
52    Vector(Vec<f32>),
53    Tensor(Vec<Vec<f32>>),
54    /// A validated packed tensor whose declared dimension survives an empty row set.
55    TypedTensor(SQLTensor),
56}
57
58impl SQLParam {
59    /// Copy a parameter without evaluating its carrier or a deferred diagnostic, retaining its declared type and every private payload under the original allowance.
60    pub fn clone_with_control(
61        &self,
62        control: &ProductionControl<'_>,
63    ) -> Result<Produced<Self>, SQLError> {
64        crate::plan::copy::copy_syntax_with_control(self, control)
65    }
66
67    pub fn scalar(value: Value) -> Self {
68        Self::Scalar(value)
69    }
70
71    #[must_use]
72    pub fn typed_scalar(value: Value, ty: ColumnType) -> Self {
73        Self::TypedScalar { value, ty }
74    }
75
76    /// Return the scalar carrier without changing the semantics of untyped [`SQLParam::Scalar`] values.
77    #[must_use]
78    pub fn scalar_value(&self) -> Option<&Value> {
79        match self {
80            Self::Scalar(value) | Self::TypedScalar { value, .. } => Some(value),
81            Self::Vector(_)
82            | Self::Tensor(_)
83            | Self::TypedTensor(_)
84            | Self::DeferredError { .. } => None,
85        }
86    }
87
88    /// Return an explicit scalar type, including a deferred procedural error's retained type.
89    #[must_use]
90    pub fn declared_scalar_type(&self) -> Option<&ColumnType> {
91        match self {
92            Self::TypedScalar { ty, .. } | Self::DeferredError { ty, .. } => Some(ty),
93            Self::Scalar(_) | Self::Vector(_) | Self::Tensor(_) | Self::TypedTensor(_) => None,
94        }
95    }
96
97    /// Materialize the parameter carrier with ordinary SQL value semantics.
98    pub fn to_value(&self) -> Result<Value, SQLError> {
99        self.to_value_with_control(&ProductionControl::uncontrolled())
100            .map(|value| value.into_uncontrolled().expect("ordinary parameter value"))
101    }
102
103    /// Copy a borrowed parameter while retaining every container and child payload under its producer's allowance.
104    pub fn to_value_with_control(
105        &self,
106        control: &ProductionControl<'_>,
107    ) -> Result<Produced<Value>, SQLError> {
108        control.check()?;
109        match self {
110            Self::DeferredError { error, .. } => Err((**error).clone().into()),
111            Self::Scalar(value) | Self::TypedScalar { value, .. } => Ok(control.copy_value(value)?),
112            Self::Vector(values) => vector_value(values, control),
113            Self::Tensor(vectors) => {
114                let mut output = ProductionVec::new(*control);
115                output.reserve(vectors.len())?;
116                for values in vectors {
117                    output.push_produced(vector_value(values, control)?)?;
118                }
119                let (values, memory) = output.finish()?.into_parts();
120                Ok(control.finish(Value::List(values), memory)?)
121            }
122            Self::TypedTensor(tensor) => tensor.to_value_with_control(control),
123        }
124    }
125
126    pub fn vector(v: Vec<f32>) -> Self {
127        Self::Vector(v)
128    }
129
130    /// Copy a host vector after validating its SQL dimension and finite float32 elements. The completed parameter retains the caller's original allowance.
131    pub fn vector_with_control(
132        values: &[f32],
133        control: &ProductionControl<'_>,
134    ) -> Result<Produced<Self>, SQLError> {
135        control.check()?;
136        if values.is_empty() || u32::try_from(values.len()).is_err() {
137            return Err(SQLError::TypeMismatch(
138                "vector dimension must be a positive 32-bit integer".into(),
139            ));
140        }
141        for value in values {
142            crate::expr::vector_element_with_control(&Value::Float(f64::from(*value)), control)?;
143        }
144        let mut output = ProductionVec::new(*control);
145        output.extend_from_slice(values)?;
146        let (values, memory) = output.finish()?.into_parts();
147        Ok(control.finish(Self::Vector(values), memory)?)
148    }
149
150    pub fn tensor(v: Vec<Vec<f32>>) -> Self {
151        Self::Tensor(v)
152    }
153}
154
155fn vector_value(
156    values: &[f32],
157    control: &ProductionControl<'_>,
158) -> Result<Produced<Value>, SQLError> {
159    let mut output = ProductionVec::new(*control);
160    output.reserve(values.len())?;
161    for value in values {
162        output.push_produced(
163            control.finish(Value::Float(f64::from(*value)), control.empty_reservation())?,
164        )?;
165    }
166    let (values, memory) = output.finish()?.into_parts();
167    Ok(control.finish(Value::List(values), memory)?)
168}
169
170#[cfg(test)]
171mod tests {
172    use super::*;
173
174    #[test]
175    fn deferred_parameter_keeps_scalar_carriers_compact_and_errors_lazy() {
176        assert!(size_of::<SQLParam>() <= size_of::<(Value, ColumnType, usize)>());
177        let error = crate::plpgsql::runtime_diagnostics::unassigned_record("r");
178        let parameter = SQLParam::DeferredError {
179            ty: ColumnType::SmallInteger,
180            error: Box::new((&error).into()),
181        };
182        assert_eq!(parameter.scalar_value(), None);
183        assert_eq!(
184            parameter.declared_scalar_type(),
185            Some(&ColumnType::SmallInteger)
186        );
187        let observed = parameter.to_value().unwrap_err();
188        assert_eq!(observed.sqlstate(), error.sqlstate());
189        assert_eq!(observed.to_string(), error.to_string());
190        assert_eq!(observed.detail(), error.detail());
191        assert_eq!(observed.hint(), error.hint());
192    }
193
194    #[test]
195    fn typed_scalar_preserves_declared_type_without_changing_scalar_access() {
196        let value = Value::Int(7);
197        let typed = SQLParam::typed_scalar(value.clone(), ColumnType::SmallInteger);
198        assert_eq!(typed.scalar_value(), Some(&value));
199        assert_eq!(
200            typed.declared_scalar_type(),
201            Some(&ColumnType::SmallInteger)
202        );
203
204        let scalar = SQLParam::scalar(value.clone());
205        assert_eq!(scalar.scalar_value(), Some(&value));
206        assert_eq!(scalar.declared_scalar_type(), None);
207    }
208
209    #[test]
210    fn host_vector_input_checks_shape_and_finiteness_before_retaining_bytes() {
211        use uqa_core::{memory::MemoryBudget, CancellationToken};
212        let budget = MemoryBudget::new(64);
213        let original = CancellationToken::new();
214        let invoking = CancellationToken::new();
215        let control = ProductionControl::new(&budget, &original, &invoking);
216        let held = control.copy_text("held").unwrap();
217        for values in [
218            vec![],
219            vec![f32::NAN],
220            vec![f32::INFINITY],
221            vec![f32::NEG_INFINITY],
222        ] {
223            assert!(SQLParam::vector_with_control(&values, &control).is_err());
224            assert_eq!(budget.used(), held.reserved_bytes());
225        }
226        assert_eq!(
227            SQLParam::vector_with_control(&[1.0; 64], &control)
228                .unwrap_err()
229                .sqlstate(),
230            Some("53200")
231        );
232        assert_eq!(budget.used(), held.reserved_bytes());
233        for token in [&original, &invoking] {
234            token.cancel();
235            assert_eq!(
236                SQLParam::vector_with_control(&[1.0], &control)
237                    .unwrap_err()
238                    .sqlstate(),
239                Some("57014")
240            );
241            assert_eq!(budget.used(), held.reserved_bytes());
242            token.reset();
243        }
244        let mut input = [-0.0, f32::MIN_POSITIVE, f32::MAX];
245        let vector = SQLParam::vector_with_control(&input, &control).unwrap();
246        input[1] = 1.0;
247        assert_eq!(input[1], 1.0);
248        let SQLParam::Vector(values) = &*vector else {
249            panic!("expected dedicated vector");
250        };
251        assert_eq!(values[0].to_bits(), (-0.0_f32).to_bits());
252        assert_eq!(values[1], f32::MIN_POSITIVE);
253        assert_eq!(values[2], f32::MAX);
254        assert_eq!(
255            budget.used(),
256            held.reserved_bytes() + vector.reserved_bytes()
257        );
258        drop(vector);
259        assert_eq!(budget.used(), held.reserved_bytes());
260    }
261
262    #[test]
263    fn parameter_value_owners_keep_tensor_and_scalar_payloads_until_drop() {
264        use uqa_core::{memory::MemoryBudget, CancellationToken};
265        let budget = MemoryBudget::new(1 << 16);
266        let token = CancellationToken::new();
267        let control = ProductionControl::new(&budget, &token, &token);
268        for (parameter, expected) in [
269            (
270                SQLParam::typed_scalar(Value::Str("payload".repeat(32)), ColumnType::Text),
271                Value::Str("payload".repeat(32)),
272            ),
273            (
274                SQLParam::Vector(vec![1.0, 2.5]),
275                Value::List(vec![Value::Float(1.0), Value::Float(2.5)]),
276            ),
277            (
278                SQLParam::Tensor(vec![vec![1.0, 2.5], vec![]]),
279                Value::List(vec![
280                    Value::List(vec![Value::Float(1.0), Value::Float(2.5)]),
281                    Value::List(vec![]),
282                ]),
283            ),
284        ] {
285            let value = parameter.to_value_with_control(&control).unwrap();
286            assert_eq!(*value, expected);
287            assert!(value.reserved_bytes() > 0);
288            assert_eq!(budget.used(), value.reserved_bytes());
289            drop(value);
290            assert_eq!(budget.used(), 0);
291            assert_eq!(parameter.to_value().unwrap(), expected);
292        }
293    }
294
295    #[test]
296    fn parameter_production_releases_partial_output_on_quota_and_both_tokens() {
297        use uqa_core::{memory::MemoryBudget, CancellationToken};
298        let budget = MemoryBudget::new(256);
299        let original = CancellationToken::new();
300        let invoking = CancellationToken::new();
301        let control = ProductionControl::new(&budget, &original, &invoking);
302        let held = control.copy_text("held").unwrap();
303        let parameter = SQLParam::Tensor(vec![vec![1.0; 64], vec![2.0; 64]]);
304        assert_eq!(
305            parameter
306                .to_value_with_control(&control)
307                .unwrap_err()
308                .sqlstate(),
309            Some("53200")
310        );
311        assert_eq!(budget.used(), held.reserved_bytes());
312        for token in [&original, &invoking] {
313            token.cancel();
314            assert_eq!(
315                parameter
316                    .to_value_with_control(&control)
317                    .unwrap_err()
318                    .sqlstate(),
319                Some("57014")
320            );
321            assert_eq!(budget.used(), held.reserved_bytes());
322            token.reset();
323        }
324        assert_eq!(
325            parameter.to_value().unwrap(),
326            Value::List(vec![
327                Value::List(vec![Value::Float(1.0); 64]),
328                Value::List(vec![Value::Float(2.0); 64])
329            ])
330        );
331    }
332}