polars.LazyFrame.sink_ndjson

LazyFrame.sink_ndjson(
    path: str | Path | IO[bytes] | IO[str] | PartitionBy,
    *,
    compression: Literal['uncompressed',
    'gzip',
    'zstd'] = 'uncompressed',
    compression_level: int | None = None,
    check_extension: bool = True,
    maintain_order: bool = True,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
    sync_on_close: SyncOnCloseMethod | None = None,
    mkdir: bool = False,
    lazy: bool = False,
    engine: EngineType = 'auto',
    optimizations: QueryOptFlags = (,
), ) → LazyFrame | None

Выполняет запрос в потоковом режиме и записывает результат в файл NDJSON.

Это позволяет записывать на диск потоковые результаты, размер которых превышает объём оперативной памяти.

движок:ПотоковыйРаспределённый

Параметры:

path

Путь к файлу, в который следует записать данные.

compression

Формат сжатия.

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

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

compression_level

Уровень сжатия: обычно от 0 до 9 или None, чтобы позволить движку выбрать его самостоятельно.

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

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

check_extension

Проверять ли, соответствует ли имя файла настройкам сжатия. Будет вызвана ошибка, если для параметра сжатия задано значение ‘uncompressed’, а имя файла заканчивается на одно из значений (“.gz”, “.zst”, “.zstd”), или если compression != ‘uncompressed’, а у файла несовместимое расширение. Применяется только в том случае, если файл задан путём.

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

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

maintain_order

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

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

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

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.

sync_on_close: { None, ‘data’, ‘all’ }

Синхронизировать данные с диском перед закрытием файла.

• None не выполняет синхронизацию.
• data синхронизирует содержимое файла.
• all синхронизирует содержимое файла и метаданные.

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

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

mkdir: bool

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

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

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

lazy: bool

Ожидать вызова collect перед началом выполнения.

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

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

engine

Выбрать движок для обработки запроса (по умолчанию "auto"). Также можно передать экземпляр Engine. Поддерживаются следующие названия движков:

• "auto": использовать движок, заданный с помощью Config.set_engine_affinity или переменной окружения POLARS_ENGINE_AFFINITY; если значение не задано, использовать "streaming".
• "in-memory": перед записью использовать движок обработки в памяти; это движок по умолчанию.
• "streaming": использовать потоковый движок, который обрабатывает запросы пакетами, снижая нагрузку на память и часто превосходя по производительности движок обработки в памяти. Вскоре он станет движком Polars по умолчанию.
• "gpu": использовать движок CUDA для GPU (требуется графический процессор Nvidia и cudf-polars). Для более точной настройки передайте объект GPUEngine.

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

optimizations

Этапы оптимизации, выполняемые при оптимизации запроса.

Не влияет на результат, если для lazy задано значение True.

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

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

Возвращает:

DataFrame

См. также

PartitionBy

Примеры

>>> lf = pl.scan_csv("/path/to/my_larger_than_ram_file.csv")  
>>> lf.sink_ndjson("out.ndjson")  

Запись в объект BytesIO.

>>> import io
>>> buf = io.BytesIO()  
>>> pl.LazyFrame({"x": [1, 2, 1]}).sink_ndjson(buf)  

Разбиение на разделы в стиле Hive:

>>> pl.LazyFrame({"x": [1, 2, 1], "y": [3, 4, 5]}).sink_ndjson(
...     pl.PartitionBy("./out/", key="x"),
...     mkdir=True
... )