Skip to main content

vortex_array/arrays/decimal/compute/
rules.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use std::ops::Range;
5
6use vortex_error::VortexResult;
7
8use crate::ArrayRef;
9use crate::IntoArray;
10use crate::array::ArrayView;
11use crate::arrays::Decimal;
12use crate::arrays::DecimalArray;
13use crate::arrays::Masked;
14use crate::arrays::slice::SliceReduce;
15use crate::arrays::slice::SliceReduceAdaptor;
16use crate::match_each_decimal_value_type;
17use crate::optimizer::rules::ArrayParentReduceRule;
18use crate::optimizer::rules::ParentRuleSet;
19use crate::scalar_fn::fns::cast::CastReduceAdaptor;
20use crate::scalar_fn::fns::mask::MaskReduceAdaptor;
21
22pub(crate) static RULES: ParentRuleSet<Decimal> = ParentRuleSet::new(&[
23    ParentRuleSet::lift(&DecimalMaskedValidityRule),
24    ParentRuleSet::lift(&CastReduceAdaptor(Decimal)),
25    ParentRuleSet::lift(&MaskReduceAdaptor(Decimal)),
26    ParentRuleSet::lift(&SliceReduceAdaptor(Decimal)),
27]);
28
29/// Rule to push down validity masking from MaskedArray parent into DecimalArray child.
30///
31/// When a DecimalArray is wrapped by a MaskedArray, this rule merges the mask's validity
32/// with the DecimalArray's existing validity, eliminating the need for the MaskedArray wrapper.
33#[derive(Default, Debug)]
34pub struct DecimalMaskedValidityRule;
35
36impl ArrayParentReduceRule<Decimal> for DecimalMaskedValidityRule {
37    type Parent = Masked;
38
39    fn reduce_parent(
40        &self,
41        array: ArrayView<'_, Decimal>,
42        parent: ArrayView<'_, Masked>,
43        _child_idx: usize,
44    ) -> VortexResult<Option<ArrayRef>> {
45        // Merge the parent's validity mask into the child's validity
46        // TODO(joe): make this lazy
47        let masked_array = match_each_decimal_value_type!(array.values_type(), |D| {
48            // SAFETY: Since we are only flipping some bits in the validity, all invariants that
49            // were upheld are still upheld.
50            unsafe {
51                DecimalArray::new_unchecked(
52                    array.buffer::<D>(),
53                    array.decimal_dtype(),
54                    array.validity()?.and(parent.validity()?)?,
55                )
56            }
57            .into_array()
58        });
59
60        Ok(Some(masked_array))
61    }
62}
63
64impl SliceReduce for Decimal {
65    fn slice(array: ArrayView<'_, Self>, range: Range<usize>) -> VortexResult<Option<ArrayRef>> {
66        let byte_width = array.values_type().byte_width();
67        let byte_range = range.start * byte_width..range.end * byte_width;
68        let values = array.buffer_handle().slice(byte_range);
69        let validity = array.validity()?.slice(range)?;
70
71        // SAFETY: Slicing on element boundaries preserves the buffer alignment, values type,
72        // decimal precision and scale, and validity length invariants.
73        let result = unsafe {
74            DecimalArray::new_unchecked_handle(
75                values,
76                array.values_type(),
77                array.decimal_dtype(),
78                validity,
79            )
80            .into_array()
81        };
82        Ok(Some(result))
83    }
84}
85
86#[cfg(test)]
87mod tests {
88    use std::any::Any;
89    use std::ops::Range;
90    use std::sync::Arc;
91    use std::sync::LazyLock;
92
93    use futures::future::BoxFuture;
94    use num_traits::AsPrimitive;
95    use rstest::rstest;
96    use vortex_buffer::Alignment;
97    use vortex_buffer::Buffer;
98    use vortex_buffer::ByteBuffer;
99    use vortex_error::VortexResult;
100    use vortex_error::vortex_bail;
101    use vortex_error::vortex_err;
102    use vortex_session::VortexSession;
103
104    use crate::IntoArray;
105    use crate::VortexSessionExecute;
106    use crate::arrays::Decimal;
107    use crate::arrays::DecimalArray;
108    use crate::assert_arrays_eq;
109    use crate::buffer::BufferHandle;
110    use crate::buffer::DeviceBuffer;
111    use crate::dtype::DecimalDType;
112    use crate::dtype::DecimalType;
113    use crate::match_each_decimal_value_type;
114    use crate::validity::Validity;
115
116    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
117
118    // Host-backed storage exposes device slicing without allowing implicit host copies.
119    #[derive(Debug, PartialEq, Eq, Hash)]
120    struct TestDeviceBuffer(ByteBuffer);
121
122    impl DeviceBuffer for TestDeviceBuffer {
123        fn as_any(&self) -> &dyn Any {
124            self
125        }
126
127        fn len(&self) -> usize {
128            self.0.len()
129        }
130
131        fn alignment(&self) -> Alignment {
132            self.0.alignment()
133        }
134
135        fn copy_to_host_sync(&self, _alignment: Alignment) -> VortexResult<ByteBuffer> {
136            vortex_bail!("decimal slicing must not copy device values to the host")
137        }
138
139        fn copy_to_host(
140            &self,
141            _alignment: Alignment,
142        ) -> VortexResult<BoxFuture<'static, VortexResult<ByteBuffer>>> {
143            vortex_bail!("decimal slicing must not copy device values to the host")
144        }
145
146        fn slice(&self, range: Range<usize>) -> Arc<dyn DeviceBuffer> {
147            Arc::new(Self(self.0.slice(range)))
148        }
149
150        fn aligned(self: Arc<Self>, alignment: Alignment) -> VortexResult<Arc<dyn DeviceBuffer>> {
151            assert!(self.alignment().is_aligned_to(alignment));
152            Ok(self)
153        }
154    }
155
156    // Exercise composed byte offsets at every storage width without allowing a host copy.
157    #[rstest]
158    fn test_slice_buffer_handle(
159        #[values(
160            DecimalType::I8,
161            DecimalType::I16,
162            DecimalType::I32,
163            DecimalType::I64,
164            DecimalType::I128,
165            DecimalType::I256
166        )]
167        values_type: DecimalType,
168    ) -> VortexResult<()> {
169        let mut ctx = SESSION.create_execution_ctx();
170        let bytes = match_each_decimal_value_type!(values_type, |D| {
171            Buffer::<D>::from_iter([-12i8, 34, -56, 78, 90, 12].map(|value| value.as_()))
172                .into_byte_buffer()
173        });
174        let handle = BufferHandle::new_device(Arc::new(TestDeviceBuffer(bytes.clone())));
175        let validity = Validity::from_iter([true, false, true, false, true, true]);
176        let array = DecimalArray::try_new_handle(
177            handle,
178            values_type,
179            DecimalDType::new(3, 1),
180            validity.clone(),
181        )?
182        .into_array();
183        let sliced = array.slice(1..5)?;
184
185        let range = 1..3;
186        let nested = sliced.slice(range.clone())?;
187        let decimal = nested.as_::<Decimal>();
188        let byte_width = values_type.byte_width();
189        let original_range = range.start + 1..range.end + 1;
190        let expected_bytes =
191            bytes.slice(original_range.start * byte_width..original_range.end * byte_width);
192        let handle = decimal.buffer_handle();
193
194        assert_eq!(nested.len(), range.len());
195        assert_eq!(nested.dtype(), array.dtype());
196        assert_eq!(decimal.values_type(), values_type);
197        assert_eq!(handle.len(), range.len() * byte_width);
198        assert!(handle.is_on_device());
199        assert!(handle.is_aligned_to(bytes.alignment()));
200
201        let actual_bytes = &handle
202            .as_device()
203            .as_any()
204            .downcast_ref::<TestDeviceBuffer>()
205            .ok_or_else(|| vortex_err!("expected TestDeviceBuffer"))?
206            .0;
207        assert_eq!(actual_bytes, &expected_bytes);
208        assert_eq!(actual_bytes.as_ptr(), expected_bytes.as_ptr());
209        assert_arrays_eq!(
210            decimal.validity()?.to_array(nested.len()),
211            validity.to_array(array.len()).slice(original_range)?,
212            &mut ctx
213        );
214
215        Ok(())
216    }
217}