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    copy_constant_field_with_control(value, ty, &ProductionControl::uncontrolled()).map(|value| {
92        value
93            .into_uncontrolled()
94            .expect("ordinary constant field copy")
95    })
96}
97
98/// Admit the selected field's detoasting workspace, physical destination and retained backing before allocation. Copying preserves bytes without interpreting scalar contents or reading other fields.
99pub fn copy_constant_field_with_control(
100    value: &Value,
101    ty: &crate::ColumnType,
102    control: &ProductionControl<'_>,
103) -> Result<Produced<Value>, SQLError> {
104    control.check()?;
105    let Value::Datum(datum) = value else {
106        return control.copy_value(value).map_err(Into::into);
107    };
108    if crate::catalog::type_metadata::pg_type_len(ty) != -1 {
109        return control.copy_value(value).map_err(Into::into);
110    }
111    let payload = payload(datum, control)?;
112    let size = payload
113        .bytes()
114        .len()
115        .checked_add(4)
116        .and_then(|size| u32::try_from(size).ok())
117        .and_then(|size| size.checked_mul(4))
118        .ok_or_else(|| corrupt("invalid datum length"))?;
119    let mut bytes = ProductionVec::new(*control);
120    bytes.reserve(payload.bytes().len() + 4)?;
121    bytes.extend_from_slice(&size.to_le_bytes())?;
122    bytes.extend_from_slice(payload.bytes())?;
123    let (datum, memory) =
124        DatumValue::with_control(datum.type_oid(), 0, bytes.finish()?, control)?.into_parts();
125    Ok(control.finish(Value::Datum(datum), memory)?)
126}
127
128pub fn read_with_control(
129    datum: &DatumValue,
130    control: &ProductionControl<'_>,
131) -> Result<Produced<Value>, SQLError> {
132    read_with_catalog_and_control(datum, None, control)
133}
134
135/// 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.
136pub fn read_composite_field_with_control(
137    datum: &DatumValue,
138    field: &str,
139    catalog: Option<&dyn super::composites::CompositeTypeCatalog>,
140    control: &ProductionControl<'_>,
141) -> Result<Produced<Value>, SQLError> {
142    let payload = payload(datum, control)?;
143    records::read_with_lookup(payload.bytes(), Some(field), control, |oid| {
144        super::composites::descriptor(catalog, oid).map(Some)
145    })
146}
147
148pub(in crate::expr) fn read_composite_field_in_descriptor(
149    datum: &DatumValue,
150    field: &str,
151    descriptor: &std::sync::Arc<super::composites::CompositeTypeDescriptor>,
152    control: &ProductionControl<'_>,
153) -> Result<Produced<Value>, SQLError> {
154    let payload = payload(datum, control)?;
155    records::read_with_lookup(payload.bytes(), Some(field), control, |_| {
156        Ok(Some(descriptor.clone()))
157    })
158}
159
160pub(super) fn range_comparison(
161    datum: &DatumValue,
162    ty: &crate::ColumnType,
163    catalog: Option<&dyn super::SQLValueCatalog>,
164    control: &ProductionControl<'_>,
165) -> Result<super::range::RangeComparisonValue, SQLError> {
166    let payload = payload(datum, control)?;
167    super::range::datum::comparison(payload.bytes(), ty, catalog, control)
168}
169
170/// A selected range output function uses its declared class even after the physical type has been dropped from the catalog.
171pub(crate) fn read_range_with_type(
172    datum: &DatumValue,
173    ty: &crate::ColumnType,
174    catalog: Option<&dyn super::SQLValueCatalog>,
175    control: &ProductionControl<'_>,
176) -> Result<Produced<Value>, SQLError> {
177    let payload = payload(datum, control)?;
178    super::range::datum::read(payload.bytes(), ty, catalog, control)
179}
180
181/// Preserve the caller's output allowance and cancellation boundary during catalog-dependent physical reads.
182pub fn read_with_catalog_and_control(
183    datum: &DatumValue,
184    engine: Option<&dyn super::EngineHook>,
185    control: &ProductionControl<'_>,
186) -> Result<Produced<Value>, SQLError> {
187    let catalog = engine.map(super::value_catalog::EngineValueCatalog);
188    read_with_value_catalog_and_control(
189        datum,
190        catalog
191            .as_ref()
192            .map(|catalog| catalog as &dyn super::SQLValueCatalog),
193        control,
194    )
195}
196
197/// Decode a reached value through the same borrowed catalog used by SQL comparison, hashing and output.
198pub fn read_with_value_catalog_and_control(
199    datum: &DatumValue,
200    catalog: Option<&dyn super::SQLValueCatalog>,
201    control: &ProductionControl<'_>,
202) -> Result<Produced<Value>, SQLError> {
203    control.check()?;
204    if let Some(value) = fixed::read(datum, control) {
205        return value;
206    }
207    if crate::catalog::type_metadata::builtin_scalar_type(datum.type_oid()).is_none()
208        && crate::catalog::type_metadata::builtin_array_element(datum.type_oid()).is_none()
209    {
210        if let Some(enums) = catalog {
211            if enums.enum_type_labels(datum.type_oid())?.is_some() {
212                let oid = enum_label_oid(datum)?;
213                return Ok(
214                    control.retain_external_value(super::enums::enum_value_from_oid(
215                        Some(enums),
216                        oid,
217                    )?)?,
218                );
219            }
220        }
221    }
222    let payload = payload(datum, control)?;
223    read_payload(datum.type_oid(), payload.bytes(), catalog, control)
224}
225
226/// 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.
227pub fn record_null_test_with_control(
228    datum: &DatumValue,
229    negated: bool,
230    catalog: Option<&dyn super::SQLValueCatalog>,
231    control: &ProductionControl<'_>,
232) -> Result<Option<bool>, SQLError> {
233    control.check()?;
234    let Some(catalog) = catalog else {
235        return Ok(None);
236    };
237    let Some(descriptor) = catalog.value_composite_type(datum.type_oid())? else {
238        return Ok(None);
239    };
240    let payload = payload(datum, control)?;
241    records::null_test(payload.bytes(), descriptor, catalog, negated, control).map(Some)
242}
243
244/// Read the fixed-width OID after the caller has selected an enum operation.
245/// Label existence belongs to the particular consuming operation, not this read.
246pub(crate) fn enum_label_oid(datum: &DatumValue) -> Result<u32, SQLError> {
247    word(
248        datum
249            .bytes()
250            .get(datum.offset() as usize..)
251            .unwrap_or_default(),
252    )
253    .ok_or_else(|| corrupt("invalid datum length"))
254}
255
256pub(super) fn compare_jsonb_with_control(
257    left: &Value,
258    right: &Value,
259    control: &ProductionControl<'_>,
260) -> Result<Option<std::cmp::Ordering>, SQLError> {
261    let physical = |value: &Value| matches!(value, Value::Datum(datum) if datum.type_oid() == 3802);
262    let jsonb = |value: &Value| physical(value) || matches!(value, Value::JsonB(_));
263    if !(jsonb(left) && jsonb(right) && (physical(left) || physical(right))) {
264        return Ok(None);
265    }
266    let left_bytes = match left {
267        Value::Datum(datum) => Some(payload(datum, control)?),
268        _ => None,
269    };
270    let right_bytes = match right {
271        Value::Datum(datum) => Some(payload(datum, control)?),
272        _ => None,
273    };
274    let left = match left {
275        Value::JsonB(text) => super::json::JsonbInput::Text(text),
276        _ => super::json::JsonbInput::Bytes(left_bytes.as_ref().expect("physical JSONB").bytes()),
277    };
278    let right = match right {
279        Value::JsonB(text) => super::json::JsonbInput::Text(text),
280        _ => super::json::JsonbInput::Bytes(right_bytes.as_ref().expect("physical JSONB").bytes()),
281    };
282    super::json::compare_jsonb_datums_with_control(left, right, control).map(Some)
283}
284
285fn read_payload(
286    oid: u32,
287    bytes: &[u8],
288    catalog: Option<&dyn super::SQLValueCatalog>,
289    control: &ProductionControl<'_>,
290) -> Result<Produced<Value>, SQLError> {
291    if crate::catalog::type_metadata::builtin_array_element(oid).is_some() {
292        return arrays::read(bytes, catalog, control);
293    }
294    if let Some(ty @ (crate::ColumnType::Range(_) | crate::ColumnType::Multirange(_))) =
295        crate::catalog::type_metadata::builtin_scalar_type(oid)
296    {
297        return super::range::datum::read(bytes, ty, catalog, control);
298    }
299    if crate::catalog::type_metadata::builtin_scalar_type(oid).is_none() {
300        if let Some(descriptor) = catalog
301            .map(|catalog| catalog.value_range_type(oid))
302            .transpose()?
303            .flatten()
304        {
305            if oid != descriptor.range_oid && oid != descriptor.multirange_oid {
306                return Err(corrupt("inconsistent range type descriptor"));
307            }
308            return super::range::datum::read_class(
309                bytes,
310                oid == descriptor.multirange_oid,
311                catalog,
312                control,
313            );
314        }
315        if let Some(ty) = catalog
316            .map(|catalog| catalog.value_type_by_oid(oid))
317            .transpose()?
318            .flatten()
319        {
320            match ty {
321                crate::ColumnType::DeclaredRange(_) | crate::ColumnType::DeclaredMultirange(_) => {
322                    return super::range::datum::read(bytes, &ty, catalog, control);
323                }
324                crate::ColumnType::Array(_) => return arrays::read(bytes, catalog, control),
325                crate::ColumnType::Composite(_) => return records::read(bytes, catalog, control),
326                crate::ColumnType::Domain { base, .. } => {
327                    return read_payload(
328                        crate::catalog::type_metadata::pg_type_oid(&base) as u32,
329                        bytes,
330                        catalog,
331                        control,
332                    );
333                }
334                _ => {}
335            }
336        }
337    }
338    match oid {
339        22 => arrays::read_legacy_vector(bytes, uqa_core::LegacyVectorKind::SmallInteger, control),
340        30 => arrays::read_legacy_vector(bytes, uqa_core::LegacyVectorKind::Oid, control),
341        17 => {
342            let mut output = ProductionVec::new(*control);
343            output.reserve(bytes.len())?;
344            for byte in bytes {
345                output.push_copy(*byte)?;
346            }
347            let (bytes, memory) = output.finish()?.into_parts();
348            Ok(control.finish(Value::Bytes(bytes), memory)?)
349        }
350        25 | 114 | 142 | 194 | 1042 | 1043 | 1790 => {
351            let text = std::str::from_utf8(bytes).map_err(|error| SQLError::Routine {
352                sqlstate: "22021".into(),
353                message: format!(
354                    "invalid byte sequence for encoding \"UTF8\": 0x{:02x}",
355                    bytes[error.valid_up_to()]
356                ),
357            })?;
358            let (text, memory) = control.copy_text(text)?.into_parts();
359            let value = match oid {
360                114 => Value::Json(text),
361                1042 => Value::FixedChar(text),
362                _ => Value::Str(text),
363            };
364            Ok(control.finish(value, memory)?)
365        }
366        1560 | 1562 => bit_string::read(bytes, control),
367        3802 => {
368            let (text, memory) =
369                super::json::decode_jsonb_datum_with_control(bytes, control)?.into_parts();
370            Ok(control.finish(Value::JsonB(text), memory)?)
371        }
372        1700 => {
373            let text =
374                crate::catalog::node_tree::decode_numeric_datum_with_control(bytes, control)?;
375            let (number, memory) = DecimalValue::parse_with_control(&text, control)?
376                .ok_or_else(|| corrupt("invalid numeric datum"))?
377                .into_parts();
378            Ok(control.finish(Value::Decimal(number), memory)?)
379        }
380        oid => Err(SQLError::Unsupported(format!(
381            "physical datum output for type OID {oid}"
382        ))),
383    }
384}
385
386/// Borrow ordinary and inline physical bytea payloads; compressed input retains its admitted decompression buffer through consumption.
387pub(super) fn binary_payload<'a>(
388    value: &'a Value,
389    control: &ProductionControl<'_>,
390) -> Result<Option<Payload<'a>>, SQLError> {
391    control.check()?;
392    match value {
393        Value::Bytes(bytes) => Ok(Some(Payload::Borrowed(bytes))),
394        Value::Datum(datum) if datum.type_oid() == 17 => payload(datum, control).map(Some),
395        _ => Ok(None),
396    }
397}
398
399/// Binary length observes the raw-size header and does not decompress the payload.
400pub(super) fn binary_length(
401    value: &Value,
402    control: &ProductionControl<'_>,
403) -> Result<Option<i64>, SQLError> {
404    control.check()?;
405    let datum = match value {
406        Value::Bytes(bytes) => return Ok(Some(bytes.len() as i64)),
407        Value::Datum(datum) if datum.type_oid() == 17 => datum,
408        _ => return Ok(None),
409    };
410    let bytes = datum
411        .bytes()
412        .get(datum.offset() as usize..)
413        .ok_or_else(|| corrupt("invalid datum length"))?;
414    let first = *bytes
415        .first()
416        .ok_or_else(|| corrupt("invalid datum length"))?;
417    let size = if first == 1 && bytes.get(1) == Some(&18) {
418        i64::from(
419            word(bytes.get(2..).unwrap_or_default())
420                .ok_or_else(|| corrupt("invalid datum length"))?,
421        ) - 4
422    } else if first & 1 != 0 {
423        i64::from(first >> 1) - 1
424    } else if first & 3 == 2 {
425        i64::from(
426            word(bytes.get(4..).unwrap_or_default())
427                .ok_or_else(|| corrupt("invalid datum length"))?
428                & 0x3fff_ffff,
429        )
430    } else {
431        i64::from(word(bytes).ok_or_else(|| corrupt("invalid datum length"))? >> 2) - 4
432    };
433    Ok(Some(size))
434}
435
436pub(super) enum Payload<'a> {
437    Borrowed(&'a [u8]),
438    Owned(Produced<Vec<u8>>),
439}
440
441impl Payload<'_> {
442    pub(super) fn bytes(&self) -> &[u8] {
443        match self {
444            Self::Borrowed(bytes) => bytes,
445            Self::Owned(bytes) => bytes,
446        }
447    }
448}
449
450fn payload<'a>(
451    datum: &'a DatumValue,
452    control: &ProductionControl<'_>,
453) -> Result<Payload<'a>, SQLError> {
454    let offset = datum.offset() as usize;
455    let bytes = datum
456        .bytes()
457        .get(offset..)
458        .ok_or_else(|| corrupt("invalid datum length"))?;
459    let first = *bytes
460        .first()
461        .ok_or_else(|| corrupt("invalid datum length"))?;
462    if first == 1 {
463        return Err(malformed::external(datum));
464    }
465    if first & 1 != 0 {
466        let length = usize::from(first >> 1);
467        return bytes
468            .get(1..length)
469            .map(Payload::Borrowed)
470            .ok_or_else(|| corrupt("invalid datum length"));
471    }
472    let header = word(bytes).ok_or_else(|| corrupt("invalid datum length"))?;
473    let length = (header >> 2) as usize;
474    if header & 3 == 2 {
475        let information = word(bytes.get(4..).unwrap_or_default()).unwrap_or(0);
476        let method = information >> 30;
477        let compressed = bytes
478            .get(8..length)
479            .ok_or_else(|| compression::corrupt(method))?;
480        return compression::decompress(
481            compressed,
482            (information & 0x3fff_ffff) as usize,
483            method,
484            control,
485        )
486        .map(Payload::Owned);
487    }
488    bytes
489        .get(4..length)
490        .map(Payload::Borrowed)
491        .ok_or_else(|| corrupt("invalid datum length"))
492}
493
494fn word(bytes: &[u8]) -> Option<u32> {
495    Some(u32::from_le_bytes(bytes.get(..4)?.try_into().ok()?))
496}
497
498fn corrupt(message: &str) -> SQLError {
499    SQLError::Routine {
500        sqlstate: "XX001".into(),
501        message: message.into(),
502    }
503}