Skip to main content

uqa_sql/expr/
json.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! JSON scalar-function helpers for the expression evaluator.
8
9use uqa_core::{DecimalValue, TemporalValue, Value};
10
11use crate::error::{Result, SQLError};
12
13use super::{hex_encode, out_of_range};
14
15mod diagnostics;
16mod path;
17mod production;
18#[cfg(test)]
19pub(super) use production::json_delete_with_control;
20pub(super) use production::{
21    cast_json_value_with_control, compare_jsonb_datums_with_control, evaluate,
22    format_core_value_as_json_with_control, format_value_as_json_with_control,
23    json_concat_with_control, json_delete_values_with_control, json_extract_operator_with_control,
24    json_path_function_with_control, quote_with_control, utf8_lossy_with_control, JsonbInput,
25};
26pub(crate) use production::{
27    decode_jsonb_datum_with_control, encode_jsonb_datum, encode_jsonb_datum_with_control,
28};
29
30pub(super) use path::{jsonpath_candidate, jsonpath_match};
31
32/// Quote borrowed UTF-8 with the native JSON string escaper, charging output and bounded scratch to the invoking allowance.
33pub fn quote_json_string_with_control(
34    text: &str,
35    control: &uqa_core::memory::ProductionControl<'_>,
36) -> Result<uqa_core::memory::Produced<String>> {
37    production::quote_with_control(text, control)
38}
39
40pub(super) fn parse_json(s: &str) -> Result<serde_json::Value> {
41    serde_json::from_str::<serde_json::Value>(s)
42        .map_err(|_| super::json_strip::invalid_json_input(s))
43}
44
45/// Render a parsed JSON value in `PostgreSQL`'s compact result format. JSONB
46/// objects use `PostgreSQL`'s length-then-bytewise key ordering.
47pub(super) fn format_json(value: &serde_json::Value, jsonb: bool) -> String {
48    if !jsonb {
49        return serde_json::to_string(value).expect("serializing a JSON value cannot fail");
50    }
51    match value {
52        serde_json::Value::Null => "null".to_string(),
53        serde_json::Value::Bool(value) => value.to_string(),
54        serde_json::Value::Number(value) => {
55            let text = value.to_string();
56            DecimalValue::parse(&text).map_or(text, |value| value.to_sql_string())
57        }
58        serde_json::Value::String(value) => serde_json::Value::String(value.clone()).to_string(),
59        serde_json::Value::Array(values) => {
60            let values = values
61                .iter()
62                .map(|value| format_json(value, true))
63                .collect::<Vec<_>>();
64            format!("[{}]", values.join(", "))
65        }
66        serde_json::Value::Object(values) => {
67            let mut values = values.iter().collect::<Vec<_>>();
68            values.sort_by(|(left, _), (right, _)| {
69                left.len()
70                    .cmp(&right.len())
71                    .then_with(|| left.as_bytes().cmp(right.as_bytes()))
72            });
73            let values = values
74                .into_iter()
75                .map(|(key, value)| {
76                    let key = serde_json::Value::String(key.clone()).to_string();
77                    format!("{key}: {}", format_json(value, true))
78                })
79                .collect::<Vec<_>>();
80            format!("{{{}}}", values.join(", "))
81        }
82    }
83}
84
85#[cfg(test)]
86fn format_jsonb_pretty(value: &serde_json::Value) -> String {
87    let Value::Str(text) =
88        ordinary("jsonb_pretty", &[Value::Json(value.to_string())]).expect("valid parsed JSON")
89    else {
90        unreachable!("JSON pretty text")
91    };
92    text
93}
94
95pub(super) fn typed_json_value(value: &serde_json::Value, jsonb: bool) -> Result<Value> {
96    if jsonb {
97        validate_jsonb_numbers(value)?;
98    }
99    let text = format_json(value, jsonb);
100    if jsonb {
101        Ok(Value::JsonB(text))
102    } else {
103        Ok(Value::Json(text))
104    }
105}
106
107fn validate_jsonb_numbers(value: &serde_json::Value) -> Result<()> {
108    match value {
109        serde_json::Value::Number(value) => DecimalValue::parse(&value.to_string())
110            .map(|_| ())
111            .ok_or_else(|| out_of_range("numeric")),
112        serde_json::Value::Array(values) => values.iter().try_for_each(validate_jsonb_numbers),
113        serde_json::Value::Object(values) => values.values().try_for_each(validate_jsonb_numbers),
114        _ => Ok(()),
115    }
116}
117
118/// Render an engine value as `PostgreSQL` JSON input text without losing the
119/// lexical representation of values already typed as `json` or `jsonb`.
120pub fn value_to_json_text(value: &Value) -> Result<String> {
121    value_to_json_text_with_catalog(value, None)
122}
123
124/// Render admitted composite, array and enum values through the observing statement's catalog.
125pub fn value_to_json_text_with_catalog(
126    value: &Value,
127    catalog: Option<&dyn super::SQLValueCatalog>,
128) -> Result<String> {
129    Ok(match value {
130        Value::Null => "null".to_string(),
131        Value::Void => "\"\"".to_string(),
132        Value::Bool(value) => value.to_string(),
133        Value::Int(value) => value.to_string(),
134        Value::Float(value) => match serde_json::Number::from_f64(*value) {
135            Some(number) => number.to_string(),
136            None if value.is_nan() => "\"NaN\"".to_string(),
137            None if value.is_sign_positive() => "\"Infinity\"".to_string(),
138            None => "\"-Infinity\"".to_string(),
139        },
140        Value::Decimal(value) => value.to_sql_string(),
141        Value::Str(value) => serde_json::Value::String(value.clone()).to_string(),
142        Value::FixedChar(value) => {
143            serde_json::Value::String(value.trim_end_matches(' ').to_string()).to_string()
144        }
145        Value::Bytes(value) => {
146            serde_json::Value::String(format!("0x{}", hex_encode(value))).to_string()
147        }
148        Value::Temporal(_) | Value::BitString(_) => {
149            serde_json::Value::String(super::value_to_string(value)?).to_string()
150        }
151        Value::Json(text) | Value::JsonB(text) => text.clone(),
152        Value::Enum(value) => {
153            serde_json::Value::String(super::enums::enum_label(catalog, value)?.label).to_string()
154        }
155        Value::Datum(datum) => {
156            let control = uqa_core::memory::ProductionControl::uncontrolled();
157            let value =
158                super::datums::read_with_value_catalog_and_control(datum, catalog, &control)?;
159            return typed_json_text(&value, Some(datum.type_oid()), catalog);
160        }
161        Value::LegacyVector(vector) => legacy_vector_json(vector).to_string(),
162        Value::Array(array) => {
163            array_json_text(array.elements(), array.element_type_oid(), catalog)?
164        }
165        Value::List(values) => {
166            let values = values
167                .iter()
168                .map(|value| value_to_json_text_with_catalog(value, catalog))
169                .collect::<Result<Vec<_>>>()?;
170            format!("[{}]", values.join(","))
171        }
172        Value::Row(values) => record_json_text(
173            values.iter().enumerate().map(|(index, value)| {
174                (
175                    format!("f{}", index + 1),
176                    value,
177                    values
178                        .field_types()
179                        .and_then(|types| types.get(index))
180                        .map(|ty| ty.oid),
181                )
182            }),
183            catalog,
184        )?,
185        Value::Record(fields) => {
186            let descriptor = fields
187                .type_oid()
188                .and_then(|oid| catalog.map(|catalog| (oid, catalog)))
189                .map(|(oid, catalog)| catalog.value_composite_type(oid))
190                .transpose()?
191                .flatten();
192            record_json_text(
193                fields.iter().map(|(name, value)| {
194                    let oid = descriptor
195                        .as_ref()
196                        .and_then(|descriptor| descriptor.attribute(name))
197                        .map(|(_, attribute)| {
198                            crate::catalog::type_metadata::pg_type_oid(&attribute.ty) as u32
199                        });
200                    (name.clone(), value, oid)
201                }),
202                catalog,
203            )?
204        }
205        Value::Map(values) => {
206            let values = values
207                .iter()
208                .map(|(key, value)| {
209                    let key = serde_json::Value::String(key.clone()).to_string();
210                    Ok(format!(
211                        "{key}:{}",
212                        value_to_json_text_with_catalog(value, catalog)?
213                    ))
214                })
215                .collect::<Result<Vec<_>>>()?;
216            format!("{{{}}}", values.join(","))
217        }
218    })
219}
220
221fn array_json_text(
222    values: &[Value],
223    oid: Option<u32>,
224    catalog: Option<&dyn super::SQLValueCatalog>,
225) -> Result<String> {
226    let fields = values
227        .iter()
228        .map(|value| match value {
229            Value::List(values) => array_json_text(values, oid, catalog),
230            value => typed_json_text(value, oid, catalog),
231        })
232        .collect::<Result<Vec<_>>>()?;
233    Ok(format!("[{}]", fields.join(",")))
234}
235
236fn legacy_vector_json(vector: &uqa_core::LegacyVectorValue) -> serde_json::Value {
237    serde_json::Value::Array(
238        vector
239            .elements()
240            .iter()
241            .map(|value| {
242                let Value::Int(value) = value else {
243                    unreachable!("validated legacy vector element");
244                };
245                match vector.kind() {
246                    uqa_core::LegacyVectorKind::SmallInteger => (*value).into(),
247                    uqa_core::LegacyVectorKind::Oid => value.to_string().into(),
248                }
249            })
250            .collect(),
251    )
252}
253
254fn record_json_text<'a>(
255    fields: impl IntoIterator<Item = (String, &'a Value, Option<u32>)>,
256    catalog: Option<&dyn super::SQLValueCatalog>,
257) -> Result<String> {
258    let fields = fields
259        .into_iter()
260        .map(|(name, value, oid)| {
261            let name = serde_json::Value::String(name).to_string();
262            Ok(format!("{name}:{}", typed_json_text(value, oid, catalog)?))
263        })
264        .collect::<Result<Vec<_>>>()?;
265    Ok(format!("{{{}}}", fields.join(",")))
266}
267
268fn typed_json_text(
269    value: &Value,
270    oid: Option<u32>,
271    catalog: Option<&dyn super::SQLValueCatalog>,
272) -> Result<String> {
273    if let Value::Float(value) = value {
274        if value.is_finite() {
275            let resolved = oid
276                .filter(|oid| !matches!(oid, 700 | 701))
277                .and_then(|oid| catalog.map(|catalog| (oid, catalog)))
278                .map(|(oid, catalog)| catalog.value_type_by_oid(oid))
279                .transpose()?
280                .flatten();
281            let mut base = resolved.as_ref();
282            while let Some(crate::ColumnType::Domain { base: inner, .. }) = base {
283                base = Some(inner);
284            }
285            if oid == Some(700) || matches!(base, Some(crate::ColumnType::Real)) {
286                return Ok(super::format_real(*value as f32));
287            }
288        }
289    }
290    value_to_json_text_with_catalog(value, catalog)
291}
292
293pub(super) fn json_build_array_value(
294    args: &[Value],
295    jsonb: bool,
296    catalog: Option<&dyn super::SQLValueCatalog>,
297) -> Result<Value> {
298    let text = format!(
299        "[{}]",
300        args.iter()
301            .map(|value| value_to_json_text_with_catalog(value, catalog))
302            .collect::<Result<Vec<_>>>()?
303            .join(", ")
304    );
305    if jsonb {
306        typed_json_value(&parse_json(&text)?, true)
307    } else {
308        Ok(Value::Json(text))
309    }
310}
311
312/// JSON object keys must be scalar SQL datums, including when an array-shaped catalog vector has a distinct runtime carrier. Each constructor retains its own NULL-key diagnostic.
313pub fn validate_json_object_key_type(value: &Value) -> Result<()> {
314    validate_json_object_key_type_with_catalog(value, None)
315}
316
317pub fn validate_json_object_key_type_with_catalog(
318    value: &Value,
319    catalog: Option<&dyn super::SQLValueCatalog>,
320) -> Result<()> {
321    let physical_container = if let Value::Datum(datum) = value {
322        let oid = datum.type_oid();
323        let ty = catalog
324            .map(|catalog| catalog.value_type_by_oid(oid))
325            .transpose()?
326            .flatten();
327        let mut ty = ty.as_ref();
328        while let Some(crate::ColumnType::Domain { base, .. }) = ty {
329            ty = Some(base);
330        }
331        matches!(oid, 22 | 30 | 114 | 2249 | 3802)
332            || crate::catalog::type_metadata::builtin_array_element(oid).is_some()
333            || matches!(
334                ty,
335                Some(
336                    crate::ColumnType::Array(_)
337                        | crate::ColumnType::Composite(_)
338                        | crate::ColumnType::Record
339                        | crate::ColumnType::Json
340                        | crate::ColumnType::JsonB
341                )
342            )
343    } else {
344        false
345    };
346    if physical_container
347        || matches!(
348            value,
349            Value::Array(_)
350                | Value::LegacyVector(_)
351                | Value::List(_)
352                | Value::Row(_)
353                | Value::Record(_)
354                | Value::Map(_)
355                | Value::Json(_)
356                | Value::JsonB(_)
357        )
358    {
359        return Err(SQLError::Routine {
360            sqlstate: "22023".into(),
361            message: "key value must be scalar, not array, composite, or json".into(),
362        });
363    }
364    Ok(())
365}
366
367fn scalar_key(value: &Value, catalog: Option<&dyn super::SQLValueCatalog>) -> Result<String> {
368    match value {
369        Value::Datum(datum) => {
370            let decoded = super::datums::read_with_value_catalog_and_control(
371                datum,
372                catalog,
373                &uqa_core::memory::ProductionControl::uncontrolled(),
374            )?;
375            scalar_key(&decoded, catalog)
376        }
377        Value::Enum(value) => Ok(super::enums::enum_label(catalog, value)?.label),
378        _ => super::value_to_string(value),
379    }
380}
381
382pub(super) fn json_build_object_value(
383    args: &[Value],
384    jsonb: bool,
385    catalog: Option<&dyn super::SQLValueCatalog>,
386) -> Result<Value> {
387    let function = if jsonb {
388        "jsonb_build_object()"
389    } else {
390        "json_build_object()"
391    };
392    if !args.len().is_multiple_of(2) {
393        return Err(SQLError::Diagnostic {
394            sqlstate: "22023".into(),
395            message: "argument list must have even number of elements".into(),
396            detail: None,
397            hint: Some(format!(
398                "The arguments of {function} must consist of alternating keys and values."
399            )),
400        });
401    }
402    let mut fields = Vec::with_capacity(args.len() / 2);
403    for (index, pair) in args.as_chunks::<2>().0.iter().enumerate() {
404        if matches!(pair[0], Value::Null) {
405            return Err(if jsonb {
406                SQLError::Routine {
407                    sqlstate: "22023".into(),
408                    message: format!("argument {}: key must not be null", index * 2 + 1),
409                }
410            } else {
411                SQLError::Routine {
412                    sqlstate: "22004".into(),
413                    message: "null value not allowed for object key".into(),
414                }
415            });
416        }
417        validate_json_object_key_type_with_catalog(&pair[0], catalog)?;
418        let key = serde_json::Value::String(scalar_key(&pair[0], catalog)?).to_string();
419        fields.push(format!(
420            "{key} : {}",
421            value_to_json_text_with_catalog(&pair[1], catalog)?
422        ));
423    }
424    let text = format!("{{{}}}", fields.join(", "));
425    if jsonb {
426        typed_json_value(&parse_json(&text)?, true)
427    } else {
428        Ok(Value::Json(text))
429    }
430}
431
432#[cfg(test)]
433pub(super) fn value_to_json(v: &Value) -> serde_json::Value {
434    match v {
435        Value::Datum(datum) => {
436            value_to_json(&super::datums::read(datum).expect("test datum output"))
437        }
438        Value::Null => serde_json::Value::Null,
439        Value::Void => serde_json::Value::String(String::new()),
440        Value::Bool(b) => serde_json::Value::Bool(*b),
441        Value::Int(i) => serde_json::Value::Number((*i).into()),
442        Value::Float(f) => serde_json::Number::from_f64(*f).map_or_else(
443            || {
444                let label = if f.is_nan() {
445                    "NaN"
446                } else if f.is_sign_positive() {
447                    "Infinity"
448                } else {
449                    "-Infinity"
450                };
451                serde_json::Value::String(label.to_string())
452            },
453            serde_json::Value::Number,
454        ),
455        Value::Decimal(d) => {
456            if d.is_nan() || d.is_infinite() {
457                serde_json::Value::String(d.to_sql_string())
458            } else {
459                d.to_sql_string()
460                    .parse::<serde_json::Number>()
461                    .map(serde_json::Value::Number)
462                    .unwrap_or_else(|_| serde_json::Value::String(d.to_sql_string()))
463            }
464        }
465        Value::Str(s) => serde_json::Value::String(s.clone()),
466        Value::FixedChar(s) => serde_json::Value::String(s.trim_end_matches(' ').to_string()),
467        Value::Bytes(b) => serde_json::Value::String(format!("0x{}", hex_encode(b))),
468        Value::BitString(_) => {
469            serde_json::Value::String(super::value_to_string(v).expect("test bit-string output"))
470        }
471        Value::Temporal(t) => serde_json::Value::String(t.to_sql_string()),
472        Value::Json(text) | Value::JsonB(text) => {
473            serde_json::from_str(text).unwrap_or_else(|_| serde_json::Value::String(text.clone()))
474        }
475        Value::LegacyVector(vector) => legacy_vector_json(vector),
476        Value::Array(array) => {
477            serde_json::Value::Array(array.elements().iter().map(value_to_json).collect())
478        }
479        Value::List(items) => serde_json::Value::Array(items.iter().map(value_to_json).collect()),
480        Value::Row(values) => serde_json::Value::Object(
481            values
482                .iter()
483                .enumerate()
484                .map(|(index, value)| (format!("f{}", index + 1), value_to_json(value)))
485                .collect(),
486        ),
487        Value::Record(fields) => serde_json::Value::Object(
488            fields
489                .iter()
490                .map(|(name, value)| (name.clone(), value_to_json(value)))
491                .collect(),
492        ),
493        Value::Map(map) => {
494            let mut obj = serde_json::Map::new();
495            for (k, v) in map {
496                obj.insert(k.clone(), value_to_json(v));
497            }
498            serde_json::Value::Object(obj)
499        }
500        Value::Enum(value) => panic!(
501            "test JSON has no enum label for type OID {}",
502            value.type_oid()
503        ),
504    }
505}
506
507#[allow(dead_code)]
508pub(super) fn json_to_value(json: &serde_json::Value) -> Value {
509    match json {
510        serde_json::Value::Null => Value::Null,
511        serde_json::Value::Bool(b) => Value::Bool(*b),
512        serde_json::Value::Number(n) => {
513            if let Some(i) = n.as_i64() {
514                Value::Int(i)
515            } else if let Some(d) = DecimalValue::parse(&n.to_string()) {
516                Value::Decimal(d)
517            } else if let Some(f) = n.as_f64() {
518                Value::Float(f)
519            } else {
520                Value::Null
521            }
522        }
523        serde_json::Value::String(s) => Value::Str(s.clone()),
524        serde_json::Value::Array(arr) => Value::List(arr.iter().map(json_to_value).collect()),
525        serde_json::Value::Object(obj) => {
526            if let Ok(temporal) =
527                serde_json::from_value::<TemporalValue>(serde_json::Value::Object(obj.clone()))
528            {
529                return Value::Temporal(temporal);
530            }
531            let mut map = std::collections::BTreeMap::new();
532            for (k, v) in obj {
533                map.insert(k.clone(), json_to_value(v));
534            }
535            Value::Map(map)
536        }
537    }
538}
539
540fn ordinary(name: &str, args: &[Value]) -> Result<Value> {
541    Ok(production::evaluate(
542        name,
543        args,
544        &uqa_core::memory::ProductionControl::uncontrolled(),
545    )
546    .expect("known JSON builtin")?
547    .into_uncontrolled()
548    .expect("ordinary JSON has no lease"))
549}
550
551fn json_array_index(len: usize, key: &str) -> Option<usize> {
552    let index = key.parse::<i64>().ok()?;
553    let normalized = if index < 0 { len as i64 + index } else { index };
554    usize::try_from(normalized).ok().filter(|idx| *idx < len)
555}
556
557fn json_insert_index(len: usize, key: &str, insert_after: bool) -> Option<usize> {
558    let raw = key.parse::<i64>().ok()?;
559    let len_i64 = len as i64;
560    let index = if raw >= 0 {
561        if raw >= len_i64 {
562            len_i64
563        } else if insert_after {
564            raw + 1
565        } else {
566            raw
567        }
568    } else {
569        let normalized = len_i64 + raw;
570        if normalized < 0 {
571            0
572        } else if insert_after {
573            normalized + 1
574        } else {
575            normalized
576        }
577    };
578    usize::try_from(index.clamp(0, len_i64)).ok()
579}
580
581#[cfg(test)]
582mod pretty_tests {
583    use super::{format_jsonb_pretty, parse_json, typed_json_value, DecimalValue};
584
585    #[test]
586    fn jsonb_pretty_uses_postgresql_layout_and_key_order() {
587        let value = parse_json(r#"{"zz":1,"b":[],"aa":{"long":3,"x":2}}"#).unwrap();
588        assert_eq!(
589            format_jsonb_pretty(&value),
590            "{\n    \"b\": [\n    ],\n    \"aa\": {\n        \"x\": 2,\n        \"long\": 3\n    },\n    \"zz\": 1\n}"
591        );
592        assert_eq!(format_jsonb_pretty(&parse_json("[]").unwrap()), "[\n]");
593        assert_eq!(format_jsonb_pretty(&parse_json("{}").unwrap()), "{\n}");
594        assert_eq!(
595            format_jsonb_pretty(&parse_json("1e-1000").unwrap()),
596            DecimalValue::parse("1e-1000").unwrap().to_sql_string()
597        );
598        assert_eq!(format_jsonb_pretty(&parse_json("1.00").unwrap()), "1.00");
599        assert_eq!(format_jsonb_pretty(&parse_json("-0").unwrap()), "0");
600    }
601
602    #[test]
603    fn jsonb_rejects_numbers_outside_postgresql_numeric_range() {
604        let maximum = parse_json("1e131071").unwrap();
605        assert!(typed_json_value(&maximum, true).is_ok());
606
607        for text in ["1e131072", "1e-16384", "[1e131072]", r#"{"n":1e131072}"#] {
608            let error = typed_json_value(&parse_json(text).unwrap(), true).unwrap_err();
609            assert_eq!(error.sqlstate(), Some("22003"));
610        }
611
612        assert!(typed_json_value(&parse_json("1e200000").unwrap(), false).is_ok());
613        assert!(typed_json_value(&parse_json("0e200000").unwrap(), true).is_ok());
614    }
615}