polars.json_normalize

polars.json_normalize(
    data: dict[Any,
    Any] | Sequence[dict[Any,
    Any] | Any],
    *,
    separator: str = '.',
    max_level: int | None = None,
    schema: Schema | None = None,
    strict: bool = True,
    infer_schema_length: int | None = 100,
    encoder: JSONEncoder | None = None,
) → DataFrame

Преобразует десериализованные полуструктурированные данные JSON в плоскую таблицу.

Объекты-словари, которые не будут развёрнуты/нормализованы, кодируются в виде строк JSON. В отличие от аналога в pandas, эта функция не кодирует словари как объекты ни на одном уровне.

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

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

Параметры:

data

Десериализованные объекты JSON.

separator

Вложенные записи будут формировать имена, разделённые с помощью sep. Например, для separator=".", {"foo": {"bar": 0}} -> foo.bar.

max_level

Максимальное число уровней (глубина словаря) для нормализации. Если указано None, нормализуются все уровни.

schema

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

strict

Определяет, должна ли Polars строго соблюдать правила при создании DataFrame.

infer_schema_length

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

encoder

Пользовательская функция кодирования JSON; если она не задана, используется json.dumps.

Примеры

>>> data = [
...     {
...         "id": 1,
...         "name": "Cole Volk",
...         "fitness": {"height": 180, "weight": 85},
...     },
...     {
...         "id": 2,
...         "name": "Faye Raker",
...         "fitness": {"height": 155, "weight": 58},
...     },
...     {
...         "name": "Mark Reg",
...         "fitness": {"height": 170, "weight": 78},
...     },
... ]
>>> pl.json_normalize(data, max_level=1)
shape: (3, 4)
┌──────┬────────────┬────────────────┬────────────────┐
│ id   ┆ name       ┆ fitness.height ┆ fitness.weight │
│ ---  ┆ ---        ┆ ---            ┆ ---            │
│ i64  ┆ str        ┆ i64            ┆ i64            │
╞══════╪════════════╪════════════════╪════════════════╡
│ 1    ┆ Cole Volk  ┆ 180            ┆ 85             │
│ 2    ┆ Faye Raker ┆ 155            ┆ 58             │
│ null ┆ Mark Reg   ┆ 170            ┆ 78             │
└──────┴────────────┴────────────────┴────────────────┘

Нормализация до заданной глубины с использованием пользовательского кодировщика JSON (обратите внимание, что orjson.dumps кодирует данные в байты, а не в строки).

>>> import orjson
>>> pl.json_normalize(data, max_level=0, encoder=orjson.dumps)
shape: (3, 3)
┌──────┬────────────┬───────────────────────────────┐
│ id   ┆ name       ┆ fitness                       │
│ ---  ┆ ---        ┆ ---                           │
│ i64  ┆ str        ┆ binary                        │
╞══════╪════════════╪═══════════════════════════════╡
│ 1    ┆ Cole Volk  ┆ b"{"height":180,"weight":85}" │
│ 2    ┆ Faye Raker ┆ b"{"height":155,"weight":58}" │
│ null ┆ Mark Reg   ┆ b"{"height":170,"weight":78}" │
└──────┴────────────┴───────────────────────────────┘