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