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
32pub(super) fn parse_json(s: &str) -> Result<serde_json::Value> {
33    serde_json::from_str::<serde_json::Value>(s)
34        .map_err(|_| super::json_strip::invalid_json_input(s))
35}
36
37/// Render a parsed JSON value in `PostgreSQL`'s compact result format. JSONB
38/// objects use `PostgreSQL`'s length-then-bytewise key ordering.
39pub(super) fn format_json(value: &serde_json::Value, jsonb: bool) -> String {
40    if !jsonb {
41        return serde_json::to_string(value).expect("serializing a JSON value cannot fail");
42    }
43    match value {
44        serde_json::Value::Null => "null".to_string(),
45        serde_json::Value::Bool(value) => value.to_string(),
46        serde_json::Value::Number(value) => {
47            let text = value.to_string();
48            DecimalValue::parse(&text).map_or(text, |value| value.to_sql_string())
49        }
50        serde_json::Value::String(value) => serde_json::Value::String(value.clone()).to_string(),
51        serde_json::Value::Array(values) => {
52            let values = values
53                .iter()
54                .map(|value| format_json(value, true))
55                .collect::<Vec<_>>();
56            format!("[{}]", values.join(", "))
57        }
58        serde_json::Value::Object(values) => {
59            let mut values = values.iter().collect::<Vec<_>>();
60            values.sort_by(|(left, _), (right, _)| {
61                left.len()
62                    .cmp(&right.len())
63                    .then_with(|| left.as_bytes().cmp(right.as_bytes()))
64            });
65            let values = values
66                .into_iter()
67                .map(|(key, value)| {
68                    let key = serde_json::Value::String(key.clone()).to_string();
69                    format!("{key}: {}", format_json(value, true))
70                })
71                .collect::<Vec<_>>();
72            format!("{{{}}}", values.join(", "))
73        }
74    }
75}
76
77#[cfg(test)]
78fn format_jsonb_pretty(value: &serde_json::Value) -> String {
79    let Value::Str(text) =
80        ordinary("jsonb_pretty", &[Value::Json(value.to_string())]).expect("valid parsed JSON")
81    else {
82        unreachable!("JSON pretty text")
83    };
84    text
85}
86
87pub(super) fn typed_json_value(value: &serde_json::Value, jsonb: bool) -> Result<Value> {
88    if jsonb {
89        validate_jsonb_numbers(value)?;
90    }
91    let text = format_json(value, jsonb);
92    if jsonb {
93        Ok(Value::JsonB(text))
94    } else {
95        Ok(Value::Json(text))
96    }
97}
98
99fn validate_jsonb_numbers(value: &serde_json::Value) -> Result<()> {
100    match value {
101        serde_json::Value::Number(value) => DecimalValue::parse(&value.to_string())
102            .map(|_| ())
103            .ok_or_else(|| out_of_range("numeric")),
104        serde_json::Value::Array(values) => values.iter().try_for_each(validate_jsonb_numbers),
105        serde_json::Value::Object(values) => values.values().try_for_each(validate_jsonb_numbers),
106        _ => Ok(()),
107    }
108}
109
110/// Render an engine value as `PostgreSQL` JSON input text without losing the
111/// lexical representation of values already typed as `json` or `jsonb`.
112pub fn value_to_json_text(value: &Value) -> Result<String> {
113    Ok(match value {
114        Value::Null => "null".to_string(),
115        Value::Void => "\"\"".to_string(),
116        Value::Bool(value) => value.to_string(),
117        Value::Int(value) => value.to_string(),
118        Value::Float(value) => match serde_json::Number::from_f64(*value) {
119            Some(number) => number.to_string(),
120            None if value.is_nan() => "\"NaN\"".to_string(),
121            None if value.is_sign_positive() => "\"Infinity\"".to_string(),
122            None => "\"-Infinity\"".to_string(),
123        },
124        Value::Decimal(value) => value.to_sql_string(),
125        Value::Str(value) => serde_json::Value::String(value.clone()).to_string(),
126        Value::FixedChar(value) => {
127            serde_json::Value::String(value.trim_end_matches(' ').to_string()).to_string()
128        }
129        Value::Bytes(value) => {
130            serde_json::Value::String(format!("0x{}", hex_encode(value))).to_string()
131        }
132        Value::Temporal(_) | Value::BitString(_) => {
133            serde_json::Value::String(super::value_to_string(value)?).to_string()
134        }
135        Value::Json(text) | Value::JsonB(text) => text.clone(),
136        Value::Enum(value) => return Err(super::catalog_output_required(value)),
137        Value::Datum(value) => return value_to_json_text(&super::datums::read(value)?),
138        Value::LegacyVector(vector) => legacy_vector_json(vector).to_string(),
139        Value::Array(array) => array_json_text(array.elements(), array.element_type_oid())?,
140        Value::List(values) => {
141            let values = values
142                .iter()
143                .map(value_to_json_text)
144                .collect::<Result<Vec<_>>>()?;
145            format!("[{}]", values.join(","))
146        }
147        Value::Row(values) => record_json_text(
148            values
149                .iter()
150                .enumerate()
151                .map(|(index, value)| (format!("f{}", index + 1), value)),
152        )?,
153        Value::Record(fields) => {
154            record_json_text(fields.iter().map(|(name, value)| (name.clone(), value)))?
155        }
156        Value::Map(values) => {
157            let values = values
158                .iter()
159                .map(|(key, value)| {
160                    let key = serde_json::Value::String(key.clone()).to_string();
161                    Ok(format!("{key}:{}", value_to_json_text(value)?))
162                })
163                .collect::<Result<Vec<_>>>()?;
164            format!("{{{}}}", values.join(","))
165        }
166    })
167}
168
169fn array_json_text(values: &[Value], oid: Option<u32>) -> Result<String> {
170    let fields = values
171        .iter()
172        .map(|value| match value {
173            Value::List(values) => array_json_text(values, oid),
174            Value::Float(value) if oid == Some(700) && value.is_finite() => {
175                Ok(super::format_real(*value as f32))
176            }
177            value => value_to_json_text(value),
178        })
179        .collect::<Result<Vec<_>>>()?;
180    Ok(format!("[{}]", fields.join(",")))
181}
182
183fn legacy_vector_json(vector: &uqa_core::LegacyVectorValue) -> serde_json::Value {
184    serde_json::Value::Array(
185        vector
186            .elements()
187            .iter()
188            .map(|value| {
189                let Value::Int(value) = value else {
190                    unreachable!("validated legacy vector element");
191                };
192                match vector.kind() {
193                    uqa_core::LegacyVectorKind::SmallInteger => (*value).into(),
194                    uqa_core::LegacyVectorKind::Oid => value.to_string().into(),
195                }
196            })
197            .collect(),
198    )
199}
200
201fn record_json_text<'a>(fields: impl IntoIterator<Item = (String, &'a Value)>) -> Result<String> {
202    let fields = fields
203        .into_iter()
204        .map(|(name, value)| {
205            let name = serde_json::Value::String(name).to_string();
206            Ok(format!("{name}:{}", value_to_json_text(value)?))
207        })
208        .collect::<Result<Vec<_>>>()?;
209    Ok(format!("{{{}}}", fields.join(",")))
210}
211
212pub(super) fn json_build_array_value(args: &[Value], jsonb: bool) -> Result<Value> {
213    let text = format!(
214        "[{}]",
215        args.iter()
216            .map(value_to_json_text)
217            .collect::<Result<Vec<_>>>()?
218            .join(", ")
219    );
220    if jsonb {
221        typed_json_value(&parse_json(&text)?, true)
222    } else {
223        Ok(Value::Json(text))
224    }
225}
226
227/// 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.
228pub fn validate_json_object_key_type(value: &Value) -> Result<()> {
229    if matches!(
230        value,
231        Value::Array(_)
232            | Value::LegacyVector(_)
233            | Value::List(_)
234            | Value::Row(_)
235            | Value::Record(_)
236            | Value::Map(_)
237            | Value::Json(_)
238            | Value::JsonB(_)
239    ) {
240        return Err(SQLError::Routine {
241            sqlstate: "22023".into(),
242            message: "key value must be scalar, not array, composite, or json".into(),
243        });
244    }
245    Ok(())
246}
247
248pub(super) fn json_build_object_value(args: &[Value], jsonb: bool) -> Result<Value> {
249    let function = if jsonb {
250        "jsonb_build_object()"
251    } else {
252        "json_build_object()"
253    };
254    if !args.len().is_multiple_of(2) {
255        return Err(SQLError::Diagnostic {
256            sqlstate: "22023".into(),
257            message: "argument list must have even number of elements".into(),
258            detail: None,
259            hint: Some(format!(
260                "The arguments of {function} must consist of alternating keys and values."
261            )),
262        });
263    }
264    let mut fields = Vec::with_capacity(args.len() / 2);
265    for (index, pair) in args.as_chunks::<2>().0.iter().enumerate() {
266        if matches!(pair[0], Value::Null) {
267            return Err(if jsonb {
268                SQLError::Routine {
269                    sqlstate: "22023".into(),
270                    message: format!("argument {}: key must not be null", index * 2 + 1),
271                }
272            } else {
273                SQLError::Routine {
274                    sqlstate: "22004".into(),
275                    message: "null value not allowed for object key".into(),
276                }
277            });
278        }
279        validate_json_object_key_type(&pair[0])?;
280        let key = serde_json::Value::String(super::value_to_string(&pair[0])?).to_string();
281        fields.push(format!("{key} : {}", value_to_json_text(&pair[1])?));
282    }
283    let text = format!("{{{}}}", fields.join(", "));
284    if jsonb {
285        typed_json_value(&parse_json(&text)?, true)
286    } else {
287        Ok(Value::Json(text))
288    }
289}
290
291#[cfg(test)]
292pub(super) fn value_to_json(v: &Value) -> serde_json::Value {
293    match v {
294        Value::Datum(datum) => {
295            value_to_json(&super::datums::read(datum).expect("test datum output"))
296        }
297        Value::Null => serde_json::Value::Null,
298        Value::Void => serde_json::Value::String(String::new()),
299        Value::Bool(b) => serde_json::Value::Bool(*b),
300        Value::Int(i) => serde_json::Value::Number((*i).into()),
301        Value::Float(f) => serde_json::Number::from_f64(*f).map_or_else(
302            || {
303                let label = if f.is_nan() {
304                    "NaN"
305                } else if f.is_sign_positive() {
306                    "Infinity"
307                } else {
308                    "-Infinity"
309                };
310                serde_json::Value::String(label.to_string())
311            },
312            serde_json::Value::Number,
313        ),
314        Value::Decimal(d) => {
315            if d.is_nan() || d.is_infinite() {
316                serde_json::Value::String(d.to_sql_string())
317            } else {
318                d.to_sql_string()
319                    .parse::<serde_json::Number>()
320                    .map(serde_json::Value::Number)
321                    .unwrap_or_else(|_| serde_json::Value::String(d.to_sql_string()))
322            }
323        }
324        Value::Str(s) => serde_json::Value::String(s.clone()),
325        Value::FixedChar(s) => serde_json::Value::String(s.trim_end_matches(' ').to_string()),
326        Value::Bytes(b) => serde_json::Value::String(format!("0x{}", hex_encode(b))),
327        Value::BitString(_) => {
328            serde_json::Value::String(super::value_to_string(v).expect("test bit-string output"))
329        }
330        Value::Temporal(t) => serde_json::Value::String(t.to_sql_string()),
331        Value::Json(text) | Value::JsonB(text) => {
332            serde_json::from_str(text).unwrap_or_else(|_| serde_json::Value::String(text.clone()))
333        }
334        Value::LegacyVector(vector) => legacy_vector_json(vector),
335        Value::Array(array) => {
336            serde_json::Value::Array(array.elements().iter().map(value_to_json).collect())
337        }
338        Value::List(items) => serde_json::Value::Array(items.iter().map(value_to_json).collect()),
339        Value::Row(values) => serde_json::Value::Object(
340            values
341                .iter()
342                .enumerate()
343                .map(|(index, value)| (format!("f{}", index + 1), value_to_json(value)))
344                .collect(),
345        ),
346        Value::Record(fields) => serde_json::Value::Object(
347            fields
348                .iter()
349                .map(|(name, value)| (name.clone(), value_to_json(value)))
350                .collect(),
351        ),
352        Value::Map(map) => {
353            let mut obj = serde_json::Map::new();
354            for (k, v) in map {
355                obj.insert(k.clone(), value_to_json(v));
356            }
357            serde_json::Value::Object(obj)
358        }
359        Value::Enum(value) => panic!(
360            "test JSON has no enum label for type OID {}",
361            value.type_oid()
362        ),
363    }
364}
365
366#[allow(dead_code)]
367pub(super) fn json_to_value(json: &serde_json::Value) -> Value {
368    match json {
369        serde_json::Value::Null => Value::Null,
370        serde_json::Value::Bool(b) => Value::Bool(*b),
371        serde_json::Value::Number(n) => {
372            if let Some(i) = n.as_i64() {
373                Value::Int(i)
374            } else if let Some(d) = DecimalValue::parse(&n.to_string()) {
375                Value::Decimal(d)
376            } else if let Some(f) = n.as_f64() {
377                Value::Float(f)
378            } else {
379                Value::Null
380            }
381        }
382        serde_json::Value::String(s) => Value::Str(s.clone()),
383        serde_json::Value::Array(arr) => Value::List(arr.iter().map(json_to_value).collect()),
384        serde_json::Value::Object(obj) => {
385            if let Ok(temporal) =
386                serde_json::from_value::<TemporalValue>(serde_json::Value::Object(obj.clone()))
387            {
388                return Value::Temporal(temporal);
389            }
390            let mut map = std::collections::BTreeMap::new();
391            for (k, v) in obj {
392                map.insert(k.clone(), json_to_value(v));
393            }
394            Value::Map(map)
395        }
396    }
397}
398
399fn ordinary(name: &str, args: &[Value]) -> Result<Value> {
400    Ok(production::evaluate(
401        name,
402        args,
403        &uqa_core::memory::ProductionControl::uncontrolled(),
404    )
405    .expect("known JSON builtin")?
406    .into_uncontrolled()
407    .expect("ordinary JSON has no lease"))
408}
409
410fn json_array_index(len: usize, key: &str) -> Option<usize> {
411    let index = key.parse::<i64>().ok()?;
412    let normalized = if index < 0 { len as i64 + index } else { index };
413    usize::try_from(normalized).ok().filter(|idx| *idx < len)
414}
415
416fn json_insert_index(len: usize, key: &str, insert_after: bool) -> Option<usize> {
417    let raw = key.parse::<i64>().ok()?;
418    let len_i64 = len as i64;
419    let index = if raw >= 0 {
420        if raw >= len_i64 {
421            len_i64
422        } else if insert_after {
423            raw + 1
424        } else {
425            raw
426        }
427    } else {
428        let normalized = len_i64 + raw;
429        if normalized < 0 {
430            0
431        } else if insert_after {
432            normalized + 1
433        } else {
434            normalized
435        }
436    };
437    usize::try_from(index.clamp(0, len_i64)).ok()
438}
439
440#[cfg(test)]
441mod pretty_tests {
442    use super::{format_jsonb_pretty, parse_json, typed_json_value, DecimalValue};
443
444    #[test]
445    fn jsonb_pretty_uses_postgresql_layout_and_key_order() {
446        let value = parse_json(r#"{"zz":1,"b":[],"aa":{"long":3,"x":2}}"#).unwrap();
447        assert_eq!(
448            format_jsonb_pretty(&value),
449            "{\n    \"b\": [\n    ],\n    \"aa\": {\n        \"x\": 2,\n        \"long\": 3\n    },\n    \"zz\": 1\n}"
450        );
451        assert_eq!(format_jsonb_pretty(&parse_json("[]").unwrap()), "[\n]");
452        assert_eq!(format_jsonb_pretty(&parse_json("{}").unwrap()), "{\n}");
453        assert_eq!(
454            format_jsonb_pretty(&parse_json("1e-1000").unwrap()),
455            DecimalValue::parse("1e-1000").unwrap().to_sql_string()
456        );
457        assert_eq!(format_jsonb_pretty(&parse_json("1.00").unwrap()), "1.00");
458        assert_eq!(format_jsonb_pretty(&parse_json("-0").unwrap()), "0");
459    }
460
461    #[test]
462    fn jsonb_rejects_numbers_outside_postgresql_numeric_range() {
463        let maximum = parse_json("1e131071").unwrap();
464        assert!(typed_json_value(&maximum, true).is_ok());
465
466        for text in ["1e131072", "1e-16384", "[1e131072]", r#"{"n":1e131072}"#] {
467            let error = typed_json_value(&parse_json(text).unwrap(), true).unwrap_err();
468            assert_eq!(error.sqlstate(), Some("22003"));
469        }
470
471        assert!(typed_json_value(&parse_json("1e200000").unwrap(), false).is_ok());
472        assert!(typed_json_value(&parse_json("0e200000").unwrap(), true).is_ok());
473    }
474}