Skip to main content

uqa_sql/expr/
datums.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Read retained physical scalar bytes only when a SQL operation observes the value. Type inspection, copying and NULL tests do not invoke this decoder.
8
9use crate::SQLError;
10use uqa_core::{
11    memory::{Produced, ProductionControl, ProductionVec},
12    DatumValue, DecimalValue, Value,
13};
14
15mod arrays;
16mod bit_string;
17mod compression;
18pub(crate) mod encoding;
19mod fixed;
20pub(in crate::expr) mod inline;
21mod malformed;
22mod records;
23
24pub use arrays::ArrayShape;
25
26/// Whether catalog-free constant evaluation could reach an admitted physical value.
27pub fn contains_datum(value: &Value) -> bool {
28    super::observations::any_nested_value(value, &mut |value| matches!(value, Value::Datum(_)))
29}
30
31/// Read only the actual tuple type of a value already selected as a composite by SQL analysis.
32pub(in crate::expr) fn record_type_oid(
33    datum: &DatumValue,
34    control: &ProductionControl<'_>,
35) -> Result<u32, SQLError> {
36    let payload = payload(datum, control)?;
37    word(payload.bytes().get(4..).unwrap_or_default())
38        .ok_or_else(|| corrupt("invalid record header"))
39}
40
41/// Shape functions inspect only the detoasted array header, without resolving or observing its elements.
42pub fn array_shape(
43    datum: &DatumValue,
44    control: &ProductionControl<'_>,
45) -> Result<ArrayShape, SQLError> {
46    control.check()?;
47    let payload = payload(datum, control)?;
48    arrays::ArrayShape::read(payload.bytes())
49}
50
51/// A polymorphic array operation selects the physical array header even when its declared input is an atomic catalog vector. Vector-specific output and scalar comparison checks belong to those operations, not this array observation.
52pub(in crate::expr) fn read_array_input_with_catalog_and_control(
53    datum: &DatumValue,
54    catalog: Option<&dyn super::SQLValueCatalog>,
55    control: &ProductionControl<'_>,
56) -> Result<Produced<Value>, SQLError> {
57    control.check()?;
58    let payload = payload(datum, control)?;
59    arrays::read(payload.bytes(), catalog, control)
60}
61
62#[cfg(test)]
63mod tests;
64
65pub fn type_name(datum: &DatumValue) -> &'static str {
66    match datum.type_oid() {
67        18 => "\"char\"",
68        19 => "name",
69        700 => "real",
70        1042 => "character",
71        1043 => "character varying",
72        oid => crate::catalog::type_metadata::catalog_type_name(i64::from(oid)),
73    }
74}
75
76pub fn read(datum: &DatumValue) -> Result<Value, SQLError> {
77    read_with_catalog(datum, None)
78}
79
80/// Read an admitted physical value through the current statement's catalog, without invoking type input or domain checks.
81pub fn read_with_catalog(
82    datum: &DatumValue,
83    engine: Option<&dyn super::EngineHook>,
84) -> Result<Value, SQLError> {
85    read_with_catalog_and_control(datum, engine, &ProductionControl::uncontrolled())
86        .map(|value| value.into_uncontrolled().expect("ordinary datum read"))
87}
88
89/// Copy a selected constant field at planning time, detoasting variable-width storage without interpreting its scalar contents. Whole records remain deferred.
90pub fn copy_constant_field(value: &Value, ty: &crate::ColumnType) -> Result<Value, SQLError> {
91    let Value::Datum(datum) = value else {
92        return Ok(value.clone());
93    };
94    if crate::catalog::type_metadata::pg_type_len(ty) != -1 {
95        return Ok(value.clone());
96    }
97    let control = ProductionControl::uncontrolled();
98    let payload = payload(datum, &control)?;
99    let size = payload
100        .bytes()
101        .len()
102        .checked_add(4)
103        .and_then(|size| u32::try_from(size).ok())
104        .and_then(|size| size.checked_mul(4))
105        .ok_or_else(|| corrupt("invalid datum length"))?;
106    let mut bytes = size.to_le_bytes().to_vec();
107    bytes.extend_from_slice(payload.bytes());
108    Ok(Value::Datum(DatumValue::new(datum.type_oid(), 0, bytes)))
109}
110
111pub fn read_with_control(
112    datum: &DatumValue,
113    control: &ProductionControl<'_>,
114) -> Result<Produced<Value>, SQLError> {
115    read_with_catalog_and_control(datum, None, control)
116}
117
118/// Select one field of a resolved composite. Unreached fields remain unread, including their variable-width headers; binding and planning need only the tuple descriptor catalog.
119pub fn read_composite_field_with_control(
120    datum: &DatumValue,
121    field: &str,
122    catalog: Option<&dyn super::composites::CompositeTypeCatalog>,
123    control: &ProductionControl<'_>,
124) -> Result<Produced<Value>, SQLError> {
125    let payload = payload(datum, control)?;
126    records::read_with_lookup(payload.bytes(), Some(field), control, |oid| {
127        super::composites::descriptor(catalog, oid).map(Some)
128    })
129}
130
131pub(in crate::expr) fn read_composite_field_in_descriptor(
132    datum: &DatumValue,
133    field: &str,
134    descriptor: &std::sync::Arc<super::composites::CompositeTypeDescriptor>,
135    control: &ProductionControl<'_>,
136) -> Result<Produced<Value>, SQLError> {
137    let payload = payload(datum, control)?;
138    records::read_with_lookup(payload.bytes(), Some(field), control, |_| {
139        Ok(Some(descriptor.clone()))
140    })
141}
142
143pub(super) fn range_comparison(
144    datum: &DatumValue,
145    ty: &crate::ColumnType,
146    catalog: Option<&dyn super::SQLValueCatalog>,
147    control: &ProductionControl<'_>,
148) -> Result<super::range::RangeComparisonValue, SQLError> {
149    let payload = payload(datum, control)?;
150    super::range::datum::comparison(payload.bytes(), ty, catalog, control)
151}
152
153/// A selected range output function uses its declared class even after the physical type has been dropped from the catalog.
154pub(crate) fn read_range_with_type(
155    datum: &DatumValue,
156    ty: &crate::ColumnType,
157    catalog: Option<&dyn super::SQLValueCatalog>,
158    control: &ProductionControl<'_>,
159) -> Result<Produced<Value>, SQLError> {
160    let payload = payload(datum, control)?;
161    super::range::datum::read(payload.bytes(), ty, catalog, control)
162}
163
164/// Preserve the caller's output allowance and cancellation boundary during catalog-dependent physical reads.
165pub fn read_with_catalog_and_control(
166    datum: &DatumValue,
167    engine: Option<&dyn super::EngineHook>,
168    control: &ProductionControl<'_>,
169) -> Result<Produced<Value>, SQLError> {
170    let catalog = engine.map(super::value_catalog::EngineValueCatalog);
171    read_with_value_catalog_and_control(
172        datum,
173        catalog
174            .as_ref()
175            .map(|catalog| catalog as &dyn super::SQLValueCatalog),
176        control,
177    )
178}
179
180/// Decode a reached value through the same borrowed catalog used by SQL comparison, hashing and output.
181pub fn read_with_value_catalog_and_control(
182    datum: &DatumValue,
183    catalog: Option<&dyn super::SQLValueCatalog>,
184    control: &ProductionControl<'_>,
185) -> Result<Produced<Value>, SQLError> {
186    control.check()?;
187    if let Some(value) = fixed::read(datum, control) {
188        return value;
189    }
190    if crate::catalog::type_metadata::builtin_scalar_type(datum.type_oid()).is_none()
191        && crate::catalog::type_metadata::builtin_array_element(datum.type_oid()).is_none()
192    {
193        if let Some(enums) = catalog {
194            if enums.enum_type_labels(datum.type_oid())?.is_some() {
195                let oid = enum_label_oid(datum)?;
196                return Ok(
197                    control.retain_external_value(super::enums::enum_value_from_oid(
198                        Some(enums),
199                        oid,
200                    )?)?,
201                );
202            }
203        }
204    }
205    let payload = payload(datum, control)?;
206    read_payload(datum.type_oid(), payload.bytes(), catalog, control)
207}
208
209/// Inspect a named row's live field NULL flags without reading its field payloads. Non-composite datums retain scalar NULL semantics and are not decoded.
210pub fn record_null_test_with_control(
211    datum: &DatumValue,
212    negated: bool,
213    catalog: Option<&dyn super::SQLValueCatalog>,
214    control: &ProductionControl<'_>,
215) -> Result<Option<bool>, SQLError> {
216    control.check()?;
217    let Some(catalog) = catalog else {
218        return Ok(None);
219    };
220    let Some(descriptor) = catalog.value_composite_type(datum.type_oid())? else {
221        return Ok(None);
222    };
223    let payload = payload(datum, control)?;
224    records::null_test(payload.bytes(), descriptor, catalog, negated, control).map(Some)
225}
226
227/// Read the fixed-width OID after the caller has selected an enum operation.
228/// Label existence belongs to the particular consuming operation, not this read.
229pub(crate) fn enum_label_oid(datum: &DatumValue) -> Result<u32, SQLError> {
230    word(
231        datum
232            .bytes()
233            .get(datum.offset() as usize..)
234            .unwrap_or_default(),
235    )
236    .ok_or_else(|| corrupt("invalid datum length"))
237}
238
239pub(super) fn compare_jsonb_with_control(
240    left: &Value,
241    right: &Value,
242    control: &ProductionControl<'_>,
243) -> Result<Option<std::cmp::Ordering>, SQLError> {
244    let physical = |value: &Value| matches!(value, Value::Datum(datum) if datum.type_oid() == 3802);
245    let jsonb = |value: &Value| physical(value) || matches!(value, Value::JsonB(_));
246    if !(jsonb(left) && jsonb(right) && (physical(left) || physical(right))) {
247        return Ok(None);
248    }
249    let left_bytes = match left {
250        Value::Datum(datum) => Some(payload(datum, control)?),
251        _ => None,
252    };
253    let right_bytes = match right {
254        Value::Datum(datum) => Some(payload(datum, control)?),
255        _ => None,
256    };
257    let left = match left {
258        Value::JsonB(text) => super::json::JsonbInput::Text(text),
259        _ => super::json::JsonbInput::Bytes(left_bytes.as_ref().expect("physical JSONB").bytes()),
260    };
261    let right = match right {
262        Value::JsonB(text) => super::json::JsonbInput::Text(text),
263        _ => super::json::JsonbInput::Bytes(right_bytes.as_ref().expect("physical JSONB").bytes()),
264    };
265    super::json::compare_jsonb_datums_with_control(left, right, control).map(Some)
266}
267
268fn read_payload(
269    oid: u32,
270    bytes: &[u8],
271    catalog: Option<&dyn super::SQLValueCatalog>,
272    control: &ProductionControl<'_>,
273) -> Result<Produced<Value>, SQLError> {
274    if crate::catalog::type_metadata::builtin_array_element(oid).is_some() {
275        return arrays::read(bytes, catalog, control);
276    }
277    if let Some(ty @ (crate::ColumnType::Range(_) | crate::ColumnType::Multirange(_))) =
278        crate::catalog::type_metadata::builtin_scalar_type(oid)
279    {
280        return super::range::datum::read(bytes, ty, catalog, control);
281    }
282    if crate::catalog::type_metadata::builtin_scalar_type(oid).is_none() {
283        if let Some(descriptor) = catalog
284            .map(|catalog| catalog.value_range_type(oid))
285            .transpose()?
286            .flatten()
287        {
288            if oid != descriptor.range_oid && oid != descriptor.multirange_oid {
289                return Err(corrupt("inconsistent range type descriptor"));
290            }
291            return super::range::datum::read_class(
292                bytes,
293                oid == descriptor.multirange_oid,
294                catalog,
295                control,
296            );
297        }
298        if let Some(ty) = catalog
299            .map(|catalog| catalog.value_type_by_oid(oid))
300            .transpose()?
301            .flatten()
302        {
303            match ty {
304                crate::ColumnType::DeclaredRange(_) | crate::ColumnType::DeclaredMultirange(_) => {
305                    return super::range::datum::read(bytes, &ty, catalog, control);
306                }
307                crate::ColumnType::Array(_) => return arrays::read(bytes, catalog, control),
308                crate::ColumnType::Composite(_) => return records::read(bytes, catalog, control),
309                crate::ColumnType::Domain { base, .. } => {
310                    return read_payload(
311                        crate::catalog::type_metadata::pg_type_oid(&base) as u32,
312                        bytes,
313                        catalog,
314                        control,
315                    );
316                }
317                _ => {}
318            }
319        }
320    }
321    match oid {
322        22 => arrays::read_legacy_vector(bytes, uqa_core::LegacyVectorKind::SmallInteger, control),
323        30 => arrays::read_legacy_vector(bytes, uqa_core::LegacyVectorKind::Oid, control),
324        17 => {
325            let mut output = ProductionVec::new(*control);
326            output.reserve(bytes.len())?;
327            for byte in bytes {
328                output.push_copy(*byte)?;
329            }
330            let (bytes, memory) = output.finish()?.into_parts();
331            Ok(control.finish(Value::Bytes(bytes), memory)?)
332        }
333        25 | 114 | 142 | 194 | 1042 | 1043 | 1790 => {
334            let text = std::str::from_utf8(bytes).map_err(|error| SQLError::Routine {
335                sqlstate: "22021".into(),
336                message: format!(
337                    "invalid byte sequence for encoding \"UTF8\": 0x{:02x}",
338                    bytes[error.valid_up_to()]
339                ),
340            })?;
341            let (text, memory) = control.copy_text(text)?.into_parts();
342            let value = match oid {
343                114 => Value::Json(text),
344                1042 => Value::FixedChar(text),
345                _ => Value::Str(text),
346            };
347            Ok(control.finish(value, memory)?)
348        }
349        1560 | 1562 => bit_string::read(bytes, control),
350        3802 => {
351            let (text, memory) =
352                super::json::decode_jsonb_datum_with_control(bytes, control)?.into_parts();
353            Ok(control.finish(Value::JsonB(text), memory)?)
354        }
355        1700 => {
356            let text =
357                crate::catalog::node_tree::decode_numeric_datum_with_control(bytes, control)?;
358            let (number, memory) = DecimalValue::parse_with_control(&text, control)?
359                .ok_or_else(|| corrupt("invalid numeric datum"))?
360                .into_parts();
361            Ok(control.finish(Value::Decimal(number), memory)?)
362        }
363        oid => Err(SQLError::Unsupported(format!(
364            "physical datum output for type OID {oid}"
365        ))),
366    }
367}
368
369/// Borrow ordinary and inline physical bytea payloads; compressed input retains its admitted decompression buffer through consumption.
370pub(super) fn binary_payload<'a>(
371    value: &'a Value,
372    control: &ProductionControl<'_>,
373) -> Result<Option<Payload<'a>>, SQLError> {
374    control.check()?;
375    match value {
376        Value::Bytes(bytes) => Ok(Some(Payload::Borrowed(bytes))),
377        Value::Datum(datum) if datum.type_oid() == 17 => payload(datum, control).map(Some),
378        _ => Ok(None),
379    }
380}
381
382/// Binary length observes the raw-size header and does not decompress the payload.
383pub(super) fn binary_length(
384    value: &Value,
385    control: &ProductionControl<'_>,
386) -> Result<Option<i64>, SQLError> {
387    control.check()?;
388    let datum = match value {
389        Value::Bytes(bytes) => return Ok(Some(bytes.len() as i64)),
390        Value::Datum(datum) if datum.type_oid() == 17 => datum,
391        _ => return Ok(None),
392    };
393    let bytes = datum
394        .bytes()
395        .get(datum.offset() as usize..)
396        .ok_or_else(|| corrupt("invalid datum length"))?;
397    let first = *bytes
398        .first()
399        .ok_or_else(|| corrupt("invalid datum length"))?;
400    let size = if first == 1 && bytes.get(1) == Some(&18) {
401        i64::from(
402            word(bytes.get(2..).unwrap_or_default())
403                .ok_or_else(|| corrupt("invalid datum length"))?,
404        ) - 4
405    } else if first & 1 != 0 {
406        i64::from(first >> 1) - 1
407    } else if first & 3 == 2 {
408        i64::from(
409            word(bytes.get(4..).unwrap_or_default())
410                .ok_or_else(|| corrupt("invalid datum length"))?
411                & 0x3fff_ffff,
412        )
413    } else {
414        i64::from(word(bytes).ok_or_else(|| corrupt("invalid datum length"))? >> 2) - 4
415    };
416    Ok(Some(size))
417}
418
419pub(super) enum Payload<'a> {
420    Borrowed(&'a [u8]),
421    Owned(Produced<Vec<u8>>),
422}
423
424impl Payload<'_> {
425    pub(super) fn bytes(&self) -> &[u8] {
426        match self {
427            Self::Borrowed(bytes) => bytes,
428            Self::Owned(bytes) => bytes,
429        }
430    }
431}
432
433fn payload<'a>(
434    datum: &'a DatumValue,
435    control: &ProductionControl<'_>,
436) -> Result<Payload<'a>, SQLError> {
437    let offset = datum.offset() as usize;
438    let bytes = datum
439        .bytes()
440        .get(offset..)
441        .ok_or_else(|| corrupt("invalid datum length"))?;
442    let first = *bytes
443        .first()
444        .ok_or_else(|| corrupt("invalid datum length"))?;
445    if first == 1 {
446        return Err(malformed::external(datum));
447    }
448    if first & 1 != 0 {
449        let length = usize::from(first >> 1);
450        return bytes
451            .get(1..length)
452            .map(Payload::Borrowed)
453            .ok_or_else(|| corrupt("invalid datum length"));
454    }
455    let header = word(bytes).ok_or_else(|| corrupt("invalid datum length"))?;
456    let length = (header >> 2) as usize;
457    if header & 3 == 2 {
458        let information = word(bytes.get(4..).unwrap_or_default()).unwrap_or(0);
459        let method = information >> 30;
460        let compressed = bytes
461            .get(8..length)
462            .ok_or_else(|| compression::corrupt(method))?;
463        return compression::decompress(
464            compressed,
465            (information & 0x3fff_ffff) as usize,
466            method,
467            control,
468        )
469        .map(Payload::Owned);
470    }
471    bytes
472        .get(4..length)
473        .map(Payload::Borrowed)
474        .ok_or_else(|| corrupt("invalid datum length"))
475}
476
477fn word(bytes: &[u8]) -> Option<u32> {
478    Some(u32::from_le_bytes(bytes.get(..4)?.try_into().ok()?))
479}
480
481fn corrupt(message: &str) -> SQLError {
482    SQLError::Routine {
483        sqlstate: "XX001".into(),
484        message: message.into(),
485    }
486}