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    pub fn scalar(value: Value) -> Self {
60        Self::Scalar(value)
61    }
62
63    #[must_use]
64    pub fn typed_scalar(value: Value, ty: ColumnType) -> Self {
65        Self::TypedScalar { value, ty }
66    }
67
68    /// Return the scalar carrier without changing the semantics of untyped [`SQLParam::Scalar`] values.
69    #[must_use]
70    pub fn scalar_value(&self) -> Option<&Value> {
71        match self {
72            Self::Scalar(value) | Self::TypedScalar { value, .. } => Some(value),
73            Self::Vector(_)
74            | Self::Tensor(_)
75            | Self::TypedTensor(_)
76            | Self::DeferredError { .. } => None,
77        }
78    }
79
80    /// Return an explicit scalar type, including a deferred procedural error's retained type.
81    #[must_use]
82    pub fn declared_scalar_type(&self) -> Option<&ColumnType> {
83        match self {
84            Self::TypedScalar { ty, .. } | Self::DeferredError { ty, .. } => Some(ty),
85            Self::Scalar(_) | Self::Vector(_) | Self::Tensor(_) | Self::TypedTensor(_) => None,
86        }
87    }
88
89    /// Materialize the parameter carrier with ordinary SQL value semantics.
90    pub fn to_value(&self) -> Result<Value, SQLError> {
91        self.to_value_with_control(&ProductionControl::uncontrolled())
92            .map(|value| value.into_uncontrolled().expect("ordinary parameter value"))
93    }
94
95    /// Copy a borrowed parameter while retaining every container and child payload under its producer's allowance.
96    pub fn to_value_with_control(
97        &self,
98        control: &ProductionControl<'_>,
99    ) -> Result<Produced<Value>, SQLError> {
100        control.check()?;
101        match self {
102            Self::DeferredError { error, .. } => Err((**error).clone().into()),
103            Self::Scalar(value) | Self::TypedScalar { value, .. } => Ok(control.copy_value(value)?),
104            Self::Vector(values) => vector_value(values, control),
105            Self::Tensor(vectors) => {
106                let mut output = ProductionVec::new(*control);
107                output.reserve(vectors.len())?;
108                for values in vectors {
109                    output.push_produced(vector_value(values, control)?)?;
110                }
111                let (values, memory) = output.finish()?.into_parts();
112                Ok(control.finish(Value::List(values), memory)?)
113            }
114            Self::TypedTensor(tensor) => tensor.to_value_with_control(control),
115        }
116    }
117
118    pub fn vector(v: Vec<f32>) -> Self {
119        Self::Vector(v)
120    }
121
122    /// Copy a host vector after validating its SQL dimension and finite float32 elements. The completed parameter retains the caller's original allowance.
123    pub fn vector_with_control(
124        values: &[f32],
125        control: &ProductionControl<'_>,
126    ) -> Result<Produced<Self>, SQLError> {
127        control.check()?;
128        if values.is_empty() || u32::try_from(values.len()).is_err() {
129            return Err(SQLError::TypeMismatch(
130                "vector dimension must be a positive 32-bit integer".into(),
131            ));
132        }
133        for value in values {
134            crate::expr::vector_element_with_control(&Value::Float(f64::from(*value)), control)?;
135        }
136        let mut output = ProductionVec::new(*control);
137        output.extend_from_slice(values)?;
138        let (values, memory) = output.finish()?.into_parts();
139        Ok(control.finish(Self::Vector(values), memory)?)
140    }
141
142    pub fn tensor(v: Vec<Vec<f32>>) -> Self {
143        Self::Tensor(v)
144    }
145}
146
147fn vector_value(
148    values: &[f32],
149    control: &ProductionControl<'_>,
150) -> Result<Produced<Value>, SQLError> {
151    let mut output = ProductionVec::new(*control);
152    output.reserve(values.len())?;
153    for value in values {
154        output.push_produced(
155            control.finish(Value::Float(f64::from(*value)), control.empty_reservation())?,
156        )?;
157    }
158    let (values, memory) = output.finish()?.into_parts();
159    Ok(control.finish(Value::List(values), memory)?)
160}
161
162#[cfg(test)]
163mod tests {
164    use super::*;
165
166    #[test]
167    fn deferred_parameter_keeps_scalar_carriers_compact_and_errors_lazy() {
168        assert!(size_of::<SQLParam>() <= size_of::<(Value, ColumnType, usize)>());
169        let error = crate::plpgsql::runtime_diagnostics::unassigned_record("r");
170        let parameter = SQLParam::DeferredError {
171            ty: ColumnType::SmallInteger,
172            error: Box::new((&error).into()),
173        };
174        assert_eq!(parameter.scalar_value(), None);
175        assert_eq!(
176            parameter.declared_scalar_type(),
177            Some(&ColumnType::SmallInteger)
178        );
179        let observed = parameter.to_value().unwrap_err();
180        assert_eq!(observed.sqlstate(), error.sqlstate());
181        assert_eq!(observed.to_string(), error.to_string());
182        assert_eq!(observed.detail(), error.detail());
183        assert_eq!(observed.hint(), error.hint());
184    }
185
186    #[test]
187    fn typed_scalar_preserves_declared_type_without_changing_scalar_access() {
188        let value = Value::Int(7);
189        let typed = SQLParam::typed_scalar(value.clone(), ColumnType::SmallInteger);
190        assert_eq!(typed.scalar_value(), Some(&value));
191        assert_eq!(
192            typed.declared_scalar_type(),
193            Some(&ColumnType::SmallInteger)
194        );
195
196        let scalar = SQLParam::scalar(value.clone());
197        assert_eq!(scalar.scalar_value(), Some(&value));
198        assert_eq!(scalar.declared_scalar_type(), None);
199    }
200
201    #[test]
202    fn host_vector_input_checks_shape_and_finiteness_before_retaining_bytes() {
203        use uqa_core::{memory::MemoryBudget, CancellationToken};
204        let budget = MemoryBudget::new(64);
205        let original = CancellationToken::new();
206        let invoking = CancellationToken::new();
207        let control = ProductionControl::new(&budget, &original, &invoking);
208        let held = control.copy_text("held").unwrap();
209        for values in [
210            vec![],
211            vec![f32::NAN],
212            vec![f32::INFINITY],
213            vec![f32::NEG_INFINITY],
214        ] {
215            assert!(SQLParam::vector_with_control(&values, &control).is_err());
216            assert_eq!(budget.used(), held.reserved_bytes());
217        }
218        assert_eq!(
219            SQLParam::vector_with_control(&[1.0; 64], &control)
220                .unwrap_err()
221                .sqlstate(),
222            Some("53200")
223        );
224        assert_eq!(budget.used(), held.reserved_bytes());
225        for token in [&original, &invoking] {
226            token.cancel();
227            assert_eq!(
228                SQLParam::vector_with_control(&[1.0], &control)
229                    .unwrap_err()
230                    .sqlstate(),
231                Some("57014")
232            );
233            assert_eq!(budget.used(), held.reserved_bytes());
234            token.reset();
235        }
236        let mut input = [-0.0, f32::MIN_POSITIVE, f32::MAX];
237        let vector = SQLParam::vector_with_control(&input, &control).unwrap();
238        input[1] = 1.0;
239        assert_eq!(input[1], 1.0);
240        let SQLParam::Vector(values) = &*vector else {
241            panic!("expected dedicated vector");
242        };
243        assert_eq!(values[0].to_bits(), (-0.0_f32).to_bits());
244        assert_eq!(values[1], f32::MIN_POSITIVE);
245        assert_eq!(values[2], f32::MAX);
246        assert_eq!(
247            budget.used(),
248            held.reserved_bytes() + vector.reserved_bytes()
249        );
250        drop(vector);
251        assert_eq!(budget.used(), held.reserved_bytes());
252    }
253
254    #[test]
255    fn parameter_value_owners_keep_tensor_and_scalar_payloads_until_drop() {
256        use uqa_core::{memory::MemoryBudget, CancellationToken};
257        let budget = MemoryBudget::new(1 << 16);
258        let token = CancellationToken::new();
259        let control = ProductionControl::new(&budget, &token, &token);
260        for (parameter, expected) in [
261            (
262                SQLParam::typed_scalar(Value::Str("payload".repeat(32)), ColumnType::Text),
263                Value::Str("payload".repeat(32)),
264            ),
265            (
266                SQLParam::Vector(vec![1.0, 2.5]),
267                Value::List(vec![Value::Float(1.0), Value::Float(2.5)]),
268            ),
269            (
270                SQLParam::Tensor(vec![vec![1.0, 2.5], vec![]]),
271                Value::List(vec![
272                    Value::List(vec![Value::Float(1.0), Value::Float(2.5)]),
273                    Value::List(vec![]),
274                ]),
275            ),
276        ] {
277            let value = parameter.to_value_with_control(&control).unwrap();
278            assert_eq!(*value, expected);
279            assert!(value.reserved_bytes() > 0);
280            assert_eq!(budget.used(), value.reserved_bytes());
281            drop(value);
282            assert_eq!(budget.used(), 0);
283            assert_eq!(parameter.to_value().unwrap(), expected);
284        }
285    }
286
287    #[test]
288    fn parameter_production_releases_partial_output_on_quota_and_both_tokens() {
289        use uqa_core::{memory::MemoryBudget, CancellationToken};
290        let budget = MemoryBudget::new(256);
291        let original = CancellationToken::new();
292        let invoking = CancellationToken::new();
293        let control = ProductionControl::new(&budget, &original, &invoking);
294        let held = control.copy_text("held").unwrap();
295        let parameter = SQLParam::Tensor(vec![vec![1.0; 64], vec![2.0; 64]]);
296        assert_eq!(
297            parameter
298                .to_value_with_control(&control)
299                .unwrap_err()
300                .sqlstate(),
301            Some("53200")
302        );
303        assert_eq!(budget.used(), held.reserved_bytes());
304        for token in [&original, &invoking] {
305            token.cancel();
306            assert_eq!(
307                parameter
308                    .to_value_with_control(&control)
309                    .unwrap_err()
310                    .sqlstate(),
311                Some("57014")
312            );
313            assert_eq!(budget.used(), held.reserved_bytes());
314            token.reset();
315        }
316        assert_eq!(
317            parameter.to_value().unwrap(),
318            Value::List(vec![
319                Value::List(vec![Value::Float(1.0); 64]),
320                Value::List(vec![Value::Float(2.0); 64])
321            ])
322        );
323    }
324}