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