Apache Arrow 官方原生 Rust 实现

本软件包包含由 Apache 软件基金会管理的 Apache Arrow 内存格式官方原生 Rust 实现。

API 文档包含示例和完整 API。 也有一些示例 可以从中开始。

最新未发布代码的 API 文档在这里 可用。

Rust 版本兼容性

本软件包使用最新的稳定版本的 Rust 进行测试。我们目前不测试其他较旧的版本。

版本/发布

arrow 软件包遵循 Cargo 定义的 SemVer 标准，并在 Rust 软件包生态系统中运行良好。有关发布计划和版本详细信息，请参阅仓库 README。

请注意，由于历史原因，这个crate使用主版本号大于 0.x（例如 19.0.0）的版本，这与Rust生态系统中的许多其他crate不同，这些crate花费了很长时间发布 0.x 版本，以表示计划中的API更改。次要版本发布仅包含兼容性更改，而主要版本可能包含破坏性API更改。

功能标志

arrow crate提供了以下功能，可以在您的Cargo.toml中启用

• csv（默认）- 支持将Arrow数组读取和写入csv文件
• json（默认）- 支持将Arrow数组读取和写入json文件
• ipc（默认）- 支持读取Arrow IPC格式，也用作arrow-flight中的网络协议
• ipc_compression - 启用读取和写入压缩IPC流（同时启用ipc）
• prettyprint - 支持将记录批次格式化为文本列，以及某些计算的实现
• chrono-tz - 支持使用chrono-tz解析时区
• ffi - Arrow C C数据接口的绑定
• pyarrow - pyo3的绑定，用于从python调用arrow-rs

Arrow功能状态

Apache Arrow状态页面列出了此crate支持的Arrow功能。

安全性

Arrow致力于遵守Rust清晰性誓言，正如此处所阐述的那样。具体而言

此crate的意图是避免清晰的错误。开发者将尽力避免它们，并欢迎帮助分析和修复它们

清晰性被定义为

代码无法使用安全API触发未定义的行为

确保这一点的一种方法是不使用unsafe，然而，如Rustonomicon的开篇章节所述，这并不是一个要求，在这方面有灵活性是Rust的伟大优势之一。

特别是，有许多场景下unsafe几乎是不可避免的

• 无法由编译器静态验证的约定，并解锁非平凡的性能提升，例如StringArray中的值是UTF-8，TrustedLen迭代器等...
• FFI

此外，此crate公开了一些unsafe API，允许下游crate在适当的情况下明确选择退出可能昂贵的约定检查。

我们有一些策略来帮助降低这种风险

• 提供强类型化的Array和ArrayBuilder API，以安全高效地与数组交互
• 广泛的验证逻辑，以安全地从不可信的来源构建ArrayData
• 所有提交都使用MIRI进行验证，以检测未定义的行为
• 使用force_validate功能，该功能可以在测试/调试构建中启用额外的验证检查
• 我们正在进行减少和更好地记录使用unsafe的工作，并欢迎在此领域做出贡献

为WASM构建

箭头（Arrow）可以使用 wasm32-unknown-unknown 和 wasm32-wasi 目标编译为 WebAssembly。

为了编译箭头（Arrow）为 wasm32-unknown-unknown，您需要禁用默认功能，然后包含所需的功能，但排除测试依赖（test_utils 功能）。例如，在您的 Cargo.toml 中使用以下片段：

[dependencies]
arrow = { version = "5.0", default-features = false, features = ["csv", "ipc"] }

示例

示例文件夹展示了如何构建不同类型的箭头数组，包括动态数组。

可以使用 cargo run --example 命令运行示例。例如：

cargo run --example builders
cargo run --example dynamic_types
cargo run --example read_csv

性能提示

箭头（Arrow）旨在尽可能快，同时不牺牲安全性。然而，它严重依赖 LLVM 自动向量化来实现这一点。不幸的是，LLVM 的默认设置，尤其是针对 x86_64，更倾向于便携性而不是性能，并且 LLVM 将避免使用可能导致旧 CPU 错误的最新指令。

为了解决这个问题，建议您通过设置 RUSTFLAGS 环境变量或在您的 Cargo 配置 中设置 rustflags 来覆盖 LLVM 的默认设置。

启用当前 CPU 支持的所有功能

RUSTFLAGS="-C target-cpu=native"

启用当前 CPU 支持的所有功能，并启用 AVX512 的完全使用

RUSTFLAGS="-C target-cpu=native -C target-feature=-prefer-256-bit"

启用比 haswell（2013 年）更新的 CPU 支持的所有功能

RUSTFLAGS="-C target-cpu=haswell"

要获取功能列表和目标 CPU 的完整列表，请使用

$ rustc --print target-cpus
$ rustc --print target-features