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

vortex_arrow/
lib.rs
