serde_arrow - 将Rust对象的序列转换为Arrow数组并返回

包信息 | API文档 | 示例 | 相关包和性能 | 状态 | 许可证 | 变更 | 开发

内存中的arrow格式是一种强大的方式来处理类似数据框的结构。周围的生态系统包括丰富的库，从数据框如 Polars 到查询引擎如 DataFusion。然而，由于Rust的静态类型性质，底层的Rust包的API有时使用起来可能会有些繁琐。

serde_arrow 提供了一种简单的方法将Rust对象转换为Arrow数组并返回。 serde_arrow 依赖于 Serde 包来解释Rust对象。因此，将 serde_arrow 添加到自定义类型支持就像使用Serde的derive宏一样简单。

在Rust生态系统中有两种相互竞争的内存中arrow格式的实现。 serde_arrow 支持用于模式追踪、从Rust结构到数组的序列化和从数组到Rust结构的反序列化的 arrow 和 arrow2。

示例

以下示例假设已经将 serde_arrow 添加到 Cargo.toml 文件中，并配置了其功能。 serde_arrow 支持不同的 arrow 和 arrow2 版本。可以通过指定正确的功能来选择相关版本（例如，使用 arrow-51 支持箭头版本 arrow=51）。更多详情请见这里。

以下示例使用以下 Rust 结构和示例记录

#[derive(Serialize, Deserialize)]
struct Record {
    a: f32,
    b: i32,
}

let records = vec![
    Record { a: 1.0, b: 1 },
    Record { a: 2.0, b: 2 },
    Record { a: 3.0, b: 3 },
];

序列化为 arrow RecordBatch

use arrow::datatypes::FieldRef;
use serde_arrow::schema::{SchemaLike, TracingOptions};

// Determine Arrow schema
let fields = Vec::<FieldRef>::from_type::<Record>(TracingOptions::default())?;

// Build a record batch
let batch = serde_arrow::to_record_batch(&fields, &records)?;

现在可以使用来自 parquet crate 的 ArrowWriter 将这个 RecordBatch 写入磁盘。

let file = File::create("example.pq");
let mut writer = ArrowWriter::try_new(file, batch.schema(), None)?;
writer.write(&batch)?;
writer.close()?;

序列化为 arrow2 数组

use arrow2::datatypes::Field;
use serde_arrow::schema::{SchemaLike, TracingOptions};

let fields = Vec::<Field>::from_type::<Record>(TracingOptions::default())?;
let arrays = serde_arrow::to_arrow2(&fields, &records)?;

现在可以使用 arrow2 指南中定义的辅助方法将这些数组写入磁盘。对于 parquet

use arrow2::{chunk::Chunk, datatypes::Schema};

// see https://jorgecarleitao.github.io/arrow2/io/parquet_write.html
write_chunk(
    "example.pq",
    Schema::from(fields),
    Chunk::new(arrays),
)?;

Python 中的使用

可以通过以下方式在 Python 中读取写入的文件

# using polars
>>> import polars as pl
>>> pl.read_parquet("example.pq")
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ f32 ┆ i32 │
╞═════╪═════╡
│ 1.0 ┆ 1   │
│ 2.0 ┆ 2   │
│ 3.0 ┆ 3   │
└─────┴─────┘

# using pandas
>>> import pandas as pd
>>> pd.read_parquet("example.pq")
     a  b
0  1.0  1
1  2.0  2
2  3.0  3

相关软件包 & 性能

• arrow: 官方 Arrow 包的 JSON 组件支持通过 Decoder 对象序列化支持序列化的对象。它支持基本类型、结构体和列表
• arrow2-convert: 为从箭头2数组转换对象和从对象到箭头2数组添加 derive 宏。它支持基本类型、结构体、列表和 chrono 的日期时间类型。枚举支持是实验性的，如 Readme 所述。如果性能是主要目标，arrow2-convert 是一个好的选择，因为它在手动构建数组时没有或最小化开销。

与其他实现相比，以下性能差异

以下列出了 基准测试 的详细运行时间。

complex_common_serialize(100000)

complex_common_serialize(1000000)

primitives_serialize(100000)

primitives_serialize(1000000)

许可证

Copyright (c) 2021 - 2024 Christopher Prohm and contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.