polars.LazyFrame.sink_csv

LazyFrame.sink_csv(
    path: str | Path | IO[bytes] | IO[str] | PartitionBy,
    *,
    include_bom: bool = False,
    compression: Literal['uncompressed',
    'gzip',
    'zstd'] = 'uncompressed',
    compression_level: int | None = None,
    check_extension: bool = True,
    include_header: bool = True,
    separator: str = ',',
    line_terminator: str = '\n',
    quote_char: str = '"',
    batch_size: int = 1024,
    datetime_format: str | None = None,
    date_format: str | None = None,
    time_format: str | None = None,
    float_scientific: bool | None = None,
    float_precision: int | None = None,
    decimal_comma: bool = False,
    null_value: str | None = None,
    quote_style: CsvQuoteStyle | None = None,
    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

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

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

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

Параметры:

path

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

include_bom

Указывает, следует ли включать BOM UTF-8 в выходные данные CSV.

compression

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

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

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

compression_level

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

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

check_extension

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

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

include_header

Указывает, следует ли включать заголовок в выходные данные CSV.

separator

Разделитель полей CSV.

line_terminator

Строка, используемая для завершения каждой строки.

quote_char

Байт, используемый в качестве символа кавычек.

batch_size

Количество строк, обрабатываемых каждым потоком.

datetime_format

Строка формата со спецификаторами, определенными в крейте Rust chrono. Если формат не задан, точность дробной части секунды по умолчанию определяется по максимальной единице времени, найденной в столбцах Datetime кадра (если такие есть).

date_format

Строка формата со спецификаторами, определенными в крейте Rust chrono.

time_format

Строка формата со спецификаторами, определенными в крейте Rust chrono.

float_scientific

Указывает, следует ли всегда (true), никогда (false) или автоматически (None) использовать научную запись для типов данных с плавающей точкой.

float_precision

Количество десятичных знаков для записи; применяется к обоим типам данных с плавающей точкой.

decimal_comma

Использовать запятую вместо точки в качестве десятичного разделителя. При необходимости числа с плавающей точкой будут заключаться в кавычки; чтобы переопределить это поведение, задайте разделитель полей.

null_value

Строка, представляющая нулевые значения (по умолчанию — пустая строка).

quote_style{‘necessary’, ‘always’, ‘non_numeric’, ‘never’}

Определяет используемую стратегию заключения в кавычки.

necessary (по умолчанию): заключает поля в кавычки только при необходимости. Это необходимо, если поля содержат кавычку, разделитель или символ завершения записи. Кавычки также нужны при записи пустой записи (которую невозможно отличить от записи с одним пустым полем). Это стратегия по умолчанию.
always: заключает в кавычки каждое поле. Всегда.
never: никогда не заключает поля в кавычки, даже если в результате данные CSV окажутся некорректными (например, если строки с разделителем не заключены в кавычки).
non_numeric: заключает в кавычки все поля, не являющиеся числовыми. То есть при записи поля, которое не разбирается как допустимое число с плавающей точкой или целое число, будут использоваться кавычки, даже если они не являются строго необходимыми.

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_csv("out.csv")

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

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

Разделение на секции в стиле секционирования Hive:

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

© 2020 Ritchie Vink
© 2022 Polars contributors
Licensed under the MIT License.
https://docs.pola.rs/api/python/stable/reference/api/polars.LazyFrame.sink_csv.html