polars.LazyFrame.match_to_schema

LazyFrame.match_to_schema(
    schema: SchemaDict | Schema,
    *,
    missing_columns: Literal['insert',
    'raise'] | Mapping[str,
    Literal['insert',
    'raise'] | Expr] | 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',
) → LazyFrame

Сопоставить схему 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.

Примеры

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

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

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

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

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

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

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

>>> (
...     pl.LazyFrame(
...         {"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",
...     )
...     .collect()
... )
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ f64 │
╞═════╪═════╡
│ 1   ┆ 1.0 │
│ 2   ┆ 2.0 │
│ 3   ┆ 3.0 │
└─────┴─────┘