vortex_array/arrow/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Utilities to work with `Arrow` data and types.
5
6use arrow_array::ArrayRef as ArrowArrayRef;
7use arrow_schema::DataType;
8use vortex_error::VortexResult;
9
10mod convert;
11mod datum;
12mod executor;
13mod iter;
14mod null_buffer;
15mod session;
16
17pub(crate) use convert::nulls;
18pub use datum::*;
19pub use executor::*;
20pub use iter::*;
21pub use null_buffer::to_arrow_null_buffer;
22pub use null_buffer::to_null_buffer;
23pub use session::*;
24
25use crate::ArrayRef;
26use crate::LEGACY_SESSION;
27use crate::VortexSessionExecute;
28
29/// Construct a Vortex array from an Arrow array (or other Arrow container) of type `A`.
30///
31/// Implementations reuse the underlying Arrow buffers without copying wherever the Arrow and
32/// Vortex memory layouts allow it.
33pub trait FromArrowArray<A> {
34    /// Convert `array` into a Vortex array whose [`DType`](crate::dtype::DType) has the requested
35    /// `nullable` [`Nullability`](crate::dtype::Nullability).
36    ///
37    /// An Arrow array can carry a validity (null) buffer regardless of whether its schema declares
38    /// the field nullable, so the desired nullability is supplied separately by the caller
39    /// (typically from the corresponding Arrow `Field`'s `is_nullable`). This flag is reconciled
40    /// with the array's physical nulls as follows:
41    ///
42    /// - `nullable == true`: the resulting validity is derived from the array's null buffer, or
43    ///   all-valid when the array has none.
44    /// - `nullable == false`: the array must contain no nulls, and the result is non-nullable.
45    ///
46    /// # Errors
47    ///
48    /// Returns an error if `nullable` is `false` but `array` physically contains one or more nulls
49    /// (including an Arrow `NullArray`, which is entirely null), or if the Arrow data type is not
50    /// supported.
51    fn from_arrow(array: A, nullable: bool) -> VortexResult<Self>
52    where
53        Self: Sized;
54}
55
56#[deprecated(note = "Use `execute_arrow(None, ctx)` or `execute_arrow(Some(dt), ctx)` instead")]
57pub trait IntoArrowArray {
58    #[deprecated(note = "Use `execute_arrow(None, ctx)` instead")]
59    fn into_arrow_preferred(self) -> VortexResult<ArrowArrayRef>;
60
61    #[deprecated(note = "Use `execute_arrow(Some(data_type), ctx)` instead")]
62    fn into_arrow(self, data_type: &DataType) -> VortexResult<ArrowArrayRef>;
63}
64
65#[allow(deprecated)]
66impl IntoArrowArray for ArrayRef {
67    /// Convert this [`crate::ArrayRef`] into an Arrow [`crate::ArrayRef`] by using the array's
68    /// preferred (cheapest) Arrow [`DataType`].
69    fn into_arrow_preferred(self) -> VortexResult<ArrowArrayRef> {
70        self.execute_arrow(None, &mut LEGACY_SESSION.create_execution_ctx())
71    }
72
73    fn into_arrow(self, data_type: &DataType) -> VortexResult<ArrowArrayRef> {
74        self.execute_arrow(Some(data_type), &mut LEGACY_SESSION.create_execution_ctx())
75    }
76}
vortex_array/arrow/mod.rs

vortex_array/arrow/
mod.rs
