polars.scan_iceberg

polars.scan_iceberg(
    source: str | pyiceberg.table.Table,
    *,
    snapshot_id: int | None = None,
    storage_options: StorageOptionsDict | None = None,
    catalog: pyiceberg.catalog.Catalog | polars.io.iceberg.IcebergCatalogConfig | None = None,
    reader_override: Literal['native',
    'pyiceberg'] | None = None,
    use_metadata_statistics: bool = True,
    fast_deletion_count: bool | None = None,
    use_pyiceberg_filter: bool = True,
) → LazyFrame

Лениво считывает данные из таблицы Apache Iceberg.

Параметры:

source

Таблица PyIceberg, строка-идентификатор «namespace.table_name» или абсолютный путь к метаданным.

snapshot_id

Идентификатор снимка, из которого нужно считывать данные.

storage_options

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

Дополнительная информация доступна здесь.

catalog

Каталог PyIceberg, из которого загружается таблица, если переданный target был именем таблицы.

reader_override

Переопределяет средство чтения, используемое для считывания данных.

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

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

Обратите внимание: этот параметр не должен требоваться вне тестирования, поскольку polars по умолчанию автоматически выбирает оптимальное средство чтения.

Доступные параметры:

• native: используется встроенное средство чтения polars. Это позволяет применять дополнительные оптимизации для повышения производительности.
• pyiceberg: используется PyIceberg, который может поддерживать больше возможностей.

use_metadata_statistics

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

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

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

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

Если запрошено количество строк (например, scan_iceberg().select(pl.len())), этот параметр позволяет получить количество непосредственно из метаданных Iceberg. Однако для наборов данных, содержащих файлы позиционного удаления, для этого также необходимо включить fast_deletion_count.

fast_deletion_count

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

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

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

use_pyiceberg_filter

Преобразует фильтр и, если возможно, передаёт его в PyIceberg.

Возвращает:

LazyFrame

Примеры

Создаёт сканирование таблицы Iceberg из локальной файловой системы или объектного хранилища.

>>> table_path = "file:/path/to/iceberg-table/metadata.json"
>>> pl.scan_iceberg(table_path).collect()  

Создаёт сканирование таблицы Iceberg из S3. Список поддерживаемых параметров хранения для S3 см. здесь.

>>> table_path = "s3://bucket/path/to/iceberg-table/metadata.json"
>>> storage_options = {
...     "s3.region": "eu-central-1",
...     "s3.access-key-id": "THE_AWS_ACCESS_KEY_ID",
...     "s3.secret-access-key": "THE_AWS_SECRET_ACCESS_KEY",
... }
>>> pl.scan_iceberg(
...     table_path, storage_options=storage_options
... ).collect()  

Создаёт сканирование таблицы Iceberg из Azure. Поддерживаемые параметры для Azure доступны здесь.

Поддерживаются следующие типы путей к таблицам:

• az://<container>/<path>/metadata.json
• adl://<container>/<path>/metadata.json
• abfs[s]://<container>/<path>/metadata.json

>>> table_path = "az://container/path/to/iceberg-table/metadata.json"
>>> storage_options = {
...     "adlfs.account-name": "AZURE_STORAGE_ACCOUNT_NAME",
...     "adlfs.account-key": "AZURE_STORAGE_ACCOUNT_KEY",
... }
>>> pl.scan_iceberg(
...     table_path, storage_options=storage_options
... ).collect()  

Создаёт сканирование таблицы Iceberg из Google Cloud Storage. Поддерживаемые параметры для GCS доступны здесь.

>>> table_path = "s3://bucket/path/to/iceberg-table/metadata.json"
>>> storage_options = {
...     "gcs.project-id": "my-gcp-project",
...     "gcs.oauth.token": "ya29.dr.AfM...",
... }
>>> pl.scan_iceberg(
...     table_path, storage_options=storage_options
... ).collect()  

Создаёт сканирование таблицы Iceberg с дополнительными параметрами. В примере ниже используется параметр without_files, который загружает таблицу без сведений об отслеживании файлов.

>>> table_path = "/path/to/iceberg-table/metadata.json"
>>> storage_options = {"py-io-impl": "pyiceberg.io.fsspec.FsspecFileIO"}
>>> pl.scan_iceberg(
...     table_path, storage_options=storage_options
... ).collect()  

Создаёт сканирование таблицы Iceberg с использованием указанного идентификатора снимка.

>>> table_path = "/path/to/iceberg-table/metadata.json"
>>> snapshot_id = 7051579356916758811
>>> pl.scan_iceberg(table_path, snapshot_id=snapshot_id).collect()