入门#

Arrow 使用数组（pyarrow.Array）管理数据，这些数组可以组合成表（pyarrow.Table），以表示表格数据中的列。

Arrow 还支持多种格式，以便将这些表格数据存入或读出磁盘及网络。最常用的格式是 Parquet（读取和写入 Apache Parquet 格式）和 IPC 格式（流式传输、序列化和 IPC）。

创建数组和表#

Arrow 中的数组是类型统一的数据集合。这使得 Arrow 能够使用性能最优的实现来存储数据并对其执行计算。因此，每个数组都旨在包含数据和特定的类型。

>>> import pyarrow as pa
>>> days = pa.array([1, 12, 17, 23, 28], type=pa.int8())

当多个数组被赋予列名并组合在一起时，它们可以在表中形成表格数据的列。

>>> months = pa.array([1, 3, 5, 7, 1], type=pa.int8())
>>> years = pa.array([1990, 2000, 1995, 2000, 1995], type=pa.int16())
>>> birthdays_table = pa.table([days, months, years],
...                            names=["days", "months", "years"])
>>> birthdays_table
pyarrow.Table
days: int8
months: int8
years: int16
----
days: [[1,12,17,23,28]]
months: [[1,3,5,7,1]]
years: [[1990,2000,1995,2000,1995]]

有关更多详细信息，请参阅数据类型和内存中数据模型。

保存和加载表#

一旦拥有了表格数据，Arrow 就能开箱即用地提供保存和恢复这些数据的功能，支持 Parquet 等常见格式。

>>> import pyarrow.parquet as pq
>>> pq.write_table(birthdays_table, 'birthdays.parquet')

数据存入磁盘后，只需调用一个函数即可将其加载回来。由于 Arrow 在内存和速度方面进行了深度优化，因此数据加载将尽可能快速。

>>> reloaded_birthdays = pq.read_table('birthdays.parquet')
>>> reloaded_birthdays
pyarrow.Table
days: int8
months: int8
years: int16
----
days: [[1,12,17,23,28]]
months: [[1,3,5,7,1]]
years: [[1990,2000,1995,2000,1995]]

在 Arrow 中保存和加载数据通常通过 Parquet、IPC 格式（Feather 文件格式）、CSV 或行分隔 JSON 格式完成。

执行计算#

Arrow 自带一系列计算函数，可应用于其数组和表。通过这些计算函数，可以对数据进行转换。

>>> import pyarrow.compute as pc
>>> pc.value_counts(birthdays_table["years"])
<pyarrow.lib.StructArray object at ...>
-- is_valid: all not null
-- child 0 type: int16
  [
    1990,
    2000,
    1995
  ]
-- child 1 type: int64
  [
    1,
    2,
    2
  ]

有关可用计算函数及其使用方法的列表，请参阅计算函数。

处理大数据#

Arrow 还提供了 pyarrow.dataset API 来处理大数据，它会为您处理将数据分区为较小块的工作。

>>> import pyarrow.dataset as ds
>>> ds.write_dataset(birthdays_table, "savedir", format="parquet",
...                  partitioning=ds.partitioning(
...                     pa.schema([birthdays_table.schema.field("years")])
...                 ))

重新加载分区数据集时，它会自动检测这些数据块，

>>> birthdays_dataset = ds.dataset("savedir", format="parquet", partitioning=["years"])
>>> birthdays_dataset.files
['savedir/1990/part-0.parquet', 'savedir/1995/part-0.parquet', 'savedir/2000/part-0.parquet']

并仅在迭代这些数据块时才进行惰性加载。

>>> current_year = 2025
>>> for table_chunk in birthdays_dataset.to_batches():
...     print("AGES", pc.subtract(current_year, table_chunk["years"]))
AGES [
  35
]
AGES [
  30,
  30
]
AGES [
  25,
  25
]

有关如何处理大数据集、如何进行过滤、投影等操作的更多详细信息，请参考表格数据集文档。

后续学习#

如需深入了解 Arrow，您可以阅读 PyArrow 文档本身，或查看 Arrow Python 食谱 (Cookbook)。