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: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
    metadata: ParquetMetadata | None = None,
    arrow_schema: ArrowSchemaExportable | None = None,
    mkdir: bool = False,
) → None

Записать в файл Apache Parquet.

Параметры:

file

Путь к файлу или объект, подобный файлу и доступный для записи, в который будет записан результат. При записи секционированного набора данных здесь должен быть указан путь к каталогу.

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

Выберите «zstd» для хорошего сжатия. Выберите «lz4» для быстрого сжатия и распаковки. Выберите «snappy», если при работе со старыми средствами чтения Parquet важна обратная совместимость.

compression_level

Уровень сжатия. Чем выше уровень сжатия, тем меньше файлы на диске.

• «gzip»: мин. уровень: 0, макс. уровень: 9, по умолчанию: 6.
• «brotli»: мин. уровень: 0, макс. уровень: 11, по умолчанию: 1.
• «zstd»: мин. уровень: 1, макс. уровень: 22, по умолчанию: 3.

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

Использовать реализацию Parquet на C++ из PyArrow вместо собственной реализации Polars на Rust. Это может быть полезно, если требуются определённые возможности PyArrow через pyarrow_options. При включении этой опции некоторые параметры не поддерживаются (например, statistics="full", metadata, mkdir).

pyarrow_options

Аргументы, передаваемые в pyarrow.parquet.write_table.

Если передать сюда partition_cols, набор данных будет записан с использованием pyarrow.parquet.write_to_dataset. Параметр partition_cols приводит к записи набора данных в каталог. Это похоже на секционированные наборы данных Spark. Для встроенной записи секционированных данных рассмотрите возможность использования partition_by.

partition_by

Столбец или столбцы, по которым нужно выполнить секционирование. Если указать этот параметр, будет записан секционированный набор данных. Этот параметр считается нестабильным и может измениться.

partition_chunk_size_bytes

Приблизительный размер для разбиения DataFrame на части в пределах одного раздела при записи. Обратите внимание: размер вычисляется по объёму DataFrame в памяти; размер выходного файла может отличаться в зависимости от формата файла и сжатия.

storage_options

Параметры, определяющие способ подключения к облачному провайдеру.

В настоящее время поддерживаются облачные провайдеры AWS, GCP и Azure. Список поддерживаемых ключей см. здесь:

• aws
• gcp
• azure
• Hugging Face (hf://): принимает ключ API в параметре token: {'token': '...'} или через переменную окружения HF_TOKEN.

Если storage_options не указан, Polars попытается получить необходимые сведения из переменных окружения.

credential_provider

Функция, которую можно вызвать для получения учётных данных облачного хранилища. Функция должна возвращать словарь с ключами учётных данных и необязательным временем истечения срока их действия.

Предупреждение

Эта функциональность считается нестабильной. Она может быть изменена в любой момент без того, чтобы это считалось нарушением обратной совместимости.

retries

Количество повторных попыток при сбое доступа к облачному экземпляру.

Устарело с версии 1.37.1: Вместо этого передайте {“max_retries”: n} через storage_options.

metadata

Словарь или функция обратного вызова для добавления пар «ключ — значение» в метаданные Parquet на уровне файла.

Предупреждение

Эта функциональность считается экспериментальной. Она может быть удалена или изменена в любой момент без того, чтобы это считалось нарушением обратной совместимости.

arrow_schema

Пользовательская схема Arrow для записи в файл. Это позволяет задать пользовательскую схему и метаданные на уровне полей. Имена и типы данных должны совпадать.

Предупреждение

Эта функциональность считается нестабильной. Она может быть изменена в любой момент без того, чтобы это считалось нарушением обратной совместимости.

mkdir: bool

Рекурсивно создать все каталоги в указанном пути.

Предупреждение

Эта функциональность считается нестабильной. Она может быть изменена в любой момент без того, чтобы это считалось нарушением обратной совместимости.

Примеры

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

Можно записывать секционированные наборы данных. В следующем примере первая строка будет записана в ../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,
...     partition_by=["watermark"],
... )