数据帧交换协议

该交换协议已在 pa.Table 和 pa.RecordBatch 中实现，用于在 PyArrow 与其他同样实现了该协议的数据帧库之间进行数据交换。协议支持的数据结构包括原始数据类型和字典数据类型。该协议还具备缺失数据支持，并支持分块（chunking），即以“批次”行的方式访问数据。

Python 数据帧交换协议由 Python 数据 API 标准联盟设计，旨在实现 Python 生态系统中各数据帧库之间的数据交换。有关该标准的更多信息，请参阅 协议文档。

注意

在不同数据帧库之间进行转换的推荐方式是通过 Arrow PyCapsule 接口，例如在实现了该接口的数据帧对象上调用 pa.table(df)。

从 PyArrow 到其他库：__dataframe__() 方法

__dataframe__() 方法创建一个新的交换对象，消费库可以使用该对象构建其自身的数据对象。

>>> import pyarrow as pa
>>> table = pa.table({"n_attendees": [100, 10, 1]})
>>> table.__dataframe__()
<pyarrow.interchange.dataframe._PyArrowDataFrame object at ...>

此方法旨在供消费库在调用 from_dataframe() 函数时使用，不建议用户手动调用。

从其他库到 PyArrow：from_dataframe()

使用 from_dataframe() 函数，我们可以从任何实现了 __dataframe__() 方法的数据帧对象（通过数据帧交换协议）构建一个 pyarrow.Table。

例如，我们可以利用交换协议获取一个 Polars 数据帧并构建一个 PyArrow 表。

>>> import polars as pl
>>> from datetime import datetime
>>> arr = [datetime(2023, 5, 20, 10, 0),
...        datetime(2023, 5, 20, 11, 0),
...        datetime(2023, 5, 20, 13, 30)]
>>> df = pl.DataFrame({
...          'Talk': ['About Polars','Intro into PyArrow','Coding in Rust'],
...          'Time': arr,
...      })
>>> df
shape: (3, 2)
┌────────────────────┬─────────────────────┐
│ Talk               ┆ Time                │
│ ---                ┆ ---                 │
│ str                ┆ datetime[μs]        │
╞════════════════════╪═════════════════════╡
│ About Polars       ┆ 2023-05-20 10:00:00 │
│ Intro into PyArrow ┆ 2023-05-20 11:00:00 │
│ Coding in Rust     ┆ 2023-05-20 13:30:00 │
└────────────────────┴─────────────────────┘
>>> from_dataframe(df)
pyarrow.Table
Talk: large_string
Time: timestamp[us]
----
Talk: [["About Polars","Intro into PyArrow","Coding in Rust"]]
Time: [[2023-05-20 10:00:00.000000,2023-05-20 11:00:00.000000,2023-05-20 13:30:00.000000]]