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 转换的类型定义自定义实现。

要将数据序列化为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; SIZE]如果T实现了ArrowField
• 支持大型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);
}