polars.DataFrame.match_to_schema

DataFrame.match_to_schema(
    schema: SchemaDict | Schema,
    *,
    missing_columns: Literal['insert',
    'raise'] | Mapping[str,
    Literal['insert',
    'raise'] | Expr] = 'raise',
    missing_struct_fields: Literal['insert',
    'raise'] | Mapping[str,
    Literal['insert',
    'raise']] = 'raise',
    extra_columns: Literal['ignore',
    'raise'] = 'raise',
    extra_struct_fields: Literal['ignore',
    'raise'] | Mapping[str,
    Literal['ignore',
    'raise']] = 'raise',
    integer_cast: Literal['upcast',
    'forbid'] | Mapping[str,
    Literal['upcast',
    'forbid']] = 'forbid',
    float_cast: Literal['upcast',
    'forbid'] | Mapping[str,
    Literal['upcast',
    'forbid']] = 'forbid',
) → DataFrame

Сопоставляет схему LazyFrame с заданной схемой или изменяет её.

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

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

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

Параметры:

schema

Целевая схема, с которой нужно сопоставить текущую схему или к которой нужно её привести.

missing_columns

Вызывает ошибку или добавляет отсутствующие во входных данных столбцы в соответствии с schema.

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

missing_struct_fields

Вызывает ошибку или добавляет отсутствующие во входных данных поля структуры в соответствии с schema.

extra_columns

Вызывает ошибку или игнорирует лишние столбцы во входных данных в соответствии с schema.

extra_struct_fields

Вызывает ошибку или игнорирует лишние поля структуры во входных данных в соответствии с schema.

integer_cast

Запрещает расширение типа целочисленных столбцов во входных данных до типа соответствующего столбца в schema.

float_cast

Запрещает расширение типа столбцов с плавающей точкой во входных данных до типа соответствующего столбца в schema.

Примеры

Проверка соответствия схемы

>>> df = pl.DataFrame({"a": [1, 2, 3], "b": ["A", "B", "C"]})
>>> df.match_to_schema({"a": pl.Int64, "b": pl.String})
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ str │
╞═════╪═════╡
│ 1   ┆ A   │
│ 2   ┆ B   │
│ 3   ┆ C   │
└─────┴─────┘
>>> df.match_to_schema({"a": pl.Int64})  
polars.exceptions.SchemaError: extra columns in `match_to_schema`: "b"

Добавление отсутствующих столбцов

>>> (
...     pl.DataFrame({"a": [1, 2, 3]}).match_to_schema(
...         {"a": pl.Int64, "b": pl.String},
...         missing_columns="insert",
...     )
... )
shape: (3, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ str  │
╞═════╪══════╡
│ 1   ┆ null │
│ 2   ┆ null │
│ 3   ┆ null │
└─────┴──────┘
>>> (
...     pl.DataFrame({"a": [1, 2, 3]}).match_to_schema(
...         {"a": pl.Int64, "b": pl.String},
...         missing_columns={"b": pl.col.a.cast(pl.String)},
...     )
... )
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ str │
╞═════╪═════╡
│ 1   ┆ 1   │
│ 2   ┆ 2   │
│ 3   ┆ 3   │
└─────┴─────┘

Удаление лишних столбцов

>>> (
...     pl.DataFrame({"a": [1, 2, 3], "b": ["A", "B", "C"]}).match_to_schema(
...         {"a": pl.Int64},
...         extra_columns="ignore",
...     )
... )
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
└─────┘

Расширение типов целых чисел и чисел с плавающей точкой

>>> (
...     pl.DataFrame(
...         {"a": [1, 2, 3], "b": [1.0, 2.0, 3.0]},
...         schema={"a": pl.Int32, "b": pl.Float32},
...     ).match_to_schema(
...         {"a": pl.Int64, "b": pl.Float64},
...         integer_cast="upcast",
...         float_cast="upcast",
...     )
... )
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ f64 │
╞═════╪═════╡
│ 1   ┆ 1.0 │
│ 2   ┆ 2.0 │
│ 3   ┆ 3.0 │
└─────┴─────┘