polars.DataFrame.write_parquet#

DataFrame.write_parquet(
file: str | Path | IO[bytes],
*,
compression: ParquetCompression = 'zstd',
compression_level: int | None = None,
statistics: bool | str | dict[str, bool] = True,
row_group_size: int | None = None,
data_page_size: int | None = None,
use_pyarrow: bool = False,
pyarrow_options: dict[str, Any] | None = None,
partition_by: str | Sequence[str] | None = None,
partition_chunk_size_bytes: int = 4294967296,
storage_options: dict[str, Any] | None = None,
credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
retries: int = 2,
) → None[source]#

写入Apache Parquet文件。

Parameters:
file

文件路径或可写的类文件对象，结果将被写入其中。 如果要写入分区数据集，这应该是一个目录的路径。

compression{‘lz4’, ‘uncompressed’, ‘snappy’, ‘gzip’, ‘lzo’, ‘brotli’, ‘zstd’}

选择“zstd”以获得良好的压缩性能。 选择“lz4”以实现快速的压缩/解压缩。 选择“snappy”以在处理较旧的parquet读取器时获得更多的向后兼容性保证。

compression_level

使用的压缩级别。更高的压缩意味着磁盘上的文件更小。

  • “gzip” : 最小级别: 0, 最大级别: 10.

  • “brotli”：最小级别：0，最大级别：11。

  • “zstd” : 最小级别: 1, 最大级别: 22.

statistics

将统计信息写入parquet头部。这是默认行为。

可能的值：

  • True: 启用默认的统计集合（默认）

  • False: 禁用所有统计信息

  • “full”：计算并写入所有可用的统计信息。不能与use_pyarrow结合使用。

  • { "statistic-key": True / False, ... }. 不能与 use_pyarrow 结合使用。可用的键:

    • “min”: 列的最小值 (默认: True)

    • “max”: 列的最大值 (默认: True)

    • “distinct_count”: 唯一列值的数量（默认值：False）

    • “null_count”: 列中空值的数量（默认值：True）

row_group_size

行组的大小，以行数为单位。默认为512^2行。

data_page_size

数据页的大小，以字节为单位。默认为1024^2字节。

use_pyarrow

使用C++的parquet实现与Rust的parquet实现进行比较。 目前C++支持更多的功能。

pyarrow_options

传递给pyarrow.parquet.write_table的参数。

如果你在这里传递partition_cols，数据集将使用pyarrow.parquet.write_to_dataset进行写入。 partition_cols参数会导致数据集被写入到一个目录中。 类似于Spark的分区数据集。

partition_by

用于分区的列。如果指定了此参数，将写入一个分区数据集。此参数被视为不稳定，可能会发生变化。

partition_chunk_size_bytes

写入时单个分区内拆分DataFrame的近似大小。请注意，这是根据DataFrame在内存中的大小计算的 - 输出文件的大小可能会根据文件格式/压缩方式而有所不同。

storage_options

指示如何连接到云提供商的选项。

目前支持的云提供商有AWS、GCP和Azure。 查看支持的密钥请点击这里：

  • aws

  • gcp

  • azure

  • Hugging Face (hf://): 接受在 token 参数下的 API 密钥：{'token': '...'}，或者通过设置 HF_TOKEN 环境变量。

如果未提供storage_options，Polars将尝试从环境变量中推断信息。

credential_provider

提供一个可以被调用的函数来提供云存储凭证。该函数预期返回一个包含凭证键的字典以及一个可选的凭证过期时间。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

retries

如果访问云实例失败，重试次数。

示例

>>> import pathlib
>>>
>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> path: pathlib.Path = dirpath / "new_file.parquet"
>>> df.write_parquet(path)

我们可以使用pyarrow并将use_pyarrow_write_to_dataset设置为True来写入分区数据集。以下示例将第一行写入../watermark=1/.parquet，其他行写入../watermark=2/.parquet。

>>> df = pl.DataFrame({"a": [1, 2, 3], "watermark": [1, 2, 2]})
>>> path: pathlib.Path = dirpath / "partitioned_object"
>>> df.write_parquet(
...     path,
...     use_pyarrow=True,
...     pyarrow_options={"partition_cols": ["watermark"]},
... )