Skip to main content

uqa_sql/expr/
conversion.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Scalar coercion, checked numeric conversion, and vector/tensor decoding.
8
9use super::{out_of_range, ArrayValue, DecimalValue, Result, SQLError, Value};
10
11use uqa_core::memory::{Produced, ProductionControl, ProductionString, ProductionVec};
12
13#[cfg(test)]
14mod tests;
15
16/// A value whose text is owned by the SQL catalog reached a context-free conversion. Catalog-aware callers render these carriers before delegating here.
17pub fn catalog_output_required(value: &uqa_core::EnumValue) -> SQLError {
18    SQLError::Internal(format!(
19        "enum value of type OID {} requires catalog-aware output",
20        value.type_oid()
21    ))
22}
23
24/// Produce SQL text, including errors from type output functions.
25pub fn value_to_string(value: &Value) -> Result<String> {
26    value_to_string_with_control(value, &ProductionControl::uncontrolled())
27        .map(|text| text.into_uncontrolled().expect("ordinary value text"))
28}
29
30pub fn value_to_string_with_control(
31    value: &Value,
32    control: &ProductionControl<'_>,
33) -> Result<Produced<String>> {
34    control.check()?;
35    Ok(match value {
36        Value::Null | Value::Void => control.copy_text("")?,
37        Value::Int(value) => control.format(format_args!("{value}"))?,
38        Value::Float(value) => uqa_core::format_float_pg_with_control(*value, control)?,
39        Value::Decimal(value) => value.to_sql_string_with_control(control)?,
40        Value::Str(value) | Value::Json(value) | Value::JsonB(value) => control.copy_text(value)?,
41        Value::FixedChar(value) => control.copy_text(value.trim_end_matches(' '))?,
42        Value::Bool(value) => control.copy_text(if *value { "true" } else { "false" })?,
43        Value::Temporal(value) => value.to_sql_string_in_interval_style_with_control(
44            super::temporal_interval_style(),
45            control,
46        )?,
47        Value::Array(value) => array_value_to_string_with_control(value, control)?,
48        Value::LegacyVector(_) => {
49            vector_value_to_string_with_control(value, control)?.expect("validated legacy vector")
50        }
51        Value::List(_) | Value::Map(_) => {
52            return super::json::format_value_as_json_with_control(value, control)
53        }
54        Value::Row(values) => composite_value_to_string(values.iter(), control)?,
55        Value::Record(fields) => {
56            composite_value_to_string(fields.iter().map(|(_, value)| value), control)?
57        }
58        Value::Enum(value) => return Err(catalog_output_required(value)),
59        Value::Datum(value) => {
60            return value_to_string_with_control(
61                &*super::datums::read_with_control(value, control)?,
62                control,
63            )
64        }
65        Value::Bytes(values) => bytea_to_string_with_control(values, control)?,
66        Value::BitString(value) => super::bit_string::output_with_control(value, control)?,
67    })
68}
69
70pub(crate) fn bytea_to_string_with_control(
71    values: &[u8],
72    control: &ProductionControl<'_>,
73) -> Result<Produced<String>> {
74    const HEX: &[u8; 16] = b"0123456789abcdef";
75    let mut text = ProductionString::new(*control);
76    text.reserve(values.len().saturating_mul(2).saturating_add(2))?;
77    text.push_str("\\x")?;
78    for byte in values {
79        text.push(char::from(HEX[usize::from(byte >> 4)]))?;
80        text.push(char::from(HEX[usize::from(byte & 0xf)]))?;
81    }
82    Ok(text.finish()?)
83}
84
85/// `PostgreSQL`'s legacy vector text format separates values with spaces.
86pub fn vector_value_to_string(value: &Value) -> Result<Option<String>> {
87    vector_value_to_string_with_control(value, &ProductionControl::uncontrolled())
88        .map(|text| text.map(|text| text.into_uncontrolled().expect("ordinary vector text")))
89}
90
91pub(crate) fn vector_value_to_string_with_control(
92    value: &Value,
93    control: &ProductionControl<'_>,
94) -> Result<Option<Produced<String>>> {
95    control.check()?;
96    let elements = match value {
97        Value::LegacyVector(vector) => {
98            if !vector.has_vector_layout() {
99                return Err(SQLError::Routine {
100                    sqlstate: "42804".into(),
101                    message: format!("array is not a valid {}", vector.kind().type_name()),
102                });
103            }
104            vector.elements()
105        }
106        Value::List(elements) => elements.as_slice(),
107        Value::Array(array) if array.dimensions().len() <= 1 => array.elements(),
108        _ => return Ok(None),
109    };
110    let mut text = ProductionString::new(*control);
111    for (index, value) in elements.iter().enumerate() {
112        if index != 0 {
113            text.push(' ')?;
114        }
115        text.push_str(&value_to_string_with_control(value, control)?)?;
116    }
117    Ok(Some(text.finish()?))
118}
119
120pub fn array_value_to_string(array: &ArrayValue) -> Result<String> {
121    array_value_to_string_with_control(array, &ProductionControl::uncontrolled())
122        .map(|text| text.into_uncontrolled().expect("ordinary array text"))
123}
124
125pub(super) fn array_value_to_string_with_control(
126    array: &ArrayValue,
127    control: &ProductionControl<'_>,
128) -> Result<Produced<String>> {
129    let mut text = ProductionString::new(*control);
130    append_array(&mut text, array, control)?;
131    Ok(text.finish()?)
132}
133
134fn append_array(
135    text: &mut ProductionString<'_>,
136    array: &ArrayValue,
137    control: &ProductionControl<'_>,
138) -> Result<()> {
139    if !array.elements().is_empty() && array.lower_bounds().iter().any(|lower| *lower != 1) {
140        for (lower, length) in array.lower_bounds().iter().zip(array.dimensions()) {
141            let upper = i64::from(*lower) + i64::try_from(*length).unwrap_or(i64::MAX) - 1;
142            text.push_str(&control.format(format_args!("[{lower}:{upper}]"))?)?;
143        }
144        text.push('=')?;
145    }
146    append_array_elements(text, array.elements(), control)
147}
148
149fn append_array_elements(
150    text: &mut ProductionString<'_>,
151    elements: &[Value],
152    control: &ProductionControl<'_>,
153) -> Result<()> {
154    text.push('{')?;
155    for (index, value) in elements.iter().enumerate() {
156        if index != 0 {
157            text.push(',')?;
158        }
159        match value {
160            Value::Null => text.push_str("NULL")?,
161            Value::Bool(value) => text.push_str(if *value { "t" } else { "f" })?,
162            Value::List(values) => append_array_elements(text, values, control)?,
163            Value::Array(array) => append_array(text, array, control)?,
164            other => {
165                let value = container_field_to_string(other, control)?;
166                let mut quoted = value.is_empty() || value.eq_ignore_ascii_case("null");
167                for character in value.chars() {
168                    control.check()?;
169                    quoted |= (character.is_ascii() && character.is_whitespace())
170                        || matches!(character, ',' | '{' | '}' | '"' | '\\');
171                }
172                append_escaped(text, &value, quoted, false)?;
173            }
174        }
175    }
176    text.push('}')?;
177    Ok(())
178}
179
180fn composite_value_to_string<'a>(
181    values: impl IntoIterator<Item = &'a Value>,
182    control: &ProductionControl<'_>,
183) -> Result<Produced<String>> {
184    let mut text = ProductionString::new(*control);
185    text.push('(')?;
186    for (index, value) in values.into_iter().enumerate() {
187        if index != 0 {
188            text.push(',')?;
189        }
190        if matches!(value, Value::Null) {
191            continue;
192        }
193        let value = container_field_to_string(value, control)?;
194        let mut quoted = value.is_empty();
195        for byte in value.bytes() {
196            control.check()?;
197            quoted |=
198                matches!(byte, b',' | b'(' | b')' | b'"' | b'\\') || byte.is_ascii_whitespace();
199        }
200        append_escaped(&mut text, &value, quoted, true)?;
201    }
202    text.push(')')?;
203    Ok(text.finish()?)
204}
205
206/// Container fields use type output, preserving bpchar padding independently of scalar text coercion.
207fn container_field_to_string(
208    value: &Value,
209    control: &ProductionControl<'_>,
210) -> Result<Produced<String>> {
211    match value {
212        Value::Bool(value) => Ok(control.copy_text(if *value { "t" } else { "f" })?),
213        Value::FixedChar(value) => Ok(control.copy_text(value)?),
214        Value::Datum(value) => {
215            container_field_to_string(&*super::datums::read_with_control(value, control)?, control)
216        }
217        other => value_to_string_with_control(other, control),
218    }
219}
220
221fn append_escaped(
222    text: &mut ProductionString<'_>,
223    value: &str,
224    quoted: bool,
225    composite: bool,
226) -> Result<()> {
227    if !quoted {
228        text.push_str(value)?;
229        return Ok(());
230    }
231    text.push('"')?;
232    for character in value.chars() {
233        if character == '\\' || (character == '"' && !composite) {
234            text.push('\\')?;
235        }
236        if character == '"' && composite {
237            text.push('"')?;
238        }
239        text.push(character)?;
240    }
241    text.push('"')?;
242    Ok(())
243}
244
245pub(super) fn float1_with_control<F: FnOnce(f64) -> f64>(
246    args: &[Value],
247    name: &str,
248    f: F,
249    control: &ProductionControl<'_>,
250) -> Result<Value> {
251    control.check()?;
252    if args.len() != 1 {
253        return Err(SQLError::TypeMismatch(format!("{name} takes 1 arg")));
254    }
255    if matches!(args[0], Value::Null) {
256        return Ok(Value::Null);
257    }
258    Ok(Value::Float(f(to_f64_with_control(&args[0], control)?)))
259}
260
261pub(super) fn to_i64(v: &Value) -> Result<i64> {
262    to_i64_with_control(v, &ProductionControl::uncontrolled())
263}
264
265pub(super) fn to_i64_with_control(v: &Value, control: &ProductionControl<'_>) -> Result<i64> {
266    if let Value::Datum(datum) = v {
267        return to_i64_with_control(&*super::datums::read_with_control(datum, control)?, control);
268    }
269    control.check()?;
270    match v {
271        Value::Int(n) => Ok(*n),
272        Value::Float(f) => float_to_i64_trunc(*f),
273        Value::Decimal(d) => d
274            .to_i64_trunc_with_control(control)?
275            .ok_or_else(|| SQLError::TypeMismatch(format!("cannot cast {v:?} to integer"))),
276        Value::Bool(b) => Ok(i64::from(*b)),
277        Value::Str(s) | Value::FixedChar(s) => s
278            .trim()
279            .parse()
280            .map_err(|_| SQLError::TypeMismatch(format!("cannot parse {s:?} as integer"))),
281        other => Err(SQLError::TypeMismatch(format!(
282            "expected integer, got {other:?}"
283        ))),
284    }
285}
286
287pub(super) fn nonnegative_usize(value: i64, label: &str) -> Result<usize> {
288    usize::try_from(value).map_err(|_| SQLError::Routine {
289        sqlstate: "22003".into(),
290        message: format!("{label} exceeds the platform addressable range"),
291    })
292}
293
294pub(super) fn allocation_error(label: &str) -> SQLError {
295    SQLError::Routine {
296        sqlstate: "53200".into(),
297        message: format!("{label} result exceeds available memory"),
298    }
299}
300
301pub(crate) fn to_f64(v: &Value) -> Result<f64> {
302    to_f64_with_control(v, &ProductionControl::uncontrolled())
303}
304
305pub(crate) fn to_f64_with_control(v: &Value, control: &ProductionControl<'_>) -> Result<f64> {
306    if let Value::Datum(datum) = v {
307        return to_f64_with_control(&*super::datums::read_with_control(datum, control)?, control);
308    }
309    super::floating::to_float_with_control(v, super::FloatWidth::DoublePrecision, control)
310}
311
312/// The error `numeric_in` reports for text it cannot read.
313#[must_use]
314pub fn invalid_numeric_input(text: &str) -> SQLError {
315    SQLError::Routine {
316        sqlstate: "22P02".into(),
317        message: format!("invalid input syntax for type numeric: \"{text}\""),
318    }
319}
320
321pub(super) fn to_decimal(value: &Value) -> Result<DecimalValue> {
322    to_decimal_with_control(value, &ProductionControl::uncontrolled())?
323        .into_uncontrolled()
324        .map_err(|_| SQLError::Internal("ordinary numeric production owner".into()))
325}
326
327pub(super) fn to_decimal_with_control(
328    value: &Value,
329    control: &ProductionControl<'_>,
330) -> Result<Produced<DecimalValue>> {
331    control.check()?;
332    match value {
333        Value::Datum(datum) => {
334            to_decimal_with_control(&*super::datums::read_with_control(datum, control)?, control)
335        }
336        Value::Decimal(value) => Ok(value.clone_with_control(control)?),
337        Value::Int(value) => Ok(DecimalValue::from_i64_with_control(*value, control)?),
338        Value::Bool(value) => Ok(DecimalValue::from_i64_with_control(
339            i64::from(*value),
340            control,
341        )?),
342        Value::Float(number) => DecimalValue::from_f64_lossy_with_control(*number, control)?
343            .ok_or_else(|| SQLError::TypeMismatch(format!("cannot cast {value:?} to numeric"))),
344        Value::Str(text) | Value::FixedChar(text) => {
345            DecimalValue::parse_with_control(text, control)?
346                .ok_or_else(|| invalid_numeric_input(text))
347        }
348        other => Err(SQLError::TypeMismatch(format!(
349            "expected number, got {other:?}"
350        ))),
351    }
352}
353
354pub(super) fn float_to_i64_trunc(value: f64) -> Result<i64> {
355    if !value.is_finite() || value < i64::MIN as f64 || value >= 9_223_372_036_854_775_808.0 {
356        return Err(out_of_range("bigint"));
357    }
358    Ok(value.trunc() as i64)
359}
360
361pub(super) fn float_to_i64_rounded(value: f64, type_name: &str) -> Result<i64> {
362    let rounded = value.round();
363    if !rounded.is_finite() || rounded < i64::MIN as f64 || rounded >= 9_223_372_036_854_775_808.0 {
364        return Err(out_of_range(type_name));
365    }
366    Ok(rounded as i64)
367}
368
369pub(super) fn gcd_i64(a: i64, b: i64) -> Result<i64> {
370    let mut a = a.unsigned_abs();
371    let mut b = b.unsigned_abs();
372    while b != 0 {
373        let r = a % b;
374        a = b;
375        b = r;
376    }
377    i64::try_from(a).map_err(|_| out_of_range("bigint"))
378}
379
380/// Coerce a [`Value`] into a `Vec<f32>` if it is a homogeneous numeric
381/// list (used to read vector literals from `ARRAY[...]` or `$N` Vector
382/// params).
383pub fn value_to_vector(v: &Value) -> Result<Vec<f32>> {
384    value_to_vector_with_control(v, &ProductionControl::uncontrolled())?
385        .into_uncontrolled()
386        .map_err(|_| SQLError::Internal("ordinary vector owner".into()))
387}
388
389pub fn value_to_vector_with_control(
390    v: &Value,
391    control: &ProductionControl<'_>,
392) -> Result<Produced<Vec<f32>>> {
393    let items = vector_items(v)?;
394    let mut out = ProductionVec::new(*control);
395    out.reserve(items.len())?;
396    for item in items {
397        out.push_copy(vector_element_with_control(item, control)?)?;
398    }
399    Ok(out.finish()?)
400}
401
402pub(crate) fn vector_items(v: &Value) -> Result<&[Value]> {
403    match v {
404        Value::List(items) => Ok(items.as_slice()),
405        Value::Array(array) if array.dimensions().len() <= 1 => Ok(array.elements()),
406        Value::Array(array) => Err(SQLError::TypeMismatch(format!(
407            "expected one-dimensional vector input, got {} dimensions",
408            array.dimensions().len()
409        ))),
410        other => Err(SQLError::TypeMismatch(format!(
411            "expected vector (numeric array), got {other:?}"
412        ))),
413    }
414}
415
416pub(crate) fn vector_element(item: &Value) -> Result<f32> {
417    vector_element_with_control(item, &ProductionControl::uncontrolled())
418}
419
420pub(crate) fn vector_element_with_control(
421    item: &Value,
422    control: &ProductionControl<'_>,
423) -> Result<f32> {
424    control.check()?;
425    match item {
426        Value::Float(f) => numeric_f64_to_f32(*f, item),
427        Value::Int(i) => Ok(*i as f32),
428        Value::Decimal(d) => numeric_f64_to_f32(
429            d.to_f64_with_control(control)?.ok_or_else(|| {
430                SQLError::TypeMismatch(format!("vector element must fit f32, got {item:?}"))
431            })?,
432            item,
433        ),
434        other => Err(SQLError::TypeMismatch(format!(
435            "vector element must be numeric, got {other:?}"
436        ))),
437    }
438}
439
440pub(super) fn numeric_f64_to_f32(value: f64, source: &Value) -> Result<f32> {
441    if !value.is_finite() || value < -(f32::MAX as f64) || value > f32::MAX as f64 {
442        return Err(SQLError::TypeMismatch(format!(
443            "vector element must be finite and fit f32, got {source:?}"
444        )));
445    }
446    Ok(value as f32)
447}
448
449/// Coerce a [`Value`] into a tensor: an array of homogeneous numeric
450/// vectors. Used by `TENSOR(N)` columns to store chunk embeddings for one
451/// row while still indexing each vector element.
452pub fn value_to_tensor(v: &Value) -> Result<Vec<Vec<f32>>> {
453    value_to_tensor_with_control(v, &ProductionControl::uncontrolled())?
454        .into_uncontrolled()
455        .map_err(|_| SQLError::Internal("ordinary tensor owner".into()))
456}
457
458pub fn value_to_tensor_with_control(
459    v: &Value,
460    control: &ProductionControl<'_>,
461) -> Result<Produced<Vec<Vec<f32>>>> {
462    let items = tensor_items(v)?;
463    let mut out = ProductionVec::new(*control);
464    out.reserve(items.len())?;
465    for item in items {
466        out.push_produced(value_to_vector_with_control(item, control)?)?;
467    }
468    Ok(out.finish()?)
469}
470
471pub(crate) fn tensor_items(v: &Value) -> Result<&[Value]> {
472    match v {
473        Value::List(items) => Ok(items.as_slice()),
474        Value::Array(array) if array.dimensions().is_empty() || array.dimensions().len() == 2 => {
475            Ok(array.elements())
476        }
477        Value::Array(array) => Err(SQLError::TypeMismatch(format!(
478            "expected two-dimensional tensor input, got {} dimensions",
479            array.dimensions().len()
480        ))),
481        other => Err(SQLError::TypeMismatch(format!(
482            "expected tensor (array of numeric arrays), got {other:?}"
483        ))),
484    }
485}