pyarrow.parquet.write_to_dataset#

pyarrow.parquet.write_to_dataset(table, root_path, partition_cols=None, filesystem=None, schema=None, partitioning=None, basename_template=None, use_threads=None, file_visitor=None, existing_data_behavior=None, **kwargs)[源]#

封装了 dataset.write_dataset，用于按分区将 Table 写入 Parquet 格式。对于分区列和值的每种组合，子目录会按以下方式创建

root_dir/

group1=value1

group2=value1: <uuid>.parquet
group2=value2: <uuid>.parquet

group1=valueN

group2=value1: <uuid>.parquet
group2=valueN: <uuid>.parquet

参数:

tablepyarrow.Table

root_pathstr, pathlib.Path

数据集的根目录。

partition_colslist,

用于对数据集进行分区的列名。列将按照给定顺序进行分区。

filesystemFileSystem, 默认值 None

如果未传递任何内容，将根据路径推断。路径将尝试在本地磁盘文件系统中查找，否则将解析为 URI 以确定文件系统。

schemaSchema，可选

数据集的此 Schema。

partitioningPartitioning or list[str], 可选

使用 pyarrow.dataset.partitioning() 函数指定的分区方案或字段名称列表。提供字段名称列表时，可以使用 partitioning_flavor 来确定应使用哪种分区类型。

basename_templatestr, 可选

用于生成写入数据文件基名称的模板字符串。令牌“{i}”将被自动递增的整数替换。如果未指定，则默认为“guid-{i}.parquet”。

use_threadsbool, 默认 True

并行写入文件。如果启用，将根据可用 CPU 核的数量使用最大并行度。

file_visitor函数

如果设置，此函数将为调用期间创建的每个文件调用一个 WrittenFile 实例。此对象将同时具有 path 属性和 metadata 属性。

path 属性将是一个包含创建文件路径的字符串。

metadata 属性将是文件的 parquet 元数据。此元数据将设置文件 path 属性，并可用于构建一个 _metadata 文件。如果格式不是 parquet，metadata 属性将为 None。

收集创建文件名的示例访问器

visited_paths = []

def file_visitor(written_file):
    visited_paths.append(written_file.path)

existing_data_behavior‘overwrite_or_ignore’ | ‘error’ | ‘delete_matching’

控制数据集如何处理目标中已存在的数据。默认行为是‘overwrite_or_ignore’。

‘overwrite_or_ignore’将忽略任何现有数据，并覆盖与输出文件同名的文件。其他现有文件将被忽略。此行为，结合每次写入的唯一 basename_template，将允许追加工作流。

‘error’如果目标中存在任何数据，将引发错误。

‘delete_matching’在写入分区数据集时很有用。每次遇到分区目录时，整个目录将被删除。这允许您完全覆盖旧分区。

**kwargsdict,

用作额外的 kwargs，用于 pyarrow.dataset.write_dataset() 函数匹配 kwargs，其余传递给 pyarrow.dataset.ParquetFileFormat.make_write_options()。请参阅 write_table() 和 pyarrow.dataset.write_dataset() 的文档字符串以了解可用选项。在 kwargs 中使用 metadata_collector 可以收集数据集片段的文件元数据实例。ColumnChunkMetaData 中的文件路径将相对于 root_path 设置。

示例

生成一个 PyArrow Table 示例

>>> import pyarrow as pa
>>> table = pa.table({'year': [2020, 2022, 2021, 2022, 2019, 2021],
...                   'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})

并将其写入分区数据集

>>> import pyarrow.parquet as pq
>>> pq.write_to_dataset(table, root_path='dataset_name_3',
...                     partition_cols=['year'])
>>> pq.ParquetDataset('dataset_name_3').files
['dataset_name_3/year=2019/...-0.parquet', ...

将单个 Parquet 文件写入根文件夹

>>> pq.write_to_dataset(table, root_path='dataset_name_4')
>>> pq.ParquetDataset('dataset_name_4/').files
['dataset_name_4/...-0.parquet']