polars.DataFrame.map_rows

DataFrame.map_rows(
    function: Callable[[tuple[Any,
    ...]],
    Any],
    return_dtype: PolarsDataType | None = None,
    *,
    inference_size: int = 256,
) → DataFrame

Применяет пользовательскую функцию (UDF) к строкам DataFrame.

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

Этот метод намного медленнее, чем API нативных выражений. Используйте его, только если не можете реализовать логику иным способом.

UDF получает каждую строку в виде кортежа значений: udf(row).

Реализация логики с помощью функции Python почти всегда значительно медленнее и требует больше памяти, чем реализация той же логики с помощью API нативных выражений, поскольку:

• Движок нативных выражений работает на Rust; UDF выполняются на Python.
• Использование UDF на Python приводит к загрузке DataFrame в память.
• Нативные выражения Polars можно выполнять параллельно (UDF, как правило, нельзя).
• Нативные выражения Polars можно оптимизировать логически (UDF — нельзя).

По возможности настоятельно рекомендуется отдавать предпочтение API нативных выражений для достижения наилучшей производительности.

Параметры:

function

Пользовательская функция или лямбда-функция.

return_dtype

Тип результата операции. Если он не указан, Polars пытается определить его автоматически.

inference_size

Используется только в том случае, если пользовательская функция возвращает строки. Для определения схемы результата используются первые n строк.

Примечания

• Метод map_rows на уровне фрейма не может отслеживать имена столбцов (поскольку UDF — это чёрный ящик, который может произвольно удалять, переставлять, преобразовывать или добавлять столбцы); если вы хотите применить UDF с сохранением имён столбцов, используйте синтаксис map_elements на уровне выражения.
• Если ваша функция требует значительных ресурсов и вы не хотите, чтобы она вызывалась более одного раза для заданных входных данных, рассмотрите возможность применения к ней декоратора @lru_cache. Если ваши данные подходят для этого, можно добиться значительного ускорения.

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3], "bar": [-1, 5, 8]})

Вернуть DataFrame, преобразовав каждую строку в кортеж:

>>> df.map_rows(lambda t: (t[0] * 2, t[1] * 3))
shape: (3, 2)
┌──────────┬──────────┐
│ column_0 ┆ column_1 │
│ ---      ┆ ---      │
│ i64      ┆ i64      │
╞══════════╪══════════╡
│ 2        ┆ -3       │
│ 4        ┆ 15       │
│ 6        ┆ 24       │
└──────────┴──────────┘

Однако гораздо лучше реализовать это с помощью нативного выражения:

>>> df.select(
...     pl.col("foo") * 2,
...     pl.col("bar") * 3,
... )  

Вернуть DataFrame с одним столбцом, преобразовав каждую строку в скалярное значение:

>>> df.map_rows(lambda t: t[0] * 2 + t[1])
shape: (3, 1)
┌─────┐
│ map │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 9   │
│ 14  │
└─────┘

В этом случае лучше использовать следующее нативное выражение:

>>> df.select(pl.col("foo") * 2 + pl.col("bar"))