polars.read_ndjson

polars.read_ndjson(
    source: str | Path | IO[str] | IO[bytes] | bytes | list[str] | list[Path] | list[IO[str]] | list[IO[bytes]],
    *,
    schema: SchemaDefinition | None = None,
    schema_overrides: SchemaDefinition | None = None,
    infer_schema_length: int | None = 100,
    batch_size: int | None = 1024,
    n_rows: int | None = None,
    low_memory: bool = False,
    rechunk: bool | None = None,
    row_index_name: str | None = None,
    row_index_offset: int = 0,
    ignore_errors: bool = False,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
    file_cache_ttl: int | None = None,
    include_file_paths: str | None = None,
) → DataFrame

Чтение данных в DataFrame из файла JSON с разделителями в виде символов новой строки.

Параметры:

source

Путь к файлу или файловоподобный объект (под «файловоподобным объектом» подразумеваются объекты, у которых есть метод read(), например дескриптор файла, созданный встроенной функцией open, или экземпляр BytesIO). Для файловоподобных объектов позиция в потоке после чтения может быть обновлена некорректно.

schemaSequence of str, (str,DataType) pairs, or a {str:DataType,} dict

Схему DataFrame можно задать несколькими способами:

• В виде словаря пар {имя:тип}; если тип равен None, он будет определен автоматически.
• В виде списка имен столбцов; в этом случае типы определяются автоматически.
• В виде списка пар (имя,тип); это эквивалентно форме словаря.

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

schema_overridesdict, default None

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

infer_schema_length

Максимальное количество строк для сканирования при определении схемы. Если задано значение None, может быть просканирован весь набор данных (это медленно).

batch_size

Количество строк для чтения в каждом пакете.

n_rows

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

low_memory

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

rechunk

Перераспределить данные в непрерывную область памяти после разбора всех фрагментов/файлов.

Устарело с версии 1.43.2: Вызовите rechunk для возвращенного DataFrame.

row_index_name

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

row_index_offset

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

ignore_errors

Возвращать Null, если разбор завершается ошибкой из-за несовпадения схем.

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.

file_cache_ttl

Время хранения загруженных облачных файлов с момента последнего доступа к ним, в секундах. Если значение не задано, используется переменная окружения POLARS_FILE_CACHE_TTL (по умолчанию — 1 час).

Устарело с версии 1.39.0: Кэш файлов больше не поддерживается.

include_file_paths

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

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

Вызов read_ndjson().lazy() считается антипаттерном, поскольку заставляет Polars материализовать весь файл ndjson и не позволяет передавать оптимизации в средство чтения. Поэтому всегда предпочитайте scan_ndjson, если хотите работать с LazyFrame s.

См. также

scan_ndjson

Ленивое чтение из файла NDJSON или нескольких файлов с помощью шаблонов glob.

Примеры

>>> from io import StringIO
>>> json_str = '{"foo":1,"bar":6}\n{"foo":2,"bar":7}\n{"foo":3,"bar":8}\n'
>>> pl.read_ndjson(StringIO(json_str))
shape: (3, 2)
┌─────┬─────┐
│ foo ┆ bar │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 6   │
│ 2   ┆ 7   │
│ 3   ┆ 8   │
└─────┴─────┘