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

vortex_arrow/
lib.rs
