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

vortex_arrow/
lib.rs
