polars.DataFrame.write_delta

DataFrame.write_delta(
    target: str | Path | deltalake.DeltaTable,
    *,
    mode: Literal['error',
    'append',
    'overwrite',
    'ignore',
    'merge'] = 'error',
    overwrite_schema: bool | None = None,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    delta_write_options: dict[str,
    Any] | None = None,
    delta_merge_options: dict[str,
    Any] | None = None,
) → deltalake.table.TableMerger | None

Записать DataFrame в виде таблицы Delta.

Параметры:

target

URI таблицы или объект DeltaTable.

mode{‘error’, ‘append’, ‘overwrite’, ‘ignore’, ‘merge’}

Способ обработки существующих данных.

• Если указано ‘error’, вызвать ошибку, если таблица уже существует (по умолчанию).
• Если указано ‘append’, добавить новые данные.
• Если указано ‘overwrite’, заменить таблицу новыми данными.
• Если указано ‘ignore’, ничего не записывать, если таблица уже существует.
• Если указано ‘merge’, вернуть объект TableMerger для объединения данных из DataFrame с существующими данными.

overwrite_schema

Если значение True, разрешить обновление схемы таблицы.

Устарело с версии 0.20.14: Вместо этого используйте параметр delta_write_options и передайте {"schema_mode": "overwrite"}.

storage_options

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

• Список поддерживаемых параметров хранилища для S3 см. здесь.
• Список поддерживаемых параметров хранилища для GCS см. здесь.
• Список поддерживаемых параметров хранилища для Azure см. здесь.

credential_provider

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

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

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

delta_write_options

Дополнительные именованные аргументы при записи таблицы Delta Lake. Список поддерживаемых параметров записи см. здесь.

delta_merge_options

Именованные аргументы, необходимые для MERGE таблицы Delta Lake. Список поддерживаемых параметров объединения см. здесь.

Исключения:

TypeError

Если DataFrame содержит неподдерживаемые типы данных.

ArrowInvalidError

Если DataFrame содержит типы данных, которые невозможно привести к примитивному типу.

TableNotFoundError

Если таблица Delta не существует и запускается действие MERGE.

Примечания

Типы данных Polars Null и Time не поддерживаются спецификацией протокола Delta, поэтому будет вызвана ошибка TypeError. Столбцы с типом данных Categorical при записи будут преобразованы в обычные (не категориальные) строки.

Столбцы Polars всегда допускают значения null. Чтобы записать данные в таблицу Delta со столбцами, не допускающими значения null, необходимо передать пользовательскую схему pyarrow в delta_write_options. См. последний пример ниже.

Примеры

Записать DataFrame в виде таблицы Delta Lake в локальную файловую систему.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> table_path = "/path/to/delta-table/"
>>> df.write_delta(table_path)  

Добавить данные в существующую таблицу Delta Lake в локальной файловой системе. Обратите внимание, что операция завершится ошибкой, если схема новых данных не совпадает со схемой существующей таблицы.

>>> df.write_delta(table_path, mode="append")  

Перезаписать таблицу Delta Lake, создав новую версию. Если схемы новых и старых данных совпадают, указывать schema_mode необязательно.

>>> existing_table_path = "/path/to/delta-table/"
>>> df.write_delta(
...     existing_table_path,
...     mode="overwrite",
...     delta_write_options={"schema_mode": "overwrite"},
... )  

Записать DataFrame в виде таблицы Delta Lake в облачное объектное хранилище, например S3.

>>> table_path = "s3://bucket/prefix/to/delta-table/"
>>> df.write_delta(
...     table_path,
...     storage_options={
...         "AWS_REGION": "THE_AWS_REGION",
...         "AWS_ACCESS_KEY_ID": "THE_AWS_ACCESS_KEY_ID",
...         "AWS_SECRET_ACCESS_KEY": "THE_AWS_SECRET_ACCESS_KEY",
...     },
... )  

Записать DataFrame в виде таблицы Delta Lake со столбцами, не допускающими значения null.

>>> import pyarrow as pa
>>> existing_table_path = "/path/to/delta-table/"
>>> df.write_delta(
...     existing_table_path,
...     delta_write_options={
...         "schema": pa.schema([pa.field("foo", pa.int64(), nullable=False)])
...     },
... )  

Записать DataFrame в виде таблицы Delta Lake со сжатием zstd. Список всех именованных аргументов delta_write_options см. в документации deltalake здесь, а информацию о свойствах Writer — в частности, здесь.

>>> import deltalake
>>> df.write_delta(
...     table_path,
...     delta_write_options={
...         "writer_properties": deltalake.WriterProperties(compression="zstd"),
...     },
... )  

Объединить DataFrame с существующей таблицей Delta Lake. Список всех методов TableMerger см. в документации deltalake здесь.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> table_path = "/path/to/delta-table/"
>>> (
...     df.write_delta(
...         "table_path",
...         mode="merge",
...         delta_merge_options={
...             "predicate": "s.foo = t.foo",
...             "source_alias": "s",
...             "target_alias": "t",
...         },
...     )
...     .when_matched_update_all()
...     .when_not_matched_insert_all()
...     .execute()
... )