polars.scan_parquet

polars.scan_parquet(
    source: FileSource,
    *,
    n_rows: int | None = None,
    row_index_name: str | None = None,
    row_index_offset: int = 0,
    parallel: ParallelStrategy = 'auto',
    use_statistics: bool = True,
    hive_partitioning: bool | None = None,
    glob: bool = True,
    hidden_file_prefix: str | Sequence[str] | None = None,
    schema: SchemaDict | None = None,
    hive_schema: SchemaDict | None = None,
    try_parse_hive_dates: bool = True,
    rechunk: bool | None = None,
    low_memory: bool = False,
    cache: bool = True,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
    include_file_paths: str | None = None,
    missing_columns: Literal['insert',
    'raise'] = 'raise',
    allow_missing_columns: bool | None = None,
    extra_columns: Literal['ignore',
    'raise'] = 'raise',
    cast_options: ScanCastOptions | None = None,
    _column_mapping: ColumnMapping | None = None,
    _default_values: DefaultFieldValues | None = None,
    _deletion_files: DeletionFiles | None = None,
    _table_statistics: DataFrame | None = None,
    _row_count: tuple[int,
    int] | None = None,
) → LazyFrame

Лениво считывает локальный файл Parquet или файл, размещённый в облаке (или несколько файлов).

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

Изменено в версии 0.20.4: * Параметр row_count_name переименован в row_index_name. * Параметр row_count_offset переименован в row_index_offset.

Изменено в версии 1.30.0: * Параметр allow_missing_columns устарел; вместо него следует использовать missing_columns.

Параметры:

source

Путь или пути к файлу или каталогу. Для аутентификации при сканировании расположений в облаке см. параметр storage_options.

n_rows

Прекратить чтение файла Parquet после считывания n_rows.

row_index_name

Если значение не None, в DataFrame будет добавлен столбец с индексами строк и указанным именем.

row_index_offset

Смещение, с которого начинается столбец с индексами строк (используется, только если задано имя).

parallel{‘auto’, ‘columns’, ‘row_groups’, ‘prefiltered’, ‘none’}

Определяет направление и стратегию распараллеливания. Значение ‘auto’ позволяет автоматически определить оптимальное направление.

Стратегия prefiltered сначала параллельно вычисляет переданные предикаты и определяет маску строк, которые нужно прочитать. Затем распараллеливает обработку по столбцам и группам строк, отфильтровывая строки, которые не требуется считывать. Это может значительно ускорить обработку больших файлов (то есть содержащих много групп строк), если предикат фильтрует сгруппированные строки или отбирает большую часть строк. В остальных случаях prefiltered может замедлить сканирование по сравнению с другими стратегиями.

Если предикат не задан, настройка prefiltered переключается на auto.

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

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

use_statistics

Использовать статистику Parquet, чтобы определять, можно ли пропускать страницы при чтении.

hive_partitioning

Выводить статистику и схему из URL с разбиением на разделы Hive и использовать их для сокращения объёма чтения.

glob

Разворачивать путь с использованием правил glob.

hidden_file_prefix

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

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

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

schema

Задать типы данных столбцов. Типы данных должны соответствовать типам данных в файле или файлах. Если заданы дополнительные столбцы, отсутствующие в файле или файлах, рассмотрите возможность также передать missing_columns='insert'.

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

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

hive_schema

Имена и типы данных столбцов, по которым разделены данные. Если задано значение None (по умолчанию), схема разделов Hive выводится автоматически.

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

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

try_parse_hive_dates

Пробовать ли разбирать значения Hive как типы date/datetime.

rechunk

При чтении нескольких файлов с помощью шаблона glob перестроить итоговый DataFrame в непрерывные блоки памяти.

Устарело с версии 1.43.2: Сначала соберите данные в DataFrame, затем вызовите rechunk для возвращённого DataFrame.

low_memory

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

cache

Кэшировать результат после чтения.

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.

include_file_paths

Добавить путь к исходному файлу или файлам в столбец с указанным именем.

missing_columns

Настройка поведения при отсутствии в данных столбцов, указанных в схеме:

• insert: вставляет отсутствующие столбцы, используя NULL в качестве значений строк.
• raise: вызывает ошибку.

allow_missing_columns

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

Устарело с версии 1.30.0: Используйте параметр missing_columns и передайте одно из значений ('insert', 'raise').

extra_columns

Настройка поведения при обнаружении в данных дополнительных столбцов, не указанных в схеме:

• ignore: игнорирует их без уведомления.
• raise: вызывает ошибку.

cast_options

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

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

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

См. также

read_parquet

scan_pyarrow_dataset

Примеры

Сканирование локального файла Parquet.

>>> pl.scan_parquet("path/to/file.parquet")  

Сканирование файла в AWS S3.

>>> source = "s3://bucket/*.parquet"
>>> pl.scan_parquet(source)  
>>> storage_options = {
...     "aws_access_key_id": "<secret>",
...     "aws_secret_access_key": "<secret>",
...     "aws_region": "us-east-1",
... }
>>> pl.scan_parquet(source, storage_options=storage_options)