vortex_arrow/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Apache Arrow interoperability for Vortex.
5//!
6//! This crate owns every conversion between Vortex and Arrow: importing Arrow arrays, record
7//! batches, schemas, and fields into Vortex ([`FromArrowArray`], [`FromArrowType`],
8//! [`TryFromArrowType`]), and executing Vortex arrays into Arrow ([`ArrowSession::execute_arrow`]
9//! and the [`ArrowArrayExecutor`] convenience trait).
10//!
11//! The [`ArrowSession`] session variable is created lazily on first use of
12//! [`ArrowSessionExt::arrow`], so no explicit registration is required for plain conversions.
13
14use arrow_array::ArrayRef as ArrowArrayRef;
15use arrow_schema::DataType;
16use vortex_array::ArrayRef;
17use vortex_array::VortexSessionExecute;
18use vortex_array::legacy_session;
19use vortex_error::VortexResult;
20use vortex_session::VortexSession;
21
22mod convert;
23mod datum;
24pub mod dtype;
25mod executor;
26mod iter;
27mod null_buffer;
28mod run_end_import;
29mod scalar;
30mod session;
31mod uuid;
32
33pub use convert::IntoVortexArray;
34pub(crate) use convert::nulls;
35pub use datum::*;
36pub use dtype::FromArrowType;
37pub use dtype::ToArrowType;
38pub use dtype::TryFromArrowType;
39pub use executor::*;
40pub use iter::*;
41pub use null_buffer::to_arrow_null_buffer;
42pub use null_buffer::to_null_buffer;
43pub use scalar::ToArrowDatum;
44pub use session::*;
45
46/// Register vortex-arrow's session extensions into `session`.
47///
48/// This eagerly registers the [`ArrowSession`], which is otherwise created lazily on first use.
49pub fn initialize(session: &VortexSession) {
50    session.register(ArrowSession::default());
51}
52
53/// Construct a Vortex array from an Arrow array (or other Arrow container) of type `A`.
54///
55/// Implementations reuse the underlying Arrow buffers without copying wherever the Arrow and
56/// Vortex memory layouts allow it.
57pub trait FromArrowArray<A> {
58    /// Convert `array` into a Vortex array whose [`DType`](vortex_array::dtype::DType) has the requested
59    /// `nullable` [`Nullability`](vortex_array::dtype::Nullability).
60    ///
61    /// An Arrow array can carry a validity (null) buffer regardless of whether its schema declares
62    /// the field nullable, so the desired nullability is supplied separately by the caller
63    /// (typically from the corresponding Arrow `Field`'s `is_nullable`). This flag is reconciled
64    /// with the array's physical nulls as follows:
65    ///
66    /// - `nullable == true`: the resulting validity is derived from the array's null buffer, or
67    ///   all-valid when the array has none.
68    /// - `nullable == false`: the array must contain no nulls, and the result is non-nullable.
69    ///
70    /// # Errors
71    ///
72    /// Returns an error if `nullable` is `false` but `array` physically contains one or more nulls
73    /// (including an Arrow `NullArray`, which is entirely null), or if the Arrow data type is not
74    /// supported.
75    fn from_arrow(array: A, nullable: bool) -> VortexResult<Self>
76    where
77        Self: Sized;
78}
79
80#[deprecated(note = "Use `execute_arrow(None, ctx)` or `execute_arrow(Some(dt), ctx)` instead")]
81pub trait IntoArrowArray {
82    #[deprecated(note = "Use `execute_arrow(None, ctx)` instead")]
83    fn into_arrow_preferred(self) -> VortexResult<ArrowArrayRef>;
84
85    #[deprecated(note = "Use `execute_arrow(Some(data_type), ctx)` instead")]
86    fn into_arrow(self, data_type: &DataType) -> VortexResult<ArrowArrayRef>;
87}
88
89#[allow(deprecated)]
90impl IntoArrowArray for ArrayRef {
91    /// Convert this [`vortex_array::ArrayRef`] into an Arrow [`ArrowArrayRef`] by using the array's
92    /// preferred (cheapest) Arrow [`DataType`].
93    #[allow(clippy::disallowed_methods)]
94    fn into_arrow_preferred(self) -> VortexResult<ArrowArrayRef> {
95        self.execute_arrow(None, &mut legacy_session().create_execution_ctx())
96    }
97
98    #[allow(clippy::disallowed_methods)]
99    fn into_arrow(self, data_type: &DataType) -> VortexResult<ArrowArrayRef> {
100        self.execute_arrow(
101            Some(data_type),
102            &mut legacy_session().create_execution_ctx(),
103        )
104    }
105}
vortex_arrow/lib.rs

vortex_arrow/
lib.rs
