Skip to main content

vortex_array/arrays/widen/vtable/
plugin.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Serialization of decimal `Widen` arrays as narrow `vortex.decimal` nodes.
5//!
6//! The node stores the child's buffer width, while its containing format supplies the logical dtype
7//! of the `Widen`. No `Widen` node or child decimal dtype is written.
8//!
9//! This uses the legacy decimal wire format because [`Widen`] has no wire representation of its
10//! own. Noncanonical stored widths can therefore come from current writers as well as old files.
11
12use vortex_error::VortexResult;
13use vortex_error::vortex_bail;
14use vortex_session::VortexSession;
15
16use crate::ArrayDeserialization;
17use crate::ArrayId;
18use crate::ArrayPlugin;
19use crate::ArrayRef;
20use crate::ArraySerialization;
21use crate::ArrayVTable;
22use crate::arrays::Decimal;
23use crate::arrays::Widen;
24use crate::arrays::widen::WidenArraySlotsExt;
25use crate::session::ArraySessionExt;
26
27/// Writes a decimal [`Widen`] as one `vortex.decimal` node with its child's values buffer.
28///
29/// The old decimal wire format allows a buffer narrower than the logical dtype's canonical width.
30/// For example, a `Widen` of `Decimal(38, 2)` over a `Decimal(9, 2)` child writes the child's `i32`
31/// buffer while keeping the logical dtype `Decimal(38, 2)`.
32///
33/// The child **must** be a [`Decimal`] leaf. Its serializer supplies width metadata, buffers and
34/// validity children through [`ArraySerialization`], which contains no dtype. The containing format
35/// supplies the original `Widen` dtype and length, and array serialization keeps its statistics.
36///
37/// This plugin registers only a writer. The decimal reader handles the resulting node. Serialization
38/// executes neither values nor validity, so integer arrays, non-decimal children and validity that
39/// cannot be serialized require preparation by the caller.
40#[derive(Clone, Debug)]
41pub struct WidenPlugin;
42
43impl ArrayPlugin for WidenPlugin {
44    fn id(&self) -> ArrayId {
45        ArrayVTable::id(&Widen)
46    }
47
48    fn read_ids(&self) -> Vec<ArrayId> {
49        vec![]
50    }
51
52    fn write_ids(&self) -> Vec<ArrayId> {
53        vec![ArrayVTable::id(&Decimal)]
54    }
55
56    fn serialize(
57        &self,
58        array: &ArrayRef,
59        session: &VortexSession,
60    ) -> VortexResult<Option<ArraySerialization>> {
61        let widen = array.as_::<Widen>();
62        if !array.dtype().is_decimal() {
63            vortex_bail!(
64                "Widen serialization requires a decimal dtype, got {}",
65                array.dtype()
66            );
67        }
68
69        let values = widen.values();
70        if !values.is::<Decimal>() {
71            vortex_bail!(
72                "Decimal Widen serialization requires a Decimal leaf, got {}",
73                values.encoding_id()
74            );
75        }
76
77        // Only the child's wire components are returned, not its dtype. The enclosing format and
78        // serialization tree still use the original Widen's logical dtype and statistics.
79        session.array_serialize(values)
80    }
81
82    fn deserialize(
83        &self,
84        _parts: ArrayDeserialization<'_>,
85        _session: &VortexSession,
86    ) -> VortexResult<ArrayRef> {
87        vortex_bail!("Widen has no wire form yet (#10733)")
88    }
89}