Arrow 生产者/消费者

使用 pyarrow

Polars 可以在零拷贝的情况下将数据移入和移出 arrow。这可以通过 pyarrow 或原生方式完成。 我们首先展示 pyarrow 的解决方案：

import polars as pl

df = pl.DataFrame({"foo": [1, 2, 3], "bar": ["ham", "spam", "jam"]})

arrow_table = df.to_arrow()
print(arrow_table)

pyarrow.Table
foo: int64
bar: large_string
----
foo: [[1,2,3]]
bar: [["ham","spam","jam"]]

或者如果你想确保输出是零拷贝：

arrow_table_zero_copy = df.to_arrow(compat_level=pl.CompatLevel.newest())
print(arrow_table_zero_copy)

pyarrow.Table
foo: int64
bar: string_view
----
foo: [[1,2,3]]
bar: [["ham","spam","jam"]]

从pyarrow导入可以通过pl.from_arrow实现。

使用 Arrow PyCapsule 接口

从Polars v1.3及更高版本开始，Polars实现了 Arrow PyCapsule Interface， 这是一个用于在Python库之间共享Arrow数据的协议。

从Polars导出数据到pyarrow

要将Polars的DataFrame转换为pyarrow.Table，请使用pyarrow.table构造函数：

import polars as pl
import pyarrow as pa

df = pl.DataFrame({"foo": [1, 2, 3], "bar": ["ham", "spam", "jam"]})
arrow_table = pa.table(df)
print(arrow_table)

pyarrow.Table
foo: int64
bar: string_view
----
foo: [[1,2,3]]
bar: [["ham","spam","jam"]]

要将Polars的Series转换为pyarrow.ChunkedArray，请使用pyarrow.chunked_array构造函数。

arrow_chunked_array = pa.chunked_array(df["foo"])
print(arrow_chunked_array)

[
  [
    1,
    2,
    3
  ]
]

你也可以传递一个Series给pyarrow.array构造函数来创建一个连续的数组。请注意，如果底层的Series有多个块，这将不会是零拷贝。

arrow_array = pa.array(df["foo"])
print(arrow_array)

[
  1,
  2,
  3
]

从pyarrow导入数据到Polars

我们可以通过使用polars.DataFrame构造函数将pyarrow的Table传递回Polars：

polars_df = pl.DataFrame(arrow_table)
print(polars_df)

shape: (3, 2)
┌─────┬──────┐
│ foo ┆ bar  │
│ --- ┆ ---  │
│ i64 ┆ str  │
╞═════╪══════╡
│ 1   ┆ ham  │
│ 2   ┆ spam │
│ 3   ┆ jam  │
└─────┴──────┘

同样地，我们可以通过使用polars.Series构造函数将pyarrow的ChunkedArray或Array传递回Polars：

polars_series = pl.Series(arrow_chunked_array)
print(polars_series)

shape: (3,)
Series: '' [i64]
[
    1
    2
    3
]

与其他箭头库的使用

有一个不断增长的列表的库直接支持PyCapsule接口。Polars的Series和DataFrame对象可以自动与每个这样的库一起工作。

对于库维护者

如果您正在开发一个希望与Polars集成的库，建议您自己实现 Arrow PyCapsule Interface。 这样做有许多好处：

• Polars Series 和 DataFrame 的零拷贝交换
• 不需要依赖pyarrow。
• 不直接依赖Polars。
• 比将指针作为原始整数处理更难导致内存泄漏。
• 自动零拷贝集成其他支持PyCapsule接口的库。

直接使用Polars

Polars 也可以直接使用和导出到以及从 Arrow C 数据接口 导入。这对于不支持 Arrow PyCapsule 接口并且希望与 Polars 互操作而不需要安装 pyarrow 的库来说是推荐的。

• 要导出ArrowArray C结构体，Polars提供了：Series._export_arrow_to_c。
• 要导入一个ArrowArray C结构体，Polars提供了Series._import_arrow_from_c。