arrow_convert

在 arrow-rs 上提供API，用于在Rust类型和Arrow之间进行转换。此存储库是从直接转换为 arrow2-convert 库移植而来，用于与 arrow-rs 一起使用。

Arrow生态系统提供了多种方法，可以在Arrow和其他几种语言的流行格式之间进行转换。本项目旨在满足以Rust为中心的数据管道轻松将数据转换为/从Arrow的需求，同时具有强类型和任意嵌套。

示例

以下示例展示了具有单个字段的结构的往返转换。

请参阅 complex_example.rs 以了解完整功能的用法。

/// Simple example

use arrow::array::{Array, ArrayRef};
use arrow_convert::{deserialize::TryIntoCollection, serialize::TryIntoArrow, ArrowField, ArrowSerialize, ArrowDeserialize};

#[derive(Debug, Clone, PartialEq, ArrowField, ArrowSerialize, ArrowDeserialize)]
pub struct Foo {
    name: String,
}

fn main() {
    // an item
    let original_array = [
        Foo { name: "hello".to_string() },
        Foo { name: "one more".to_string() },
        Foo { name: "good bye".to_string() },
    ];

    // serialize to an arrow array. try_into_arrow() is enabled by the TryIntoArrow trait
    let arrow_array: ArrayRef = original_array.try_into_arrow().unwrap();

    // which can be cast to an Arrow StructArray and be used for all kinds of IPC, FFI, etc.
    // supported by `arrow`
    let struct_array= arrow_array.as_any().downcast_ref::<arrow::array::StructArray>().unwrap();
    assert_eq!(struct_array.len(), 3);

    // deserialize back to our original vector via TryIntoCollection trait.
    let round_trip_array: Vec<Foo> = arrow_array.try_into_collection().unwrap();
    assert_eq!(round_trip_array, original_array);
}

API

实现 ArrowField、ArrowSerialize 和 ArrowDeserialize 特性的类型可以通过 try_into_arrow 和 try_into_collection 方法转换为/从Arrow。

可以使用 ArrowField、ArrowSerialize 和 ArrowDeserialize derive宏为结构体和枚举生成这些特性的实现。还可以通过手动实现这些特性为任何需要转换为/从Arrow的类型定义自定义实现。

要将数据序列化为arrow格式，可以使用 TryIntoArrow::try_into_arrow 来将任何可迭代序列序列化为一个 arrow::Array 或一个 arrow::Chunk。其中，arrow::Array 代表内存中的Arrow布局。而 arrow::Chunk 代表一个列组，可以与 arrow API 结合使用，实现诸如转换为parquet和arrow flight RPC等操作。

要从arrow格式反序列化，可以使用 TryIntoCollection::try_into_collection 将 arrow::Array 表示形式反序列化为实现了 FromIterator 的任何容器。

默认实现

以下提供了上述特质的默认实现：

• 数值类型
  • [u8], [u16], [u32], [u64], [i8], [i16], [i32], [i64], [f32], [f64]
  • i128 通过 type 属性支持。请参阅 i128 部分 了解更多详情。
• 其他类型
  • bool、String、Binary
• 时间类型
  • chrono::NaiveDate、chrono::NaiveDateTime
• 如果 T 实现 ArrowField，则为 Option
• 如果 T 实现 ArrowField，则为 Vec
• 如果 T 实现 ArrowField，则为 [T; SIZE]
• 大 Arrow 类型 LargeBinary、LargeString、LargeList 通过 type 属性支持。请参阅 complex_example.rs 了解使用方法。
• 固定大小类型 FixedSizeBinary、FixedSizeList 通过 FixedSizeVec 类型覆盖支持。
  • 注意：不支持 FixedSizeList 的嵌套。

use arrow_convert::field::I128;
use arrow_convert::ArrowField;

#[derive(Debug, ArrowField)]
struct S {
    #[arrow_field(type = "I128<32, 32>")]
    field: i128,
}

use arrow::array::{Array, ArrayBuilder, ArrayRef};
use arrow_convert::serialize::arrow_serialize_to_mutable_array;
use arrow_convert::deserialize::arrow_array_deserialize_iterator_as_type;
use arrow_convert::field::I128;
use std::borrow::Borrow;
use std::sync::Arc;

fn convert_i128() {
    let original_array = vec![1 as i128, 2, 3];
    let b: ArrayRef = Arc::new(arrow_serialize_to_mutable_array::<_, I128<32,32>, _>(
        &original_array).unwrap().finish());
    let round_trip: Vec<i128> = arrow_array_deserialize_iterator_as_type::<_, I128<32,32>>(
        b.borrow()).unwrap().collect();
    assert_eq!(original_array, round_trip);
}