Skip to main content

uqa_sql/catalog/node_tree/
values.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Typed scalar Datums in `PostgreSQL` catalog expression nodes.
8
9pub(super) mod numeric;
10pub(super) mod temporal;
11
12use super::{invalid, Field, Node};
13use crate::catalog::type_metadata::{
14    pg_type_by_value, pg_type_collation_oid, pg_type_len, pg_type_modifier, pg_type_oid,
15};
16use crate::expr::composites::{
17    retained::{capture_type, Descriptors},
18    CompositeConstantSource, CompositeTypeCatalog,
19};
20use crate::{ColumnType, SQLError};
21use uqa_core::Value;
22
23/// Unresolved ROW fields retain `PostgreSQL`'s unknown/cstring Datum until a consumer selects a type.
24pub(super) fn unknown_constant(value: &Value) -> Result<Node, SQLError> {
25    let bytes = match value {
26        Value::Null => Field::Null,
27        Value::Str(text) => {
28            let mut bytes = text.as_bytes().to_vec();
29            bytes.push(0);
30            Field::Datum {
31                length: bytes.len(),
32                bytes,
33            }
34        }
35        _ => return Err(invalid("unknown constant is not a string or NULL")),
36    };
37    Ok(Node::new(
38        "CONST",
39        [
40            ("consttype", 705.into()),
41            ("consttypmod", (-1).into()),
42            ("constcollid", 0.into()),
43            ("constlen", (-2).into()),
44            ("constbyval", false.into()),
45            ("constisnull", matches!(value, Value::Null).into()),
46            ("location", (-1).into()),
47            ("constvalue", bytes),
48        ],
49    ))
50}
51
52pub(super) fn unknown_text(node: &Node) -> Result<&str, SQLError> {
53    let Field::Datum { length, bytes } = node.field("constvalue")? else {
54        return Err(invalid("unknown constant has no Datum"));
55    };
56    if node.integer("constlen")? != -2
57        || node.boolean("constbyval")?
58        || *length != bytes.len()
59        || bytes.last() != Some(&0)
60        || bytes[..bytes.len() - 1].contains(&0)
61    {
62        return Err(invalid("invalid unknown constant Datum"));
63    }
64    std::str::from_utf8(&bytes[..bytes.len() - 1])
65        .map_err(|_| invalid("invalid UTF-8 in unknown Datum"))
66}
67
68pub(super) fn constant(value: &Value, ty: &ColumnType) -> Result<Node, SQLError> {
69    constant_with_source(value, ty, None, None)
70}
71
72/// Encode an already admitted typed constant, preserving any retained physical source and its catalog descriptors.
73pub fn constant_with_source(
74    value: &Value,
75    ty: &ColumnType,
76    source: Option<&CompositeConstantSource>,
77    catalog: Option<&dyn CompositeTypeCatalog>,
78) -> Result<Node, SQLError> {
79    let value = source.map_or(value, |source| &source.value);
80    let bytes = if matches!(value, Value::Null) {
81        Field::Null
82    } else {
83        let descriptors = if let Some(source) = source {
84            source
85                .descriptors
86                .iter()
87                .map(|descriptor| (descriptor.type_oid, std::sync::Arc::new(descriptor.clone())))
88                .collect()
89        } else if matches!(value, Value::Datum(_)) {
90            Descriptors::new()
91        } else {
92            let mut descriptors = Descriptors::new();
93            capture_type(ty, catalog, &mut descriptors)?;
94            descriptors
95        };
96        datum(value, ty, &descriptors)?
97    };
98    Ok(Node::new(
99        "CONST",
100        [
101            ("consttype", pg_type_oid(ty).into()),
102            ("consttypmod", pg_type_modifier(ty).into()),
103            ("constcollid", pg_type_collation_oid(ty).into()),
104            ("constlen", pg_type_len(ty).into()),
105            ("constbyval", pg_type_by_value(ty).into()),
106            ("constisnull", matches!(value, Value::Null).into()),
107            ("location", (-1).into()),
108            ("constvalue", bytes),
109        ],
110    ))
111}
112
113fn datum(value: &Value, ty: &ColumnType, descriptors: &Descriptors) -> Result<Field, SQLError> {
114    let mut representation = ty;
115    while let ColumnType::Domain { base, .. } = representation {
116        representation = base;
117    }
118    let mut bytes = match (value, representation) {
119        (Value::Bool(value), ColumnType::Boolean) => vec![u8::from(*value)],
120        (
121            Value::Int(value),
122            ColumnType::SmallInteger
123            | ColumnType::Integer
124            | ColumnType::BigInteger
125            | ColumnType::Oid
126            | ColumnType::Xid
127            | ColumnType::Regclass
128            | ColumnType::Regtype
129            | ColumnType::Regcollation
130            | ColumnType::Regnamespace
131            | ColumnType::Regrole
132            | ColumnType::Regproc
133            | ColumnType::Regprocedure,
134        ) => value.to_le_bytes().to_vec(),
135        (Value::Float(value), ColumnType::Real) => (*value as f32).to_le_bytes().to_vec(),
136        (Value::Float(value), ColumnType::DoublePrecision) => value.to_le_bytes().to_vec(),
137        (Value::Enum(value), ColumnType::Enum(_)) => value
138            .label_oid()
139            .ok_or_else(|| invalid("enum constant has no retained label identity"))?
140            .to_le_bytes()
141            .to_vec(),
142        (Value::Str(_), ColumnType::InternalChar) => {
143            vec![crate::expr::internal_char::value_byte(value)
144                .ok_or_else(|| SQLError::Internal("invalid internal char carrier".into()))?]
145        }
146        (Value::Str(value) | Value::FixedChar(value), ColumnType::Name) => {
147            let mut bytes = value.as_bytes().to_vec();
148            if bytes.len() >= 64 {
149                return Err(SQLError::Internal("unclipped name Datum".into()));
150            }
151            bytes.resize(64, 0);
152            bytes
153        }
154        (
155            Value::Str(value) | Value::FixedChar(value),
156            ColumnType::Text
157            | ColumnType::Varchar(_)
158            | ColumnType::Bpchar
159            | ColumnType::Character(_)
160            | ColumnType::RefCursor,
161        ) => varlena(value.as_bytes())?,
162        (Value::Bytes(value), ColumnType::Bytea) => varlena(value)?,
163        (Value::Str(text), ColumnType::Range(_) | ColumnType::Multirange(_)) => {
164            varlena(&crate::expr::range_datum::encode(text, representation)?)?
165        }
166        (Value::Str(value), ColumnType::Uuid) => crate::expr::parse_uuid_bytes(value)?.to_vec(),
167        (Value::Json(value), ColumnType::Json) => varlena(value.as_bytes())?,
168        (Value::JsonB(value), ColumnType::JsonB) => {
169            varlena(&crate::expr::encode_jsonb_datum(value)?)?
170        }
171        (Value::Array(array), ColumnType::Array(element)) => {
172            let payload =
173                crate::expr::composites::retained::array_payload(array, element, descriptors)
174                    .ok_or_else(|| {
175                        SQLError::Unsupported(format!(
176                            "catalog array Datum encoding for {}",
177                            ty.sql_name()
178                        ))
179                    })?;
180            varlena(&payload)?
181        }
182        (Value::Record(fields), ColumnType::Composite(reference)) => {
183            crate::expr::composites::retained::record_bytes(fields, reference.oid, descriptors)
184                .ok_or_else(|| invalid("composite constant has no retained tuple layout"))?
185        }
186        (
187            Value::Datum(_),
188            ColumnType::Array(_)
189            | ColumnType::Composite(_)
190            | ColumnType::Range(_)
191            | ColumnType::Multirange(_)
192            | ColumnType::DeclaredRange(_)
193            | ColumnType::DeclaredMultirange(_),
194        ) => retained_constant_bytes(value, ty)?,
195        (Value::Decimal(value), ColumnType::Numeric { .. }) => varlena(&numeric::encode(value)?)?,
196        (Value::Temporal(value), _) => temporal::encode(value, pg_type_oid(representation))?,
197        _ => {
198            return Err(SQLError::Unsupported(format!(
199                "catalog Datum encoding for {}",
200                ty.sql_name()
201            )))
202        }
203    };
204    let length = if pg_type_by_value(ty) {
205        bytes.resize(8, 0);
206        usize::try_from(pg_type_len(ty))
207            .map_err(|_| SQLError::Internal("invalid by-value Datum length".into()))?
208    } else {
209        bytes.len()
210    };
211    Ok(Field::Datum { length, bytes })
212}
213
214fn retained_constant_bytes(value: &Value, ty: &ColumnType) -> Result<Vec<u8>, SQLError> {
215    let Value::Datum(owned) = crate::expr::datums::copy_constant_field(value, ty)? else {
216        return Err(SQLError::Internal(
217            "physical catalog constant changed carrier".into(),
218        ));
219    };
220    Ok(owned.bytes().to_vec())
221}
222
223pub(super) fn scalar_text(node: &Node) -> Result<String, SQLError> {
224    let oid = u32::try_from(node.integer("consttype")?)
225        .map_err(|_| invalid("invalid scalar constant type"))?;
226    let ty = crate::catalog::type_metadata::builtin_scalar_type(oid)
227        .ok_or_else(|| invalid("unknown scalar constant type"))?;
228    if node.boolean("constbyval")? || node.integer("constlen")? != pg_type_len(ty) {
229        return Err(invalid("invalid scalar constant layout"));
230    }
231    let Field::Datum { length, bytes } = node.field("constvalue")? else {
232        return Err(invalid("constant has no Datum"));
233    };
234    if *ty == ColumnType::Uuid {
235        if *length != 16 {
236            return Err(invalid("invalid UUID Datum length"));
237        }
238        let bytes = bytes
239            .as_slice()
240            .try_into()
241            .map_err(|_| invalid("invalid UUID Datum length"))?;
242        return Ok(crate::expr::format_uuid(bytes));
243    }
244    let payload = varlena_payload(*length, bytes)?;
245    let control = uqa_core::memory::ProductionControl::uncontrolled();
246    match ty {
247        ColumnType::Bytea => crate::expr::bytea_to_string_with_control(payload, &control)
248            .map(|text| text.into_uncontrolled().expect("ordinary bytea text")),
249        ColumnType::Json => std::str::from_utf8(payload)
250            .map(str::to_owned)
251            .map_err(|_| invalid("invalid JSON Datum encoding")),
252        ColumnType::JsonB => crate::expr::decode_jsonb_datum_with_control(payload, &control)
253            .map(|text| text.into_uncontrolled().expect("ordinary JSONB text")),
254        _ => Err(invalid("unsupported scalar constant type")),
255    }
256}
257
258pub(super) fn varlena_payload(length: usize, bytes: &[u8]) -> Result<&[u8], SQLError> {
259    let header = bytes
260        .get(..4)
261        .and_then(|bytes| bytes.try_into().ok())
262        .map(u32::from_le_bytes)
263        .ok_or_else(|| invalid("truncated varlena Datum"))?;
264    if bytes.len() != length || header & 3 != 0 || usize::try_from(header >> 2).ok() != Some(length)
265    {
266        return Err(invalid("invalid varlena Datum length"));
267    }
268    Ok(&bytes[4..])
269}
270
271pub(super) fn catalog_text(
272    node: &Node,
273    catalog: Option<&dyn crate::expr::SQLValueCatalog>,
274) -> Result<Option<String>, SQLError> {
275    let oid = u32::try_from(node.integer("consttype")?)
276        .map_err(|_| invalid("invalid catalog constant type"))?;
277    let ty = if let Some(element) = crate::catalog::type_metadata::builtin_array_element(oid) {
278        ColumnType::Array(Box::new(element.clone()))
279    } else if let Some(ty @ (ColumnType::Range(_) | ColumnType::Multirange(_))) =
280        crate::catalog::type_metadata::builtin_scalar_type(oid)
281    {
282        ty.clone()
283    } else if let Some(ty) = catalog
284        .map(|catalog| catalog.value_type_by_oid(oid))
285        .transpose()?
286        .flatten()
287    {
288        ty
289    } else {
290        return Ok(None);
291    };
292    if node.boolean("constbyval")? != pg_type_by_value(&ty)
293        || node.integer("constlen")? != pg_type_len(&ty)
294    {
295        return Err(invalid("invalid catalog constant layout"));
296    }
297    let Field::Datum { length, bytes } = node.field("constvalue")? else {
298        return Err(invalid("constant has no Datum"));
299    };
300    if pg_type_len(&ty) == -1 {
301        varlena_payload(*length, bytes)?;
302    } else if i64::try_from(*length).ok() != Some(pg_type_len(&ty))
303        || (!pg_type_by_value(&ty) && bytes.len() != *length)
304    {
305        return Err(invalid("invalid catalog constant length"));
306    }
307    let value = Value::Datum(uqa_core::DatumValue::new(oid, 0, bytes.clone()));
308    crate::result::format_postgres_text_with_catalog(&value, &ty, catalog).map(Some)
309}
310
311fn varlena(payload: &[u8]) -> Result<Vec<u8>, SQLError> {
312    let length = payload
313        .len()
314        .checked_add(4)
315        .and_then(|length| u32::try_from(length).ok())
316        .filter(|length| *length <= u32::MAX >> 2)
317        .ok_or_else(|| SQLError::Routine {
318            sqlstate: "54000".into(),
319            message: "catalog Datum is too large".into(),
320        })?;
321    Ok((length << 2)
322        .to_le_bytes()
323        .into_iter()
324        .chain(payload.iter().copied())
325        .collect())
326}