数据帧交换协议

交换协议针对 pa.Table 和 pa.RecordBatch 实现，并用于在 PyArrow 和其他也实现了该协议的数据帧库之间交换数据。协议中支持的数据结构是基本数据类型加上字典数据类型。该协议还支持缺失数据，并支持分块，这意味着可以按行“批次”访问数据。

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

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

The __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。

例如，我们可以使用交换协议获取 pandas 数据框并构建 PyArrow 表

>>> import pyarrow
>>> from pyarrow.interchange import from_dataframe

>>> import pandas as pd
>>> df = pd.DataFrame({
...         "n_attendees": [100, 10, 1],
...         "country": ["Italy", "Spain", "Slovenia"],
...     })
>>> df
   n_attendees   country
0          100     Italy
1           10     Spain
2            1  Slovenia
>>> from_dataframe(df)
pyarrow.Table
n_attendees: int64
country: large_string
----
n_attendees: [[100,10,1]]
country: [["Italy","Spain","Slovenia"]]

我们也可以对 polars 数据框执行相同的操作

>>> 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]]