LazyFrame

На этой странице представлен обзор всех публичных методов LazyFrame.

class polars.LazyFrame(
    data: FrameInitTypes | None = None,
    schema: SchemaDefinition | None = None,
    *,
    schema_overrides: SchemaDict | None = None,
    strict: bool = True,
    orient: Orientation | None = None,
    infer_schema_length: int | None = 100,
    nan_to_null: bool = False,
    height: int | None = None,
)

Представление графа/запроса ленивых вычислений для DataFrame.

Это позволяет оптимизировать запрос целиком в дополнение к параллельному выполнению и является предпочтительным (и наиболее производительным) режимом работы polars.

Параметры:

datadict, Sequence, ndarray, Series, or pandas.DataFrame

Двумерные данные в различных форматах; входной словарь должен содержать последовательности, генераторы или range. Последовательность может содержать Series или другие последовательности.

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

Схему LazyFrame можно объявить несколькими способами:

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

Порядок элементов схемы определяет порядок столбцов во фрейме. При передаче словаря сохраняется порядок добавления элементов. Чтобы переопределить типы данных конкретных столбцов по имени, не меняя порядок столбцов, используйте schema_overrides.

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

schema_overridesdict, default None

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

Число элементов в схеме должно соответствовать размерности исходных данных, за исключением случая, когда передаётся последовательность словарей: тогда можно объявить частичную схему, чтобы исключить загрузку определённых полей.

strictbool, default True

Вызывает ошибку, если какое-либо значение data не соответствует в точности заданному или определённому типу данных для этого столбца. Если задано значение False, значения, не соответствующие типу данных, приводятся к этому типу или, если приведение невозможно, заменяются на null.

orient{‘col’, ‘row’}, default None

Определяет, следует ли интерпретировать двумерные данные как столбцы или строки. Если значение равно None, ориентация определяется по соответствию столбцов и размерности данных. Если это не позволяет однозначно определить ориентацию, используются столбцы.

infer_schema_lengthint or None

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

nan_to_nullbool, default False

Если данные получены из одного или нескольких массивов numpy, можно преобразовать входные значения np.nan в null. Для всех остальных входных данных параметр ничего не делает.

heightint or None, default None

Позволяет создавать DataFrame с нулевой шириной и заданной высотой. Если переданы данные, гарантирует, что результирующий DataFrame будет иметь эту высоту.

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

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

Примечания

Непосредственная инициализация LazyFrame(...) эквивалентна DataFrame(...).lazy().

Примеры

Создание LazyFrame непосредственно из словаря:

>>> data = {"a": [1, 2], "b": [3, 4]}
>>> lf = pl.LazyFrame(data)
>>> lf.collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

Обратите внимание, что типы данных автоматически определяются как Polars Int64:

>>> lf.collect_schema().dtypes()
[Int64, Int64]

Чтобы задать более подробную/конкретную схему фрейма, можно передать параметру schema словарь пар (имя,тип)…

>>> data = {"col1": [0, 2], "col2": [3, 7]}
>>> lf2 = pl.LazyFrame(data, schema={"col1": pl.Float32, "col2": pl.Int64})
>>> lf2.collect()
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 0.0  ┆ 3    │
│ 2.0  ┆ 7    │
└──────┴──────┘

…последовательность пар (имя,тип)…

>>> data = {"col1": [1, 2], "col2": [3, 4]}
>>> lf3 = pl.LazyFrame(data, schema=[("col1", pl.Float32), ("col2", pl.Int64)])
>>> lf3.collect()
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

…или список типизированных Series.

>>> data = [
...     pl.Series("col1", [1, 2], dtype=pl.Float32),
...     pl.Series("col2", [3, 4], dtype=pl.Int64),
... ]
>>> lf4 = pl.LazyFrame(data)
>>> lf4.collect()
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

Создание LazyFrame из массива numpy ndarray с указанием имён столбцов:

>>> import numpy as np
>>> data = np.array([(1, 2), (3, 4)], dtype=np.int64)
>>> lf5 = pl.LazyFrame(data, schema=["a", "b"], orient="col")
>>> lf5.collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

Создание LazyFrame из списка списков с заданной ориентацией по строкам:

>>> data = [[1, 2, 3], [4, 5, 6]]
>>> lf6 = pl.LazyFrame(data, schema=["a", "b", "c"], orient="row")
>>> lf6.collect()
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 2   ┆ 3   │
│ 4   ┆ 5   ┆ 6   │
└─────┴─────┴─────┘

Методы:

approx_n_unique	Приблизительный подсчёт уникальных значений.
bottom_k	Возвращает k строк с наименьшими значениями.
cache	Кэширует результат при достижении этого узла во время выполнения физического плана.
cast	Преобразует типы данных столбцов LazyFrame в указанные типы.
clear	Создаёт пустую копию текущего LazyFrame с числом строк от нуля до 'n'.
clone	Создаёт копию этого LazyFrame.
collect	Материализует этот LazyFrame в DataFrame.
collect_async	Асинхронно собирает DataFrame в пуле потоков.
collect_batches	Выполняет запрос в потоковом режиме и возвращает генератор, выдающий фрагменты данных.
collect_schema	Определяет схему этого LazyFrame.
count	Возвращает число ненулевых элементов для каждого столбца.
describe	Создаёт сводку статистических показателей LazyFrame и возвращает DataFrame.
deserialize	Считывает логический план из файла для создания LazyFrame.
drop	Удаляет столбцы из DataFrame.
drop_nans	Удаляет все строки, содержащие одно или несколько значений NaN.
drop_nulls	Удаляет все строки, содержащие одно или несколько значений null.
execute	Выполняет запрос и возвращает QueryResult.
explain	Создаёт строковое представление плана запроса.
explode	Преобразует DataFrame в длинный формат, разворачивая указанные столбцы.
fetch	Собирает небольшое число строк для отладки.
fill_nan	Заполняет значения NaN с плавающей точкой.
fill_null	Заполняет значения null указанным значением или стратегией.
filter	Фильтрует строки LazyFrame по выражению-предикату.
first	Возвращает первую строку DataFrame.
gather	Выбирает строки этого LazyFrame по указанным индексам.
gather_every	Выбирает каждую n-ю строку LazyFrame и возвращает результат в виде нового LazyFrame.
group_by	Начинает операцию группировки.
group_by_dynamic	Группирует данные по значению времени (или значению индекса типа Int32, Int64).
head	Возвращает первые n строк.
inspect	Проверяет узел графа вычислений.
interpolate	Интерполирует промежуточные значения.
join	Добавляет операцию соединения в логический план.
join_asof	Выполняет asof-соединение.
join_where	Выполняет соединение на основе одного или нескольких предикатов равенства/неравенства.
last	Возвращает последнюю строку DataFrame.
lazy	Возвращает ленивое представление, то есть сам объект.
limit	Возвращает первые n строк.
map_batches	Применяет пользовательскую функцию.
match_to_schema	Приводит схему LazyFrame к указанной схеме или изменяет её в соответствии с ней.
max	Вычисляет максимальные значения для столбцов LazyFrame.
mean	Вычисляет средние значения для столбцов LazyFrame.
median	Вычисляет медианные значения для столбцов LazyFrame.
melt	Преобразует DataFrame из широкого формата в длинный.
merge_sorted	Объединяет два отсортированных DataFrame по отсортированному ключу.
min	Вычисляет минимальные значения для столбцов LazyFrame.
null_count	Вычисляет для столбцов LazyFrame число значений null.
pipe	Предоставляет структурированный способ применения последовательности пользовательских функций (UDF).
pipe_with_schema	Позволяет изменять ленивый фрейм на этапе построения плана с учётом определённой схемы.
pivot	Создаёт сводную таблицу в стиле электронной таблицы в виде DataFrame.
profile	Профилирует LazyFrame.
quantile	Вычисляет квантиль для столбцов LazyFrame.
remote	Выполняет запрос удалённо в Polars Cloud.
remove	Удаляет строки, соответствующие заданным выражениям-предикатам.
rename	Переименовывает столбцы.
reverse	Обращает порядок строк DataFrame.
rolling	Создаёт скользящие группы на основе столбца временного или целочисленного типа.
select	Выбирает столбцы из этого LazyFrame.
select_seq	Выбирает столбцы из этого LazyFrame.
serialize	Сериализует логический план этого LazyFrame в файл или строку в формате JSON.
set_sorted	Помечает столбец как отсортированный.
shift	Сдвигает значения на указанное число индексов.
show	Показывает первые n строк.
show_graph	Показывает график плана запроса.
sink_batches	Выполняет запрос и вызывает пользовательскую функцию для каждого готового пакета данных.
sink_csv	Выполняет запрос в потоковом режиме и записывает результат в файл CSV.
sink_delta	Записывает DataFrame в виде таблицы Delta.
sink_iceberg	Записывает LazyFrame в таблицу Iceberg.
sink_ipc	Выполняет запрос в потоковом режиме и записывает результат в файл IPC.
sink_ndjson	Выполняет запрос в потоковом режиме и записывает результат в файл NDJSON.
sink_parquet	Выполняет запрос в потоковом режиме и записывает результат в файл Parquet.
slice	Возвращает срез этого DataFrame.
sort	Сортирует LazyFrame по указанным столбцам.
sql	Выполняет SQL-запрос к LazyFrame.
std	Вычисляет стандартное отклонение для столбцов LazyFrame.
sum	Вычисляет сумму значений в столбцах LazyFrame.
tail	Возвращает последние n строк.
top_k	Возвращает k строк с наибольшими значениями.
unique	Удаляет повторяющиеся строки из этого LazyFrame.
unnest	Разбивает столбцы типа struct на отдельные столбцы для каждого поля.
unpivot	Преобразует DataFrame из широкого формата в длинный.
update	Обновляет значения в этом LazyFrame значениями из other.
var	Вычисляет дисперсию для столбцов LazyFrame.
with_columns	Добавляет столбцы в этот LazyFrame.
with_columns_seq	Добавляет столбцы в этот LazyFrame.
with_context	Добавляет внешний контекст в граф вычислений.
with_row_count	Добавляет в индекс 0 столбец со счётчиком строк.
with_row_index	Добавляет индекс строк в качестве первого столбца LazyFrame.

Атрибуты:

columns	Возвращает имена столбцов.
dtypes	Возвращает типы данных столбцов.
schema	Возвращает упорядоченное соответствие имён столбцов их типам данных.
width	Возвращает число столбцов.

approx_n_unique() → LazyFrame

Приблизительный подсчёт уникальных значений.

Устарело с версии 0.20.11: Вместо этого используйте select(pl.all().approx_n_unique()).

Для оценки мощности множества используется алгоритм HyperLogLog++.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.approx_n_unique().collect()  
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ u32 ┆ u32 │
╞═════╪═════╡
│ 4   ┆ 2   │
└─────┴─────┘

bottom_k(
    k: int,
    *,
    by: IntoExpr | Iterable[IntoExpr],
    reverse: bool | Sequence[bool] = False,
) → LazyFrame

Возвращает k строк с наименьшими значениями.

Ненулевые элементы всегда имеют приоритет перед элементами null независимо от значения reverse. Порядок вывода не гарантируется; если необходимо отсортировать результат, вызовите sort() после этой функции.

движок:В памятиПотоковыйРаспределённый

Изменено в версии 1.0.0: Параметр descending переименован в reverse.

Параметры:

k

Число строк для возврата.

by

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

reverse

Рассматривает k наибольших элементов столбца или столбцов by (вместо k наименьших). Для каждого столбца можно задать отдельное значение, передав последовательность логических значений.

См. также

top_k

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [2, 1, 1, 3, 2, 1],
...     }
... )

Получение строк, содержащих 4 наименьших значения в столбце b.

>>> lf.bottom_k(4, by="b").collect()
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ b   ┆ 1   │
│ a   ┆ 1   │
│ c   ┆ 1   │
│ a   ┆ 2   │
└─────┴─────┘

Получение строк, содержащих 4 наименьших значения при сортировке по столбцам a и b.

>>> lf.bottom_k(4, by=["a", "b"]).collect()
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ a   ┆ 1   │
│ a   ┆ 2   │
│ b   ┆ 1   │
│ b   ┆ 2   │
└─────┴─────┘

cache() → LazyFrame

Кэширует результат при достижении этого узла во время выполнения физического плана.

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

движок:В памятиПотоковыйРаспределённый

cast(
    dtypes: Mapping[ColumnNameOrSelector | PolarsDataType,
    PolarsDataType | PythonDataType] | PolarsDataType | DataTypeExpr | Schema,
    *,
    strict: bool = True,
) → LazyFrame

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

движок:В памятиПотоковыйРаспределённый

Параметры:

dtypes

Соответствие имён столбцов (или селектора) типам данных либо один тип данных, к которому будут приведены все столбцы.

strict

Вызывает ошибку, если преобразование выполнить не удалось (например, из-за переполнения).

Примеры

>>> from datetime import date
>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": [date(2020, 1, 2), date(2021, 3, 4), date(2022, 5, 6)],
...     }
... )

Преобразование выбранных столбцов фрейма в указанные типы данных:

>>> lf.cast({"foo": pl.Float32, "bar": pl.UInt8}).collect()
shape: (3, 3)
┌─────┬─────┬────────────┐
│ foo ┆ bar ┆ ham        │
│ --- ┆ --- ┆ ---        │
│ f32 ┆ u8  ┆ date       │
╞═════╪═════╪════════════╡
│ 1.0 ┆ 6   ┆ 2020-01-02 │
│ 2.0 ┆ 7   ┆ 2021-03-04 │
│ 3.0 ┆ 8   ┆ 2022-05-06 │
└─────┴─────┴────────────┘

Преобразование всех столбцов фрейма, соответствующих одному типу данных (или группе типов), в другой тип данных:

>>> lf.cast({pl.Date: pl.Datetime}).collect()
shape: (3, 3)
┌─────┬─────┬─────────────────────┐
│ foo ┆ bar ┆ ham                 │
│ --- ┆ --- ┆ ---                 │
│ i64 ┆ f64 ┆ datetime[μs]        │
╞═════╪═════╪═════════════════════╡
│ 1   ┆ 6.0 ┆ 2020-01-02 00:00:00 │
│ 2   ┆ 7.0 ┆ 2021-03-04 00:00:00 │
│ 3   ┆ 8.0 ┆ 2022-05-06 00:00:00 │
└─────┴─────┴─────────────────────┘

Использование селекторов для задания столбцов, типы которых необходимо преобразовать:

>>> import polars.selectors as cs
>>> lf.cast({cs.numeric(): pl.UInt32, cs.temporal(): pl.String}).collect()
shape: (3, 3)
┌─────┬─────┬────────────┐
│ foo ┆ bar ┆ ham        │
│ --- ┆ --- ┆ ---        │
│ u32 ┆ u32 ┆ str        │
╞═════╪═════╪════════════╡
│ 1   ┆ 6   ┆ 2020-01-02 │
│ 2   ┆ 7   ┆ 2021-03-04 │
│ 3   ┆ 8   ┆ 2022-05-06 │
└─────┴─────┴────────────┘

Преобразование всех столбцов фрейма в указанный тип данных:

>>> lf.cast(pl.String).collect().to_dict(as_series=False)
{'foo': ['1', '2', '3'],
 'bar': ['6.0', '7.0', '8.0'],
 'ham': ['2020-01-02', '2021-03-04', '2022-05-06']}

clear(
    n: int = 0,
) → LazyFrame

Создаёт пустую копию текущего LazyFrame с количеством строк от нуля до «n».

Возвращает копию с идентичной схемой, но без данных.

движок:В памятиПотоковыйРаспределённый

Параметры:

n

Количество (пустых) строк, возвращаемых в очищенном фрейме.

См. также

clone

Быстрое глубокое копирование/клонирование.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [None, 2, 3, 4],
...         "b": [0.5, None, 2.5, 13],
...         "c": [True, True, False, None],
...     }
... )
>>> lf.clear().collect()
shape: (0, 3)
┌─────┬─────┬──────┐
│ a   ┆ b   ┆ c    │
│ --- ┆ --- ┆ ---  │
│ i64 ┆ f64 ┆ bool │
╞═════╪═════╪══════╡
└─────┴─────┴──────┘

>>> lf.clear(2).collect()
shape: (2, 3)
┌──────┬──────┬──────┐
│ a    ┆ b    ┆ c    │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ f64  ┆ bool │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
│ null ┆ null ┆ null │
└──────┴──────┴──────┘

clone() → LazyFrame

Создаёт копию этого LazyFrame.

Это быстрая операция, которая не копирует данные.

движок:В памятиПотоковыйРаспределённый

См. также

clear

Создаёт пустую копию текущего LazyFrame с идентичной схемой, но без данных.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [None, 2, 3, 4],
...         "b": [0.5, None, 2.5, 13],
...         "c": [True, True, False, None],
...     }
... )
>>> lf.clone()
<LazyFrame at ...>

collect(
    *,
    type_coercion: bool = True,
    predicate_pushdown: bool = True,
    projection_pushdown: bool = True,
    simplify_expression: bool = True,
    slice_pushdown: bool = True,
    comm_subplan_elim: bool = True,
    comm_subexpr_elim: bool = True,
    cluster_with_columns: bool = True,
    collapse_joins: bool = True,
    no_optimization: bool = False,
    engine: EngineType = 'auto',
    background: bool = False,
    optimizations: QueryOptFlags = (,
), **_kwargs: Any, ) → DataFrame | InProcessQuery

Материализует этот LazyFrame в DataFrame.

По умолчанию включены все оптимизации запросов. Отдельные оптимизации можно отключить, задав соответствующему параметру значение False.

Параметры:

type_coercion

Выполнять оптимизацию приведения типов.

Устарело с версии 1.30.0: Используйте параметры optimizations.

predicate_pushdown

Выполнять оптимизацию проталкивания предикатов.

Устарело с версии 1.30.0: Используйте параметры optimizations.

projection_pushdown

Выполнять оптимизацию проталкивания проекций.

Устарело с версии 1.30.0: Используйте параметры optimizations.

simplify_expression

Выполнять оптимизацию упрощения выражений.

Устарело с версии 1.30.0: Используйте параметры optimizations.

slice_pushdown

Оптимизация проталкивания срезов.

Устарело с версии 1.30.0: Используйте параметры optimizations.

comm_subplan_elim

Пытается кэшировать ветвящиеся под-планы, возникающие при соединениях таблицы с самой собой или при объединениях.

Устарело с версии 1.30.0: Используйте параметры optimizations.

comm_subexpr_elim

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

Устарело с версии 1.30.0: Используйте параметры optimizations.

cluster_with_columns

Объединять последовательные независимые вызовы with_columns

Устарело с версии 1.30.0: Используйте параметры optimizations.

collapse_joins

Преобразовывать соединение и фильтры в более быстрое соединение

Устарело с версии 1.30.0: Используйте параметры optimizations.

no_optimization

Отключить (определённые) оптимизации.

Устарело с версии 1.30.0: Используйте параметры optimizations.

engine

Выберите движок для обработки запроса (по умолчанию "auto"). Также можно передать экземпляр Engine. Поддерживаются следующие названия движков:

• "auto": использовать движок, заданный с помощью Config.set_engine_affinity или переменной окружения POLARS_ENGINE_AFFINITY; если значение не задано, использовать "in-memory" (это значение по умолчанию может измениться в будущих выпусках).
• "in-memory": использовать движок в памяти — это движок по умолчанию.
• "streaming": использовать потоковый движок, который обрабатывает запросы пакетами, снижая нагрузку на память и часто превосходя по скорости движок в памяти. Вскоре он станет движком Polars по умолчанию.
• "gpu": использовать движок CUDA GPU (требуется GPU Nvidia и cudf-polars). Для тонкой настройки (например, выбора устройства в системах с несколькими GPU) передайте объект GPUEngine.

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

Примечание

Режим GPU считается нестабильным. Не все запросы будут успешно выполняться на GPU, однако при неподдерживаемом выполнении должен происходить незаметный переход к движку по умолчанию.

Запуск с POLARS_VERBOSE=1 предоставит информацию о переходе запроса на другой движок (и его причине).

background

Запустить запрос в фоновом режиме и получить дескриптор запроса. С его помощью можно получить результат или отменить запрос.

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

Фоновый режим считается нестабильным. Он может быть изменён в любой момент без того, чтобы это считалось обратно несовместимым изменением.

optimizations

Этапы оптимизации, выполняемые при оптимизации запроса.

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

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

Возвращает:

DataFrame

См. также

explain

Вывести план запроса, выполняемый методом collect.

profile

Собрать LazyFrame и измерить время выполнения каждого узла графа вычислений.

polars.collect_all

Одновременно собрать несколько LazyFrame.

polars.Config.set_streaming_chunk_size

Задать размер потоковых пакетов.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [1, 2, 3, 4, 5, 6],
...         "c": [6, 5, 4, 3, 2, 1],
...     }
... )
>>> lf.group_by("a").agg(pl.all().sum()).collect()  
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 4   ┆ 10  │
│ b   ┆ 11  ┆ 10  │
│ c   ┆ 6   ┆ 1   │
└─────┴─────┴─────┘

Сбор в потоковом режиме

>>> lf.group_by("a").agg(pl.all().sum()).collect(
...     engine="streaming"
... )  
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 4   ┆ 10  │
│ b   ┆ 11  ┆ 10  │
│ c   ┆ 6   ┆ 1   │
└─────┴─────┴─────┘

Сбор в режиме GPU

>>> lf.group_by("a").agg(pl.all().sum()).collect(engine="gpu")  
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ b   ┆ 11  ┆ 10  │
│ a   ┆ 4   ┆ 10  │
│ c   ┆ 6   ┆ 1   │
└─────┴─────┴─────┘

С управлением используемым устройством

>>> lf.group_by("a").agg(pl.all().sum()).collect(
...     engine=pl.GPUEngine(device=1)
... )  
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ b   ┆ 11  ┆ 10  │
│ a   ┆ 4   ┆ 10  │
│ c   ┆ 6   ┆ 1   │
└─────┴─────┴─────┘

collect_async(
    *,
    gevent: bool = False,
    engine: EngineType = 'auto',
    optimizations: QueryOptFlags = (,
), ) → Awaitable[DataFrame] | _GeventDataFrameResult[DataFrame]

Асинхронно собрать DataFrame в пуле потоков.

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

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

Собирает данные в DataFrame (как collect()), но вместо непосредственного возврата DataFrame сбор планируется в пуле потоков, а этот метод возвращает управление почти мгновенно.

Это может быть полезно, если вы используете gevent или asyncio и хотите передать управление другим greenlet-задачам/задачам, пока выполняется сбор LazyFrame.

Параметры:

gevent

Возвращать оболочку для gevent.event.AsyncResult вместо Awaitable

engine

Выберите движок для обработки запроса (по умолчанию "auto"). Также можно передать экземпляр Engine. Поддерживаются следующие названия движков:

• "auto": использовать движок, заданный с помощью Config.set_engine_affinity или переменной окружения POLARS_ENGINE_AFFINITY; если значение не задано, использовать "in-memory" (это значение по умолчанию может измениться в будущих выпусках).
• "in-memory": использовать движок в памяти — это движок по умолчанию.
• "streaming": использовать потоковый движок, который обрабатывает запросы пакетами, снижая нагрузку на память и часто превосходя по скорости движок в памяти. Вскоре он станет движком Polars по умолчанию.
• "gpu": использовать движок CUDA GPU (требуется GPU Nvidia и cudf-polars). Для тонкой настройки (например, выбора устройства в системах с несколькими GPU) передайте объект GPUEngine.

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

Примечание

Движок GPU не поддерживает асинхронное выполнение и запуск в фоновом режиме. Если включён любой из этих режимов, выполнение на GPU отключается.

optimizations

Этапы оптимизации, выполняемые при оптимизации запроса.

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

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

Возвращает:

If gevent=False (default) then returns an awaitable.

If gevent=True then returns wrapper that has a

.get(block=True, timeout=None) method.

См. также

polars.collect_all

Одновременно собрать несколько LazyFrame.

polars.collect_all_async

Лениво собрать несколько LazyFrame одновременно.

Примечания

В случае ошибки set_exception используется для asyncio.Future/gevent.event.AsyncResult, и ошибка будет повторно вызвана ими.

Примеры

>>> import asyncio
>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [1, 2, 3, 4, 5, 6],
...         "c": [6, 5, 4, 3, 2, 1],
...     }
... )
>>> async def main():
...     return await (
...         lf.group_by("a", maintain_order=True)
...         .agg(pl.all().sum())
...         .collect_async()
...     )
>>> asyncio.run(main())
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 4   ┆ 10  │
│ b   ┆ 11  ┆ 10  │
│ c   ┆ 6   ┆ 1   │
└─────┴─────┴─────┘

collect_batches(
    *,
    chunk_size: int | None = None,
    maintain_order: bool = True,
    lazy: bool = False,
    engine: EngineType = 'auto',
    optimizations: QueryOptFlags = (,
), ) → _CollectBatches

Выполняет запрос в потоковом режиме и возвращает генератор, выдающий фрагменты.

Это позволяет записывать на диск потоковые результаты, размер которых превышает объём оперативной памяти.

Запрос всегда выполняется полностью, если не вызвать stop, поэтому следует вызывать next, пока не будут получены все фрагменты.

движок:Потоковый

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

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

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

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

Параметры:

chunk_size

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

maintain_order

Сохранять порядок обработки данных. Если задать False, выполнение будет немного быстрее.

lazy

Запустить запрос при первом запросе пакета.

engine

Выберите движок для обработки запроса (по умолчанию "auto"). Также можно передать экземпляр Engine. Поддерживаются следующие названия движков:

• "auto": использовать движок, заданный с помощью Config.set_engine_affinity или переменной окружения POLARS_ENGINE_AFFINITY; если значение не задано, использовать "streaming".
• "in-memory": перед записью использовать движок в памяти — это движок по умолчанию.
• "streaming": использовать потоковый движок, который обрабатывает запросы пакетами, снижая нагрузку на память и часто превосходя по скорости движок в памяти. Вскоре он станет движком Polars по умолчанию.
• "gpu": использовать движок CUDA GPU (требуется GPU Nvidia и cudf-polars). Для тонкой настройки передайте объект GPUEngine.

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

optimizations

Этапы оптимизации, выполняемые при оптимизации запроса.

Примеры

>>> lf = pl.scan_csv("/path/to/my_larger_than_ram_file.csv")  
>>> for df in lf.collect_batches():
...     print(df)  

collect_schema() → Schema

Определяет схему этого LazyFrame.

Внимание

Вычисление схемы LazyFrame может быть затратной операцией, поскольку может потребовать чтения метаданных с (медленного) дискового хранилища или выполнения сетевых запросов, если данные находятся на удалённом ресурсе.

Примеры

Определение схемы.

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.collect_schema()
Schema({'foo': Int64, 'bar': Float64, 'ham': String})

Доступ к различным свойствам схемы.

>>> schema = lf.collect_schema()
>>> schema["bar"]
Float64
>>> schema.names()
['foo', 'bar', 'ham']
>>> schema.dtypes()
[Int64, Float64, String]
>>> schema.len()
3

property columns: list[str]

Получает имена столбцов.

Возвращает:

список строк

Список, содержащий имена всех столбцов в порядке следования.

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

Чтобы определить имена столбцов LazyFrame, необходимо разрешить его схему, что может быть затратной операцией. Идиоматичный способ разрешить схему — использовать collect_schema(). Это свойство существует только для симметрии с классом DataFrame.

См. также

collect_schema

Schema.names

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... ).select("foo", "bar")
>>> lf.columns  
['foo', 'bar']

count() → LazyFrame

Возвращает количество ненулевых элементов для каждого столбца.

движок:В памятиПотоковыйРаспределённый

Примеры

>>> lf = pl.LazyFrame(
...     {"a": [1, 2, 3, 4], "b": [1, 2, 1, None], "c": [None, None, None, None]}
... )
>>> lf.count().collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ u32 ┆ u32 ┆ u32 │
╞═════╪═════╪═════╡
│ 4   ┆ 3   ┆ 0   │
└─────┴─────┴─────┘

describe(
    percentiles: Sequence[float] | float | None = (0.25,
    0.5,
    0.75,
), *, interpolation: QuantileMethod = 'nearest', ) → DataFrame

Создаёт сводку статистики для LazyFrame и возвращает DataFrame.

движок:В памятиПотоковыйРаспределённый

Параметры:

percentiles

Один или несколько процентилей, включаемых в сводную статистику. Все значения должны находиться в диапазоне [0, 1].

interpolation{‘nearest’, ‘higher’, ‘lower’, ‘midpoint’, ‘linear’, ‘equiprobable’}

Метод интерполяции, используемый при вычислении процентилей.

Возвращает:

DataFrame

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

• Этот метод не сохраняет ленивый характер фрейма и collect окончательный результат. Эта операция может быть затратной.
• Мы не гарантируем стабильность результата describe. В нём отображается статистика, которую мы считаем информативной; в будущем она может измениться. По этой причине не рекомендуется программно использовать describe (в отличие от интерактивного изучения данных).
• При выполнении запроса статистики учитываются настройки привязки к движку. После вычисления статистика собирается локально для преобразования результата.

Примечания

Медиана по умолчанию включается как 50-й процентиль.

Примеры

>>> from datetime import date, time
>>> lf = pl.LazyFrame(
...     {
...         "float": [1.0, 2.8, 3.0],
...         "int": [40, 50, None],
...         "bool": [True, False, True],
...         "str": ["zz", "xx", "yy"],
...         "date": [date(2020, 1, 1), date(2021, 7, 5), date(2022, 12, 31)],
...         "time": [time(10, 20, 30), time(14, 45, 50), time(23, 15, 10)],
...     }
... )

Показать статистику фрейма по умолчанию:

>>> lf.describe()
shape: (9, 7)
┌────────────┬──────────┬──────────┬──────────┬──────┬─────────────────────┬──────────┐
│ statistic  ┆ float    ┆ int      ┆ bool     ┆ str  ┆ date                ┆ time     │
│ ---        ┆ ---      ┆ ---      ┆ ---      ┆ ---  ┆ ---                 ┆ ---      │
│ str        ┆ f64      ┆ f64      ┆ f64      ┆ str  ┆ str                 ┆ str      │
╞════════════╪══════════╪══════════╪══════════╪══════╪═════════════════════╪══════════╡
│ count      ┆ 3.0      ┆ 2.0      ┆ 3.0      ┆ 3    ┆ 3                   ┆ 3        │
│ null_count ┆ 0.0      ┆ 1.0      ┆ 0.0      ┆ 0    ┆ 0                   ┆ 0        │
│ mean       ┆ 2.266667 ┆ 45.0     ┆ 0.666667 ┆ null ┆ 2021-07-02 16:00:00 ┆ 16:07:10 │
│ std        ┆ 1.101514 ┆ 7.071068 ┆ null     ┆ null ┆ null                ┆ null     │
│ min        ┆ 1.0      ┆ 40.0     ┆ 0.0      ┆ xx   ┆ 2020-01-01          ┆ 10:20:30 │
│ 25%        ┆ 2.8      ┆ 40.0     ┆ null     ┆ null ┆ 2021-07-05          ┆ 14:45:50 │
│ 50%        ┆ 2.8      ┆ 50.0     ┆ null     ┆ null ┆ 2021-07-05          ┆ 14:45:50 │
│ 75%        ┆ 3.0      ┆ 50.0     ┆ null     ┆ null ┆ 2022-12-31          ┆ 23:15:10 │
│ max        ┆ 3.0      ┆ 50.0     ┆ 1.0      ┆ zz   ┆ 2022-12-31          ┆ 23:15:10 │
└────────────┴──────────┴──────────┴──────────┴──────┴─────────────────────┴──────────┘

Настроить отображаемые процентили, используя линейную интерполяцию:

>>> with pl.Config(tbl_rows=12):
...     lf.describe(
...         percentiles=[0.1, 0.3, 0.5, 0.7, 0.9],
...         interpolation="linear",
...     )
shape: (11, 7)
┌────────────┬──────────┬──────────┬──────────┬──────┬─────────────────────┬──────────┐
│ statistic  ┆ float    ┆ int      ┆ bool     ┆ str  ┆ date                ┆ time     │
│ ---        ┆ ---      ┆ ---      ┆ ---      ┆ ---  ┆ ---                 ┆ ---      │
│ str        ┆ f64      ┆ f64      ┆ f64      ┆ str  ┆ str                 ┆ str      │
╞════════════╪══════════╪══════════╪══════════╪══════╪═════════════════════╪══════════╡
│ count      ┆ 3.0      ┆ 2.0      ┆ 3.0      ┆ 3    ┆ 3                   ┆ 3        │
│ null_count ┆ 0.0      ┆ 1.0      ┆ 0.0      ┆ 0    ┆ 0                   ┆ 0        │
│ mean       ┆ 2.266667 ┆ 45.0     ┆ 0.666667 ┆ null ┆ 2021-07-02 16:00:00 ┆ 16:07:10 │
│ std        ┆ 1.101514 ┆ 7.071068 ┆ null     ┆ null ┆ null                ┆ null     │
│ min        ┆ 1.0      ┆ 40.0     ┆ 0.0      ┆ xx   ┆ 2020-01-01          ┆ 10:20:30 │
│ 10%        ┆ 1.36     ┆ 41.0     ┆ null     ┆ null ┆ 2020-04-20          ┆ 11:13:34 │
│ 30%        ┆ 2.08     ┆ 43.0     ┆ null     ┆ null ┆ 2020-11-26          ┆ 12:59:42 │
│ 50%        ┆ 2.8      ┆ 45.0     ┆ null     ┆ null ┆ 2021-07-05          ┆ 14:45:50 │
│ 70%        ┆ 2.88     ┆ 47.0     ┆ null     ┆ null ┆ 2022-02-07          ┆ 18:09:34 │
│ 90%        ┆ 2.96     ┆ 49.0     ┆ null     ┆ null ┆ 2022-09-13          ┆ 21:33:18 │
│ max        ┆ 3.0      ┆ 50.0     ┆ 1.0      ┆ zz   ┆ 2022-12-31          ┆ 23:15:10 │
└────────────┴──────────┴──────────┴──────────┴──────┴─────────────────────┴──────────┘

classmethod deserialize(
    source: str | bytes | Path | IOBase,
    *,
    format: SerializationFormat = 'binary',
) → LazyFrame

Читает логический план из файла для создания LazyFrame.

Параметры:

source

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

format

Формат, в котором был сериализован LazyFrame. Возможные варианты:

• "binary": десериализовать из двоичного формата (байты). Используется по умолчанию.
• "json": десериализовать из формата JSON (строка).

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

Эта функция использует pickle, если логический план содержит Python UDF, и поэтому наследует связанные с ним риски безопасности. Десериализация может выполнить произвольный код, поэтому её следует выполнять только для доверенных данных.

См. также

LazyFrame.serialize

Примечания

Сериализация нестабильна между версиями Polars: LazyFrame, сериализованный в одной версии Polars, может быть невозможно десериализовать в другой.

Примеры

>>> import io
>>> lf = pl.LazyFrame({"a": [1, 2, 3]}).sum()
>>> bytes = lf.serialize()
>>> pl.LazyFrame.deserialize(io.BytesIO(bytes)).collect()
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 6   │
└─────┘

drop(
    *columns: ColumnNameOrSelector | Iterable[ColumnNameOrSelector],
    strict: bool = True,
) → LazyFrame

Удаляет столбцы из DataFrame.

движок:В памятиПотоковыйРаспределённый

Параметры:

*columns

Имена столбцов, которые нужно удалить из фрейма данных. Принимает селекторы столбцов.

strict

Проверять, что все имена столбцов существуют в текущей схеме, и вызывать исключение, если это не так.

Примеры

Удаление одного столбца с помощью его имени.

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.drop("ham").collect()
shape: (3, 2)
┌─────┬─────┐
│ foo ┆ bar │
│ --- ┆ --- │
│ i64 ┆ f64 │
╞═════╪═════╡
│ 1   ┆ 6.0 │
│ 2   ┆ 7.0 │
│ 3   ┆ 8.0 │
└─────┴─────┘

Удаление нескольких столбцов с помощью селектора.

>>> import polars.selectors as cs
>>> lf.drop(cs.numeric()).collect()
shape: (3, 1)
┌─────┐
│ ham │
│ --- │
│ str │
╞═════╡
│ a   │
│ b   │
│ c   │
└─────┘

Использование позиционных аргументов для удаления нескольких столбцов.

>>> lf.drop("foo", "ham").collect()
shape: (3, 1)
┌─────┐
│ bar │
│ --- │
│ f64 │
╞═════╡
│ 6.0 │
│ 7.0 │
│ 8.0 │
└─────┘

drop_nans(
    subset: ColumnNameOrSelector | Collection[ColumnNameOrSelector] | None = None,
) → LazyFrame

Удаляет все строки, содержащие одно или несколько значений NaN.

Исходный порядок оставшихся строк сохраняется.

движок:В памятиПотоковыйРаспределённый

Параметры:

subset

Имя или имена столбцов, значения NaN в которых учитываются; если задано None (значение по умолчанию), используются все столбцы (обратите внимание, что NaN могут содержаться только в столбцах с числами с плавающей точкой).

См. также

drop_nulls

Примечания

Значение NaN не то же самое, что значение null. Чтобы удалить значения null, используйте drop_nulls().

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "foo": [-20.5, float("nan"), 80.0],
...         "bar": [float("nan"), 110.0, 25.5],
...         "ham": ["xxx", "yyy", None],
...     }
... )

По умолчанию этот метод удаляет строки, если хотя бы одно значение в строке равно NaN:

>>> lf.drop_nans().collect()
shape: (1, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ f64  ┆ f64  ┆ str  │
╞══════╪══════╪══════╡
│ 80.0 ┆ 25.5 ┆ null │
└──────┴──────┴──────┘

Можно ограничить проверку подмножеством столбцов, задав их имена или селектор. Например, удалим строки, содержащие NaN в столбце «bar»:

>>> lf.drop_nans(subset=["bar"]).collect()
shape: (2, 3)
┌──────┬───────┬──────┐
│ foo  ┆ bar   ┆ ham  │
│ ---  ┆ ---   ┆ ---  │
│ f64  ┆ f64   ┆ str  │
╞══════╪═══════╪══════╡
│ NaN  ┆ 110.0 ┆ yyy  │
│ 80.0 ┆ 25.5  ┆ null │
└──────┴───────┴──────┘

Чтобы удалить строку, только если все значения равны NaN, требуется другой способ:

>>> lf = pl.LazyFrame(
...     {
...         "a": [float("nan"), float("nan"), float("nan"), float("nan")],
...         "b": [10.0, 2.5, float("nan"), 5.25],
...         "c": [65.75, float("nan"), float("nan"), 10.5],
...     }
... )
>>> lf.filter(~pl.all_horizontal(pl.all().is_nan())).collect()
shape: (3, 3)
┌─────┬──────┬───────┐
│ a   ┆ b    ┆ c     │
│ --- ┆ ---  ┆ ---   │
│ f64 ┆ f64  ┆ f64   │
╞═════╪══════╪═══════╡
│ NaN ┆ 10.0 ┆ 65.75 │
│ NaN ┆ 2.5  ┆ NaN   │
│ NaN ┆ 5.25 ┆ 10.5  │
└─────┴──────┴───────┘

drop_nulls(
    subset: ColumnNameOrSelector | Collection[ColumnNameOrSelector] | None = None,
) → LazyFrame

Удаляет все строки, содержащие одно или несколько значений null.

Исходный порядок оставшихся строк сохраняется.

движок:В памятиПотоковыйРаспределённый

См. также

drop_nans

Примечания

Значение null не то же самое, что значение NaN. Чтобы удалить значения NaN, используйте drop_nans().

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, None, 8],
...         "ham": ["a", "b", None],
...     }
... )

По умолчанию этот метод удаляет строки, если хотя бы одно значение в строке равно null:

>>> lf.drop_nulls().collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
└─────┴─────┴─────┘

Можно ограничить проверку подмножеством столбцов, задав их имена или селектор. Например, удалим строки, содержащие null хотя бы в одном целочисленном столбце:

>>> import polars.selectors as cs
>>> lf.drop_nulls(subset=cs.integer()).collect()
shape: (2, 3)
┌─────┬─────┬──────┐
│ foo ┆ bar ┆ ham  │
│ --- ┆ --- ┆ ---  │
│ i64 ┆ i64 ┆ str  │
╞═════╪═════╪══════╡
│ 1   ┆ 6   ┆ a    │
│ 3   ┆ 8   ┆ null │
└─────┴─────┴──────┘

Чтобы удалить строку, только если все значения равны null, требуется другой способ:

>>> lf = pl.LazyFrame(
...     {
...         "a": [None, None, None, None],
...         "b": [1, 2, None, 1],
...         "c": [1, None, None, 1],
...     }
... )
>>> lf.filter(~pl.all_horizontal(pl.all().is_null())).collect()
shape: (3, 3)
┌──────┬─────┬──────┐
│ a    ┆ b   ┆ c    │
│ ---  ┆ --- ┆ ---  │
│ null ┆ i64 ┆ i64  │
╞══════╪═════╪══════╡
│ null ┆ 1   ┆ 1    │
│ null ┆ 2   ┆ null │
│ null ┆ 1   ┆ 1    │
└──────┴─────┴──────┘

property dtypes: list[DataType]

Получает типы данных столбцов.

Возвращает:

список DataType

Список, содержащий типы данных всех столбцов в порядке следования.

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

Чтобы определить типы данных LazyFrame, необходимо разрешить его схему, что может быть затратной операцией. Идиоматичный способ разрешить схему — использовать collect_schema(). Это свойство существует только для симметрии с классом DataFrame.

См. также

collect_schema

Schema.dtypes

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.dtypes  
[Int64, Float64, String]

execute(
    *,
    optimizations: QueryOptFlags = (,
), engine: EngineType = 'auto', **_kwargs: Any, ) → QueryResult

Выполняет запрос и сохраняет результат в QueryResult.

Этот способ материализации LazyFrame не гарантирует, где именно будет материализован результат. Для GPU-движка это может быть GPU, для распределённого движка — кластер или удалённое хранилище, а потоковый движок может выгрузить результат на диск, если это потребуется.

QueryResult всегда можно использовать как новый LazyFrame, вызвав .lazy

Параметры:

engine

Выбор движка для обработки запроса; параметр необязательный. Также можно передать экземпляр Engine. В настоящее время, если задано значение "auto" (по умолчанию), запрос выполняется с помощью внутрипамятного движка Polars. Polars также попытается использовать движок, заданный переменной окружения POLARS_ENGINE_AFFINITY. Если выбранный движок не может выполнить запрос, он выполняется с помощью внутрипамятного движка Polars. Если задано значение "gpu", используется GPU-движок. Для более точной настройки GPU-движка, например для выбора устройства в системе с несколькими устройствами, можно передать объект GPUEngine с параметрами конфигурации.

Примечание

Режим GPU считается нестабильным. Не все запросы могут успешно выполняться на GPU, однако при отсутствии поддержки выполнения они должны незаметно переключаться на движок по умолчанию.

Запуск с POLARS_VERBOSE=1 позволит узнать, переключился ли запрос на другой движок (и почему).

optimizations

Этапы оптимизации, выполняемые при оптимизации запроса.

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

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

Возвращает:

QueryResult

См. также

explain

Выводит план запроса, который выполняется при вызове collect.

profile

Собирает LazyFrame и измеряет время выполнения каждого узла графа вычислений.

polars.collect_all

Одновременно собирает несколько LazyFrame.

polars.Config.set_streaming_chunk_size

Задаёт размер потоковых пакетов.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [1, 2, 3, 4, 5, 6],
...         "c": [6, 5, 4, 3, 2, 1],
...     }
... )
>>> lf.group_by("a").agg(pl.all().sum()).collect()  
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 4   ┆ 10  │
│ b   ┆ 11  ┆ 10  │
│ c   ┆ 6   ┆ 1   │
└─────┴─────┴─────┘

Сбор в потоковом режиме

>>> lf.group_by("a").agg(pl.all().sum()).collect(
...     engine="streaming"
... )  
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 4   ┆ 10  │
│ b   ┆ 11  ┆ 10  │
│ c   ┆ 6   ┆ 1   │
└─────┴─────┴─────┘

Сбор в режиме GPU

explain(
    *,
    format: ExplainFormat = 'plain',
    optimized: bool = True,
    type_coercion: bool = True,
    predicate_pushdown: bool = True,
    projection_pushdown: bool = True,
    simplify_expression: bool = True,
    slice_pushdown: bool = True,
    comm_subplan_elim: bool = True,
    comm_subexpr_elim: bool = True,
    cluster_with_columns: bool = True,
    collapse_joins: bool = True,
    streaming: bool = False,
    engine: EngineType = 'auto',
    tree_format: bool | None = None,
    optimizations: QueryOptFlags = (,
), ) → str

Создаёт строковое представление плана запроса.

Различные оптимизации можно включать и отключать.

Параметры:

format{‘plain’, ‘tree’}

Формат отображения логического плана.

optimized

Возвращает оптимизированный план запроса. По умолчанию — True. Если задано значение True, последующие флаги оптимизации определяют, какие оптимизации будут выполнены.

type_coercion

Выполняет оптимизацию приведения типов.

Устарело с версии 1.30.0: Используйте параметры optimizations.

predicate_pushdown

Выполняет оптимизацию проталкивания предикатов.

Устарело с версии 1.30.0: Используйте параметры optimizations.

projection_pushdown

Выполняет оптимизацию проталкивания проекций.

Устарело с версии 1.30.0: Используйте параметры optimizations.

simplify_expression

Выполняет оптимизацию упрощения выражений.

Устарело с версии 1.30.0: Используйте параметры optimizations.

slice_pushdown

Оптимизация проталкивания срезов.

Устарело с версии 1.30.0: Используйте параметры optimizations.

comm_subplan_elim

Пытается кэшировать ветвящиеся подзапросы, возникающие при самосоединениях или объединениях.

Устарело с версии 1.30.0: Используйте параметры optimizations.

comm_subexpr_elim

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

Устарело с версии 1.30.0: Используйте параметры optimizations.

cluster_with_columns

Объединяет последовательные независимые вызовы with_columns

Устарело с версии 1.30.0: Используйте параметры optimizations.

collapse_joins

Объединяет соединение и фильтры в более быстрое соединение

Устарело с версии 1.30.0: Используйте параметры optimizations.

streaming

Неиспользуемый параметр, сохранённый для обратной совместимости.

Устарело с версии 1.30.0: Вместо него используйте параметр engine.

engine

Выбор движка для обработки запроса (по умолчанию "auto"). Также можно передать экземпляр Engine. Поддерживаются следующие имена движков:

• "auto": использует движок, заданный с помощью Config.set_engine_affinity или переменной окружения POLARS_ENGINE_AFFINITY; если значение не задано, используется "in-memory" (это значение по умолчанию может измениться в будущем выпуске).
• "in-memory": использует внутрипамятный движок, который является движком по умолчанию.
• "streaming": использует потоковый движок, обрабатывающий запросы пакетами, что снижает нагрузку на память и часто обеспечивает более высокую производительность, чем внутрипамятный движок. Вскоре он станет движком Polars по умолчанию.
• "gpu": использует GPU-движок CUDA (требуется GPU Nvidia и cudf-polars). Для более точной настройки (например, выбора устройства в системах с несколькими GPU) передайте объект GPUEngine.

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

Примечание

Режим GPU считается нестабильным. Не все запросы могут успешно выполняться на GPU, однако при отсутствии поддержки выполнения они должны незаметно переключаться на движок по умолчанию.

Запуск с POLARS_VERBOSE=1 позволит узнать, переключился ли запрос на другой движок (и почему).

optimizations

Этапы оптимизации, выполняемые при оптимизации запроса.

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

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

tree_format

Форматирует вывод в виде дерева.

Устарело с версии 0.20.30: Вместо этого используйте format="tree".

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [1, 2, 3, 4, 5, 6],
...         "c": [6, 5, 4, 3, 2, 1],
...     }
... )
>>> lf.group_by("a", maintain_order=True).agg(pl.all().sum()).sort(
...     "a"
... ).explain()  

explode(
    columns: ColumnNameOrSelector | Iterable[ColumnNameOrSelector],
    *more_columns: ColumnNameOrSelector,
    empty_as_null: bool = <object object>,
    keep_nulls: bool = True,
) → LazyFrame

Преобразует DataFrame в длинный формат, разворачивая указанные столбцы.

движок:В памятиПотоковыйРаспределённый

Параметры:

columns

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

*more_columns

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

empty_as_null

Разворачивает пустой список/массив в null.

keep_nulls

Разворачивает список/массив null в null.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "letters": ["a", "a", "b", "c"],
...         "numbers": [[1], [2, 3], [4, 5], [6, 7, 8]],
...     }
... )
>>> lf.explode("numbers", empty_as_null=False).collect()
shape: (8, 2)
┌─────────┬─────────┐
│ letters ┆ numbers │
│ ---     ┆ ---     │
│ str     ┆ i64     │
╞═════════╪═════════╡
│ a       ┆ 1       │
│ a       ┆ 2       │
│ a       ┆ 3       │
│ b       ┆ 4       │
│ b       ┆ 5       │
│ c       ┆ 6       │
│ c       ┆ 7       │
│ c       ┆ 8       │
└─────────┴─────────┘

fetch(
    n_rows: int = 500,
    **kwargs: Any,
) → DataFrame

Собирает небольшое количество строк для отладки.

Устарело с версии 1.0: Вместо этого используйте collect() вместе с вызовом head().`

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

Это исключительно вспомогательная функция для отладки запросов на небольшом количестве строк; её не следует использовать в производственном коде.

Примечания

Это похоже на операцию collect(), но она переопределяет количество строк, считываемых каждой операцией сканирования. Обратите внимание: fetch не гарантирует итоговое количество строк в DataFrame. На итоговое число строк влияют фильтры, операции соединения и количество строк, доступных в сканируемых данных (особенно это касается соединений: они могут вернуть пустой результат, если n_rows слишком мало, поскольку ключи соединения могут отсутствовать).

fill_nan(
    value: int | float | Expr | None,
) → LazyFrame

Заполняет значения NaN с плавающей точкой.

движок:В памятиПотоковыйРаспределённый

Параметры:

value

Значение для заполнения значений NaN.

См. также

fill_null

Примечания

Значение NaN отличается от null. Чтобы заполнить значения null, используйте fill_null().

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1.5, 2, float("nan"), 4],
...         "b": [0.5, 4, float("nan"), 13],
...     }
... )
>>> lf.fill_nan(99).collect()
shape: (4, 2)
┌──────┬──────┐
│ a    ┆ b    │
│ ---  ┆ ---  │
│ f64  ┆ f64  │
╞══════╪══════╡
│ 1.5  ┆ 0.5  │
│ 2.0  ┆ 4.0  │
│ 99.0 ┆ 99.0 │
│ 4.0  ┆ 13.0 │
└──────┴──────┘

fill_null(
    value: Any | Expr | None = None,
    strategy: FillNullStrategy | None = None,
    limit: int | None = None,
    *,
    matches_supertype: bool = True,
) → LazyFrame

Заполняет значения null указанным значением или стратегией.

движок:В памятиПотоковыйЧастично распределённый

Параметры:

value

Значение для заполнения null.

strategy{None, ‘forward’, ‘backward’, ‘min’, ‘max’, ‘mean’, ‘zero’, ‘one’}

Стратегия заполнения null.

limit

Количество последовательных значений null для заполнения при использовании стратегии «forward» или «backward».

matches_supertype

Заполняет все соответствующие супертипы литерала заполнения value.

См. также

fill_nan

Примечания

Значение null отличается от NaN. Чтобы заполнить значения NaN, используйте fill_nan().

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, None, 4],
...         "b": [0.5, 4, None, 13],
...     }
... )
>>> lf.fill_null(99).collect()
shape: (4, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ 0.5  │
│ 2   ┆ 4.0  │
│ 99  ┆ 99.0 │
│ 4   ┆ 13.0 │
└─────┴──────┘
>>> lf.fill_null(strategy="forward").collect()
shape: (4, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ 0.5  │
│ 2   ┆ 4.0  │
│ 2   ┆ 4.0  │
│ 4   ┆ 13.0 │
└─────┴──────┘

>>> lf.fill_null(strategy="max").collect()
shape: (4, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ 0.5  │
│ 2   ┆ 4.0  │
│ 4   ┆ 13.0 │
│ 4   ┆ 13.0 │
└─────┴──────┘

>>> lf.fill_null(strategy="zero").collect()
shape: (4, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ 0.5  │
│ 2   ┆ 4.0  │
│ 0   ┆ 0.0  │
│ 4   ┆ 13.0 │
└─────┴──────┘

filter(
    *predicates: IntoExprColumn | Iterable[IntoExprColumn] | bool | list[bool] | np.ndarray[Any,
    Any],
    **constraints: Any,
) → LazyFrame

Фильтрует строки LazyFrame по выражению-предикату.

Исходный порядок оставшихся строк сохраняется.

Строки, для которых предикат фильтрации не вычисляется в True, отбрасываются (включая строки, для которых предикат вычисляется в null).

движок:В памятиПотоковыйРаспределённый

Параметры:

predicates

Выражение, результатом которого является булев Series.

constraints

Фильтры столбцов; используйте name = value для фильтрации столбцов по заданному значению. Каждое ограничение работает так же, как pl.col(name).eq(value), и неявно объединяется с другими условиями фильтра с помощью &.

См. также

remove

Примечания

Если вы переходите с Pandas и выполняете фильтрацию на основе сравнения двух или более столбцов, обратите внимание: в Polars любое сравнение, в котором участвуют значения null, возвращает результат null, а не логическое значение True или False. Поэтому такие строки не сохраняются. Чтобы избежать неожиданного поведения, правильно обрабатывайте значения null (см. примеры ниже).

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3, None, 4, None, 0],
...         "bar": [6, 7, 8, None, None, 9, 0],
...         "ham": ["a", "b", "c", None, "d", "e", "f"],
...     }
... )

Фильтрация по одному условию:

>>> lf.filter(pl.col("foo") > 1).collect()
shape: (3, 3)
┌─────┬──────┬─────┐
│ foo ┆ bar  ┆ ham │
│ --- ┆ ---  ┆ --- │
│ i64 ┆ i64  ┆ str │
╞═════╪══════╪═════╡
│ 2   ┆ 7    ┆ b   │
│ 3   ┆ 8    ┆ c   │
│ 4   ┆ null ┆ d   │
└─────┴──────┴─────┘

Фильтрация по нескольким условиям:

>>> lf.filter((pl.col("foo") < 3) & (pl.col("ham") == "a")).collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
└─────┴─────┴─────┘

Передача нескольких фильтров с использованием синтаксиса *args:

>>> lf.filter(
...     pl.col("foo") == 1,
...     pl.col("ham") == "a",
... ).collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
└─────┴─────┴─────┘

Передача нескольких фильтров с использованием синтаксиса **kwargs:

>>> lf.filter(foo=1, ham="a").collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
└─────┴─────┴─────┘

Фильтрация по условию OR:

>>> lf.filter(
...     (pl.col("foo") == 1) | (pl.col("ham") == "c"),
... ).collect()
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 3   ┆ 8   ┆ c   │
└─────┴─────┴─────┘

Фильтрация путём сравнения двух столбцов друг с другом

>>> lf.filter(
...     pl.col("foo") == pl.col("bar"),
... ).collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 0   ┆ 0   ┆ f   │
└─────┴─────┴─────┘

>>> lf.filter(
...     pl.col("foo") != pl.col("bar"),
... ).collect()
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 2   ┆ 7   ┆ b   │
│ 3   ┆ 8   ┆ c   │
└─────┴─────┴─────┘

Обратите внимание: строка со значениями None отфильтровывается; использование ne_missing обеспечивает равенство при сравнении значений null, что позволяет получить поведение, аналогичное Pandas:

>>> lf.filter(
...     pl.col("foo").ne_missing(pl.col("bar")),
... ).collect()
shape: (5, 3)
┌──────┬──────┬─────┐
│ foo  ┆ bar  ┆ ham │
│ ---  ┆ ---  ┆ --- │
│ i64  ┆ i64  ┆ str │
╞══════╪══════╪═════╡
│ 1    ┆ 6    ┆ a   │
│ 2    ┆ 7    ┆ b   │
│ 3    ┆ 8    ┆ c   │
│ 4    ┆ null ┆ d   │
│ null ┆ 9    ┆ e   │
└──────┴──────┴─────┘

first() → LazyFrame

Возвращает первую строку DataFrame.

движок:В памятиПотоковыйРаспределённый

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 3, 5],
...         "b": [2, 4, 6],
...     }
... )
>>> lf.first().collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 2   │
└─────┴─────┘

gather(
    indices: int | Sequence[int] | IntoExpr | Series | np.ndarray[Any,
    Any] | LazyFrame,
    *,
    null_on_oob: bool = False,
) → LazyFrame

Выбирает строки этого LazyFrame по заданным индексам.

движок:В памятиПотоковыйЧастично распределённый

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

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

Параметры:

indices

Индексы выбираемых строк.

Поскольку LazySeries отсутствует, в качестве индексов также разрешено передавать LazyFrame шириной в один элемент.

null_on_oob

Если значение истинно, при выходе индекса за границы вместо ошибки будет создана строка null.

Примеры

>>> lf = pl.LazyFrame({"x": [2, 1, 0], "s": ["foo", "bar", "baz"]})
>>> lf.gather([2, 0, 0]).collect()
shape: (3, 2)
┌─────┬─────┐
│ x   ┆ s   │
│ --- ┆ --- │
│ i64 ┆ str │
╞═════╪═════╡
│ 0   ┆ baz │
│ 2   ┆ foo │
│ 2   ┆ foo │
└─────┴─────┘

>>> lf.gather([0, 10, 1], null_on_oob=True).collect()
shape: (3, 2)
┌──────┬──────┐
│ x    ┆ s    │
│ ---  ┆ ---  │
│ i64  ┆ str  │
╞══════╪══════╡
│ 2    ┆ foo  │
│ null ┆ null │
│ 1    ┆ bar  │
└──────┴──────┘

>>> idxs = pl.LazyFrame({"i": [1, 10, 0], "b": [True, False, True]})
>>> lf.gather(idxs.filter(pl.col.b).select(pl.col.i)).collect()
shape: (2, 2)
┌─────┬─────┐
│ x   ┆ s   │
│ --- ┆ --- │
│ i64 ┆ str │
╞═════╪═════╡
│ 1   ┆ bar │
│ 2   ┆ foo │
└─────┴─────┘

gather_every(
    n: int,
    offset: int = 0,
) → LazyFrame

Выбирает каждую n-ю строку LazyFrame и возвращает результат в виде нового LazyFrame.

движок:В памятиПотоковый

Параметры:

n

Выбирает каждую n-ю строку.

offset

Начальный индекс.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [5, 6, 7, 8],
...     }
... )
>>> lf.gather_every(2).collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 5   │
│ 3   ┆ 7   │
└─────┴─────┘
>>> lf.gather_every(2, offset=1).collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 2   ┆ 6   │
│ 4   ┆ 8   │
└─────┴─────┘

group_by(
    *by: IntoExpr | Iterable[IntoExpr],
    maintain_order: bool = False,
    **named_by: IntoExpr,
) → LazyGroupBy

Начинает операцию группировки.

движок:В памятиЧастично потоковыйЧастично распределённый

Параметры:

*by

Столбец или столбцы для группировки. Принимает выражения. Строки интерпретируются как имена столбцов.

maintain_order

Гарантирует, что порядок групп соответствует порядку входных данных. Работает медленнее, чем группировка по умолчанию. Значение True исключает возможность выполнения с разбиением на разделы.

**named_by

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

Примеры

Группировка по одному столбцу и вызов agg для вычисления сгруппированной суммы другого столбца.

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "c"],
...         "b": [1, 2, 1, 3, 3],
...         "c": [5, 4, 3, 2, 1],
...     }
... )
>>> lf.group_by("a").agg(pl.col("b").sum()).collect()  
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ a   ┆ 2   │
│ b   ┆ 5   │
│ c   ┆ 3   │
└─────┴─────┘

Задайте maintain_order=True, чтобы порядок групп соответствовал порядку входных данных.

>>> lf.group_by("a", maintain_order=True).agg(pl.col("c")).collect()
shape: (3, 2)
┌─────┬───────────┐
│ a   ┆ c         │
│ --- ┆ ---       │
│ str ┆ list[i64] │
╞═════╪═══════════╡
│ a   ┆ [5, 3]    │
│ b   ┆ [4, 2]    │
│ c   ┆ [1]       │
└─────┴───────────┘

Группировка по нескольким столбцам с передачей списка имён столбцов.

>>> lf.group_by(["a", "b"]).agg(pl.max("c")).collect()  
shape: (4, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 1   ┆ 5   │
│ b   ┆ 2   ┆ 4   │
│ b   ┆ 3   ┆ 2   │
│ c   ┆ 3   ┆ 1   │
└─────┴─────┴─────┘

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

>>> lf.group_by("a", pl.col("b") // 2).agg(
...     pl.col("c").mean()
... ).collect()  
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ f64 │
╞═════╪═════╪═════╡
│ a   ┆ 0   ┆ 4.0 │
│ b   ┆ 1   ┆ 3.0 │
│ c   ┆ 1   ┆ 1.0 │
└─────┴─────┴─────┘

group_by_dynamic(
    index_column: IntoExpr,
    *,
    every: str | timedelta,
    period: str | timedelta | None = None,
    offset: str | timedelta | None = None,
    include_boundaries: bool = False,
    closed: ClosedInterval = 'left',
    label: Label = 'left',
    group_by: IntoExpr | Iterable[IntoExpr] | None = None,
    start_by: StartBy = 'window',
) → LazyGroupBy

Группирует по значению времени (или индекса типа Int32, Int64).

Вычисляются временные окна, и строки распределяются по ним. В отличие от обычной группировки, одна строка может входить в несколько групп. По умолчанию окна имеют следующий вид:

• [начало, начало + период)
• [начало + шаг, начало + шаг + период)
• [начало + 2*шаг, начало + 2*шаг + период)
• …

где start определяется параметрами start_by, offset, every и самой ранней точкой данных. Подробности см. в описании аргумента start_by.

движок:В памятиЧастично потоковыйЧастично распределённый

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

Столбец индекса должен быть отсортирован по возрастанию. Если передан group_by, столбец индекса должен быть отсортирован по возрастанию внутри каждой группы.

Изменено в версии 0.20.14: Параметр by был переименован в group_by.

Параметры:

index_column

Столбец, используемый для группировки по временному окну. Обычно имеет тип Date/Datetime. Этот столбец должен быть отсортирован по возрастанию (или, если указан group_by, отсортирован по возрастанию внутри каждой группы).

При динамической группировке по индексам тип данных должен быть одним из {Int32, Int64}. Обратите внимание: Int32 временно приводится к Int64, поэтому при необходимости высокой производительности используйте столбец Int64.

every

интервал окна

period

длина окна; если значение None, она равна «every»

offset

смещение окна; не действует, если start_by равно ‘datapoint’. По умолчанию равно нулю.

include_boundaries

Добавляет нижнюю и верхнюю границы окна в столбцы “_lower_boundary” и “_upper_boundary”. Это повлияет на производительность, поскольку затрудняет параллельную обработку.

closed{‘left’, ‘right’, ‘both’, ‘none’}

Определяет, какие границы временного интервала включены.

label{‘left’, ‘right’, ‘datapoint’}

Определяет метку окна:

• ‘left’: нижняя граница окна
• ‘right’: верхняя граница окна
• ‘datapoint’: первое значение столбца индекса в данном окне. Если метка не должна совпадать с одной из границ, выберите этот вариант для максимальной производительности.

group_by

Дополнительно группирует по этому столбцу или столбцам.

start_by{‘window’, ‘datapoint’, ‘monday’, ‘tuesday’, ‘wednesday’, ‘thursday’, ‘friday’, ‘saturday’, ‘sunday’}

Стратегия определения начала первого окна.

• ‘window’: берёт наиболее раннюю отметку времени, округляет её с помощью every, а затем прибавляет offset. Обратите внимание: недельные окна начинаются в понедельник.
• ‘datapoint’: начинает с первой встретившейся точки данных.

• день недели (действует только в том случае, если every содержит 'w'):

  • ‘monday’: начинает окно с понедельника перед первой точкой данных.
  • ‘tuesday’: начинает окно со вторника перед первой точкой данных.
  • …
  • ‘sunday’: начинает окно с воскресенья перед первой точкой данных.

  Затем окно сдвигается назад, пока самая ранняя точка данных не окажется внутри него или перед ним.

Возвращает:

LazyGroupBy

Объект, для агрегирования групп которого можно вызвать .agg. Результат будет отсортирован по index_column (но если переданы столбцы group_by, сортировка выполняется только внутри каждой группы).

См. также

rolling

Примечания

1. Если вы переходите с pandas, то

   # polars
   df.group_by_dynamic("ts", every="1d").agg(pl.col("value").sum())
   

   эквивалентно

   # pandas
   df.set_index("ts").resample("D")["value"].sum().reset_index()
   

   но обратите внимание: в отличие от pandas, polars не добавляет дополнительные строки для пустых окон. Если требуется равномерное распределение index_column, используйте эту функцию вместе с DataFrame.upsample().

2. Аргументы every, period и offset задаются с помощью следующих строковых обозначений:

   • 1ns (1 наносекунда)
   • 1us (1 микросекунда)
   • 1ms (1 миллисекунда)
   • 1s (1 секунда)
   • 1m (1 минута)
   • 1h (1 час)
   • 1d (1 календарный день)
   • 1w (1 календарная неделя)
   • 1mo (1 календарный месяц)
   • 1q (1 календарный квартал)
   • 1y (1 календарный год)
   • 1i (1 единица индекса)

   Их можно комбинировать (кроме every): “3d12h4m25s” # 3 дня, 12 часов, 4 минуты и 25 секунд

   Под «календарным днём» понимается соответствующее время следующего дня (который может длиться не 24 часа из-за перехода на летнее время). То же относится к «календарной неделе», «календарному месяцу», «календарному кварталу» и «календарному году».

   При динамической группировке по столбцу целых чисел окна задаются следующим образом:

   • “1i” # длина 1
   • “10i” # длина 10

Примеры

>>> from datetime import datetime
>>> lf = pl.LazyFrame(
...     {
...         "time": pl.datetime_range(
...             start=datetime(2021, 12, 16),
...             end=datetime(2021, 12, 16, 3),
...             interval="30m",
...             eager=True,
...         ),
...         "n": range(7),
...     }
... )
>>> lf.collect()
shape: (7, 2)
┌─────────────────────┬─────┐
│ time                ┆ n   │
│ ---                 ┆ --- │
│ datetime[μs]        ┆ i64 │
╞═════════════════════╪═════╡
│ 2021-12-16 00:00:00 ┆ 0   │
│ 2021-12-16 00:30:00 ┆ 1   │
│ 2021-12-16 01:00:00 ┆ 2   │
│ 2021-12-16 01:30:00 ┆ 3   │
│ 2021-12-16 02:00:00 ┆ 4   │
│ 2021-12-16 02:30:00 ┆ 5   │
│ 2021-12-16 03:00:00 ┆ 6   │
└─────────────────────┴─────┘

Группировка по окнам длительностью 1 час.

>>> lf.group_by_dynamic("time", every="1h", closed="right").agg(
...     pl.col("n")
... ).collect()
shape: (4, 2)
┌─────────────────────┬───────────┐
│ time                ┆ n         │
│ ---                 ┆ ---       │
│ datetime[μs]        ┆ list[i64] │
╞═════════════════════╪═══════════╡
│ 2021-12-15 23:00:00 ┆ [0]       │
│ 2021-12-16 00:00:00 ┆ [1, 2]    │
│ 2021-12-16 01:00:00 ┆ [3, 4]    │
│ 2021-12-16 02:00:00 ┆ [5, 6]    │
└─────────────────────┴───────────┘

Границы окон также можно добавить в результат агрегирования.

>>> lf.group_by_dynamic(
...     "time", every="1h", include_boundaries=True, closed="right"
... ).agg(pl.col("n").mean()).collect()
shape: (4, 4)
┌─────────────────────┬─────────────────────┬─────────────────────┬─────┐
│ _lower_boundary     ┆ _upper_boundary     ┆ time                ┆ n   │
│ ---                 ┆ ---                 ┆ ---                 ┆ --- │
│ datetime[μs]        ┆ datetime[μs]        ┆ datetime[μs]        ┆ f64 │
╞═════════════════════╪═════════════════════╪═════════════════════╪═════╡
│ 2021-12-15 23:00:00 ┆ 2021-12-16 00:00:00 ┆ 2021-12-15 23:00:00 ┆ 0.0 │
│ 2021-12-16 00:00:00 ┆ 2021-12-16 01:00:00 ┆ 2021-12-16 00:00:00 ┆ 1.5 │
│ 2021-12-16 01:00:00 ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 01:00:00 ┆ 3.5 │
│ 2021-12-16 02:00:00 ┆ 2021-12-16 03:00:00 ┆ 2021-12-16 02:00:00 ┆ 5.5 │
└─────────────────────┴─────────────────────┴─────────────────────┴─────┘

При closed=”left” окно не включает правую границу интервала: [lower_bound, upper_bound)

>>> lf.group_by_dynamic("time", every="1h", closed="left").agg(
...     pl.col("n")
... ).collect()
shape: (4, 2)
┌─────────────────────┬───────────┐
│ time                ┆ n         │
│ ---                 ┆ ---       │
│ datetime[μs]        ┆ list[i64] │
╞═════════════════════╪═══════════╡
│ 2021-12-16 00:00:00 ┆ [0, 1]    │
│ 2021-12-16 01:00:00 ┆ [2, 3]    │
│ 2021-12-16 02:00:00 ┆ [4, 5]    │
│ 2021-12-16 03:00:00 ┆ [6]       │
└─────────────────────┴───────────┘

При closed=”both” значения времени на границах окна относятся к двум группам.

>>> lf.group_by_dynamic("time", every="1h", closed="both").agg(
...     pl.col("n")
... ).collect()
shape: (4, 2)
┌─────────────────────┬───────────┐
│ time                ┆ n         │
│ ---                 ┆ ---       │
│ datetime[μs]        ┆ list[i64] │
╞═════════════════════╪═══════════╡
│ 2021-12-16 00:00:00 ┆ [0, 1, 2] │
│ 2021-12-16 01:00:00 ┆ [2, 3, 4] │
│ 2021-12-16 02:00:00 ┆ [4, 5, 6] │
│ 2021-12-16 03:00:00 ┆ [6]       │
└─────────────────────┴───────────┘

Динамическую группировку можно сочетать с группировкой по обычным ключам.

>>> lf = lf.with_columns(groups=pl.Series(["a", "a", "a", "b", "b", "a", "a"]))
>>> lf.collect()
shape: (7, 3)
┌─────────────────────┬─────┬────────┐
│ time                ┆ n   ┆ groups │
│ ---                 ┆ --- ┆ ---    │
│ datetime[μs]        ┆ i64 ┆ str    │
╞═════════════════════╪═════╪════════╡
│ 2021-12-16 00:00:00 ┆ 0   ┆ a      │
│ 2021-12-16 00:30:00 ┆ 1   ┆ a      │
│ 2021-12-16 01:00:00 ┆ 2   ┆ a      │
│ 2021-12-16 01:30:00 ┆ 3   ┆ b      │
│ 2021-12-16 02:00:00 ┆ 4   ┆ b      │
│ 2021-12-16 02:30:00 ┆ 5   ┆ a      │
│ 2021-12-16 03:00:00 ┆ 6   ┆ a      │
└─────────────────────┴─────┴────────┘
>>> lf.group_by_dynamic(
...     "time",
...     every="1h",
...     closed="both",
...     group_by="groups",
...     include_boundaries=True,
... ).agg(pl.col("n")).collect()
shape: (6, 5)
┌────────┬─────────────────────┬─────────────────────┬─────────────────────┬───────────┐
│ groups ┆ _lower_boundary     ┆ _upper_boundary     ┆ time                ┆ n         │
│ ---    ┆ ---                 ┆ ---                 ┆ ---                 ┆ ---       │
│ str    ┆ datetime[μs]        ┆ datetime[μs]        ┆ datetime[μs]        ┆ list[i64] │
╞════════╪═════════════════════╪═════════════════════╪═════════════════════╪═══════════╡
│ a      ┆ 2021-12-16 00:00:00 ┆ 2021-12-16 01:00:00 ┆ 2021-12-16 00:00:00 ┆ [0, 1, 2] │
│ a      ┆ 2021-12-16 01:00:00 ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 01:00:00 ┆ [2]       │
│ a      ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 03:00:00 ┆ 2021-12-16 02:00:00 ┆ [5, 6]    │
│ a      ┆ 2021-12-16 03:00:00 ┆ 2021-12-16 04:00:00 ┆ 2021-12-16 03:00:00 ┆ [6]       │
│ b      ┆ 2021-12-16 01:00:00 ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 01:00:00 ┆ [3, 4]    │
│ b      ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 03:00:00 ┆ 2021-12-16 02:00:00 ┆ [4]       │
└────────┴─────────────────────┴─────────────────────┴─────────────────────┴───────────┘

Динамическая группировка по столбцу индекса

>>> lf = pl.LazyFrame(
...     {
...         "idx": pl.int_range(0, 6, eager=True),
...         "A": ["A", "A", "B", "B", "B", "C"],
...     }
... )
>>> lf.group_by_dynamic(
...     "idx",
...     every="2i",
...     period="3i",
...     include_boundaries=True,
...     closed="right",
... ).agg(pl.col("A").alias("A_agg_list")).collect()
shape: (4, 4)
┌─────────────────┬─────────────────┬─────┬─────────────────┐
│ _lower_boundary ┆ _upper_boundary ┆ idx ┆ A_agg_list      │
│ ---             ┆ ---             ┆ --- ┆ ---             │
│ i64             ┆ i64             ┆ i64 ┆ list[str]       │
╞═════════════════╪═════════════════╪═════╪═════════════════╡
│ -2              ┆ 1               ┆ -2  ┆ ["A", "A"]      │
│ 0               ┆ 3               ┆ 0   ┆ ["A", "B", "B"] │
│ 2               ┆ 5               ┆ 2   ┆ ["B", "B", "C"] │
│ 4               ┆ 7               ┆ 4   ┆ ["C"]           │
└─────────────────┴─────────────────┴─────┴─────────────────┘

head(
    n: int = 5,
) → LazyFrame

Получает первые n строк.

движок:В памятиПотоковыйРаспределённый

Параметры:

n

Количество возвращаемых строк.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4, 5, 6],
...         "b": [7, 8, 9, 10, 11, 12],
...     }
... )
>>> lf.head().collect()
shape: (5, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 7   │
│ 2   ┆ 8   │
│ 3   ┆ 9   │
│ 4   ┆ 10  │
│ 5   ┆ 11  │
└─────┴─────┘
>>> lf.head(2).collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 7   │
│ 2   ┆ 8   │
└─────┴─────┘

inspect(
    fmt: str = '{}',
) → LazyFrame

Проверяет узел графа вычислений.

Выводит значение, вычисляемое этим узлом графа вычислений, и передаёт его дальше.

движок:В памяти

Примеры

>>> lf = pl.LazyFrame({"foo": [1, 1, -2, 3]})
>>> (
...     lf.with_columns(pl.col("foo").cum_sum().alias("bar"))
...     .inspect()  # print the node before the filter
...     .filter(pl.col("bar") == pl.col("foo"))
... )
<LazyFrame at ...>

interpolate() → LazyFrame

Интерполирует промежуточные значения линейным методом.

Значения null в начале и конце ряда остаются null.

движок:В памятиПотоковый

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, None, 9, 10],
...         "bar": [6, 7, 9, None],
...         "baz": [1, None, None, 9],
...     }
... )
>>> lf.interpolate().collect()
shape: (4, 3)
┌──────┬──────┬──────────┐
│ foo  ┆ bar  ┆ baz      │
│ ---  ┆ ---  ┆ ---      │
│ f64  ┆ f64  ┆ f64      │
╞══════╪══════╪══════════╡
│ 1.0  ┆ 6.0  ┆ 1.0      │
│ 5.0  ┆ 7.0  ┆ 3.666667 │
│ 9.0  ┆ 9.0  ┆ 6.333333 │
│ 10.0 ┆ null ┆ 9.0      │
└──────┴──────┴──────────┘

join(
    other: LazyFrame,
    on: str | Expr | Sequence[str | Expr] | None = None,
    how: JoinStrategy = 'inner',
    *,
    left_on: str | Expr | Sequence[str | Expr] | None = None,
    right_on: str | Expr | Sequence[str | Expr] | None = None,
    suffix: str = '_right',
    validate: JoinValidation = 'm:m',
    nulls_equal: bool = False,
    coalesce: bool | None = None,
    maintain_order: MaintainOrderJoin | None = None,
    build_side: JoinBuildSide = 'auto',
    allow_parallel: bool = True,
    force_parallel: bool = False,
) → LazyFrame

Добавить операцию соединения в логический план.

движок:В памятиПотоковыйЧастично распределённый

Изменено в версии 1.24: Параметр join_nulls переименован в nulls_equal.

Параметры:

other

Lazy DataFrame для соединения.

on

Имя (имена) столбцов соединения в обоих DataFrame. Если задано, left_on и right_on должны быть равны None. Не следует задавать этот параметр, если how='cross'.

how{‘inner’,’left’, ‘right’, ‘full’, ‘semi’, ‘anti’, ‘cross’}

Стратегия соединения.

inner	(По умолчанию) Возвращает строки, содержащие совпадающие значения в обеих таблицах.
left	Возвращает все строки из левой таблицы и совпавшие строки из правой таблицы.
right	Возвращает все строки из правой таблицы и совпавшие строки из левой таблицы.
full	Возвращает все строки из обеих таблиц, объединяя совпавшие строки и заполняя несовпадения значениями null.
cross	Возвращает декартово произведение строк обеих таблиц.
semi	Возвращает строки из левой таблицы, имеющие совпадение в правой таблице. Не возвращает столбцы из правой таблицы.
anti	Возвращает строки из левой таблицы, не имеющие совпадений в правой таблице. Не возвращает столбцы из правой таблицы.

left_on

Столбец соединения левого DataFrame.

right_on

Столбец соединения правого DataFrame.

suffix

Суффикс, добавляемый к столбцам с одинаковыми именами.

validate: {‘m:m’, ‘m:1’, ‘1:m’, ‘1:1’}

Проверяет, соответствует ли соединение указанному типу.

m:m	(По умолчанию) Многие ко многим. Проверки не выполняются.
1:1	Один к одному. Проверяет уникальность ключей соединения в обоих наборах данных — левом и правом.
1:m	Один ко многим. Проверяет уникальность ключей соединения в левом наборе данных.
m:1	Многие к одному. Проверяет уникальность ключей соединения в правом наборе данных.

nulls_equal

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

coalesce

Поведение coalesce (объединение столбцов соединения).

None	(По умолчанию) Выполнять coalesce, если не указан how='full'.
True	Всегда объединять столбцы соединения.
False	Никогда не объединять столбцы соединения.

Примечание

Соединение по любым выражениям, кроме col, отключает coalesce.

maintain_order{‘none’, ‘left’, ‘right’, ‘left_right’, ‘right_left’}

Порядок строк какого DataFrame следует сохранять, если таковой требуется. Не полагайтесь на наблюдаемый порядок, не задав этот параметр явно: в будущем выпуске ваш код может перестать работать. Отсутствие указания порядка может повысить производительность.

none	(По умолчанию) Определённый порядок не требуется. Порядок может различаться в разных версиях Polars и даже при разных запусках.
left	Сохраняет порядок левого DataFrame.
right	Сохраняет порядок правого DataFrame.
left_right	Сначала сохраняет порядок левого DataFrame, затем правого.
right_left	Сначала сохраняет порядок правого DataFrame, затем левого.

build_side: {‘auto’, ‘prefer_left’, ‘prefer_right’, ‘force_left’, ‘force_right’}

Какая сторона соединения будет использоваться как строящая сторона. Вероятно, эта сторона будет храниться в памяти в виде хеш-таблицы. Обратите внимание: если не выбран вариант force_, выбранная сторона может различаться в разных версиях Polars и даже при разных запусках.

auto	(По умолчанию) Предоставить Polars выбор строящей стороны.
prefer_left	Если нет веских оснований считать, что правая сторона меньше, использовать левую.
prefer_right	Если нет веских оснований считать, что левая сторона меньше, использовать правую.
force_left	Всегда использовать левую сторону.
force_right	Всегда использовать правую сторону.

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

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

allow_parallel

Разрешить физическому плану при необходимости параллельно вычислять оба DataFrame вплоть до операции соединения.

force_parallel

Заставить физический план параллельно вычислять оба DataFrame вплоть до операции соединения.

См. также

join_asof

join_where

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> other_lf = pl.LazyFrame(
...     {
...         "apple": ["x", "y", "z"],
...         "ham": ["a", "b", "d"],
...     }
... )
>>> lf.join(other_lf, on="ham").collect()
shape: (2, 4)
┌─────┬─────┬─────┬───────┐
│ foo ┆ bar ┆ ham ┆ apple │
│ --- ┆ --- ┆ --- ┆ ---   │
│ i64 ┆ f64 ┆ str ┆ str   │
╞═════╪═════╪═════╪═══════╡
│ 1   ┆ 6.0 ┆ a   ┆ x     │
│ 2   ┆ 7.0 ┆ b   ┆ y     │
└─────┴─────┴─────┴───────┘
>>> lf.join(other_lf, on="ham", how="full").collect()
shape: (4, 5)
┌──────┬──────┬──────┬───────┬───────────┐
│ foo  ┆ bar  ┆ ham  ┆ apple ┆ ham_right │
│ ---  ┆ ---  ┆ ---  ┆ ---   ┆ ---       │
│ i64  ┆ f64  ┆ str  ┆ str   ┆ str       │
╞══════╪══════╪══════╪═══════╪═══════════╡
│ 1    ┆ 6.0  ┆ a    ┆ x     ┆ a         │
│ 2    ┆ 7.0  ┆ b    ┆ y     ┆ b         │
│ null ┆ null ┆ null ┆ z     ┆ d         │
│ 3    ┆ 8.0  ┆ c    ┆ null  ┆ null      │
└──────┴──────┴──────┴───────┴───────────┘
>>> lf.join(other_lf, on="ham", how="left", coalesce=True).collect()
shape: (3, 4)
┌─────┬─────┬─────┬───────┐
│ foo ┆ bar ┆ ham ┆ apple │
│ --- ┆ --- ┆ --- ┆ ---   │
│ i64 ┆ f64 ┆ str ┆ str   │
╞═════╪═════╪═════╪═══════╡
│ 1   ┆ 6.0 ┆ a   ┆ x     │
│ 2   ┆ 7.0 ┆ b   ┆ y     │
│ 3   ┆ 8.0 ┆ c   ┆ null  │
└─────┴─────┴─────┴───────┘
>>> lf.join(other_lf, on="ham", how="semi").collect()
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ f64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6.0 ┆ a   │
│ 2   ┆ 7.0 ┆ b   │
└─────┴─────┴─────┘
>>> lf.join(other_lf, on="ham", how="anti").collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ f64 ┆ str │
╞═════╪═════╪═════╡
│ 3   ┆ 8.0 ┆ c   │
└─────┴─────┴─────┘

>>> lf.join(other_lf, how="cross").collect()
shape: (9, 5)
┌─────┬─────┬─────┬───────┬───────────┐
│ foo ┆ bar ┆ ham ┆ apple ┆ ham_right │
│ --- ┆ --- ┆ --- ┆ ---   ┆ ---       │
│ i64 ┆ f64 ┆ str ┆ str   ┆ str       │
╞═════╪═════╪═════╪═══════╪═══════════╡
│ 1   ┆ 6.0 ┆ a   ┆ x     ┆ a         │
│ 1   ┆ 6.0 ┆ a   ┆ y     ┆ b         │
│ 1   ┆ 6.0 ┆ a   ┆ z     ┆ d         │
│ 2   ┆ 7.0 ┆ b   ┆ x     ┆ a         │
│ 2   ┆ 7.0 ┆ b   ┆ y     ┆ b         │
│ 2   ┆ 7.0 ┆ b   ┆ z     ┆ d         │
│ 3   ┆ 8.0 ┆ c   ┆ x     ┆ a         │
│ 3   ┆ 8.0 ┆ c   ┆ y     ┆ b         │
│ 3   ┆ 8.0 ┆ c   ┆ z     ┆ d         │
└─────┴─────┴─────┴───────┴───────────┘

join_asof(
    other: LazyFrame,
    *,
    left_on: str | None | Expr = None,
    right_on: str | None | Expr = None,
    on: str | None | Expr = None,
    by_left: str | Sequence[str] | None = None,
    by_right: str | Sequence[str] | None = None,
    by: str | Sequence[str] | None = None,
    strategy: AsofJoinStrategy = 'backward',
    suffix: str = '_right',
    tolerance: str | int | float | timedelta | None = None,
    allow_parallel: bool = True,
    force_parallel: bool = False,
    coalesce: bool = True,
    allow_exact_matches: bool = True,
    check_sortedness: bool = True,
) → LazyFrame

Выполнить asof-соединение.

Оно похоже на левое соединение, но вместо равенства ключей выполняется сопоставление по ближайшему ключу.

Оба DataFrame должны быть отсортированы по ключу on (внутри каждой группы by, если она указана).

Для каждой строки левого DataFrame:

• При поиске «назад» выбирается последняя строка правого DataFrame, ключ ‘on’ которой меньше или равен ключу левой строки.

• При поиске «вперёд» выбирается первая строка правого DataFrame, ключ ‘on’ которой больше или равен ключу левой строки.

  При поиске «ближайшего» выбирается строка правого DataFrame со значением, ближайшим к ключу левой строки. Поиск ближайшего совпадения для строковых ключей сейчас не поддерживается.

По умолчанию выполняется поиск «назад».

движок:В памятиЧастично потоковыйЧастично распределённый

Параметры:

other

Lazy DataFrame для соединения.

left_on

Столбец соединения левого DataFrame.

right_on

Столбец соединения правого DataFrame.

on

Столбец соединения обоих DataFrame. Если задано, left_on и right_on должны быть равны None.

by_left

Сначала выполнить соединение по этим столбцам, а затем asof-соединение.

by_right

Сначала выполнить соединение по этим столбцам, а затем asof-соединение.

by

Сначала выполнить соединение по этим столбцам, а затем asof-соединение.

strategy{‘backward’, ‘forward’, ‘nearest’}

Стратегия соединения.

suffix

Суффикс, добавляемый к столбцам с одинаковыми именами.

tolerance

Числовой допуск. Если задать этот параметр, соединение будет выполнено, только если расстояние между близкими ключами не превышает указанного значения. При выполнении asof-соединения по столбцам типа “Date”, “Datetime”, “Duration” или “Time” используйте объект datetime.timedelta или строку в следующем формате:

• 1ns (1 наносекунда)
• 1us (1 микросекунда)
• 1ms (1 миллисекунда)
• 1s (1 секунда)
• 1m (1 минута)
• 1h (1 час)
• 1d (1 календарный день)
• 1w (1 календарная неделя)
• 1mo (1 календарный месяц)
• 1q (1 календарный квартал)
• 1y (1 календарный год)

Или объедините значения: “3d12h4m25s” # 3 дня, 12 часов, 4 минуты и 25 секунд

Под «календарным днём» понимается то же время следующего дня (который может длиться не 24 часа из-за перехода на летнее время; в неоднозначных случаях мы следуем RFC-5545 и сохраняем fold летнего времени исходной даты и времени). Аналогично для «календарной недели», «календарного месяца», «календарного квартала» и «календарного года».

allow_parallel

Разрешить физическому плану при необходимости параллельно вычислять оба DataFrame вплоть до операции соединения.

force_parallel

Заставить физический план параллельно вычислять оба DataFrame вплоть до операции соединения.

coalesce

Поведение coalesce (объединение столбцов on / left_on / right_on):

• True: -> Всегда объединять столбцы соединения.
• False: -> Никогда не объединять столбцы соединения.

Обратите внимание: соединение по любым выражениям, кроме col, отключает coalesce.

allow_exact_matches

Допускаются ли точные совпадения в качестве предикатов соединения.

• If True, allow matching with the same on value

  (то есть «меньше или равно» / «больше или равно»)

• If False, don’t match the same on value

  (то есть строго «меньше» / строго «больше»).

check_sortedness

Проверять, отсортированы ли ключи asof-соединения. Если ключи не отсортированы, Polars выдаст ошибку. В настоящее время движок in-memory не может проверить сортировку, если заданы группы ‘by’. Движок streaming проверяет сортировку только обрабатываемых им строк.

См. также

join

join_where

Примечания

Если задан ‘by’, реализация будет одновременно вычислять asof-соединение для всех групп. При большом количестве групп это может привести к высокому потреблению памяти.

Эту проблему можно смягчить, отсортировав оба входных LazyFrame по ключам ‘by’ (с помощью .sort(); либо используя .set_sorted(), если столбцы уже отсортированы) до вычисления операции соединения и используя потоковый движок для сбора результатов. Например:

>>> # Compute streaming asof join with 'by' groups
>>> result = (
...     left.sort("by", "on").join_asof(  # Sort left manually
...         right.set_sorted("by", "on"),  # Set right as already sorted
...     )
... ).collect(streaming=True)  

Примеры

>>> from datetime import date
>>> gdp = pl.LazyFrame(
...     {
...         "date": pl.date_range(
...             date(2016, 1, 1),
...             date(2020, 1, 1),
...             "1y",
...             eager=True,
...         ),
...         "gdp": [4164, 4411, 4566, 4696, 4827],
...     }
... )
>>> gdp.collect()
shape: (5, 2)
┌────────────┬──────┐
│ date       ┆ gdp  │
│ ---        ┆ ---  │
│ date       ┆ i64  │
╞════════════╪══════╡
│ 2016-01-01 ┆ 4164 │
│ 2017-01-01 ┆ 4411 │
│ 2018-01-01 ┆ 4566 │
│ 2019-01-01 ┆ 4696 │
│ 2020-01-01 ┆ 4827 │
└────────────┴──────┘

>>> population = pl.LazyFrame(
...     {
...         "date": [date(2016, 3, 1), date(2018, 8, 1), date(2019, 1, 1)],
...         "population": [82.19, 82.66, 83.12],
...     }
... ).sort("date")
>>> population.collect()
shape: (3, 2)
┌────────────┬────────────┐
│ date       ┆ population │
│ ---        ┆ ---        │
│ date       ┆ f64        │
╞════════════╪════════════╡
│ 2016-03-01 ┆ 82.19      │
│ 2018-08-01 ┆ 82.66      │
│ 2019-01-01 ┆ 83.12      │
└────────────┴────────────┘

Обратите внимание, что даты не совпадают в точности. Если соединить их с помощью join_asof и strategy='backward', то для каждой даты из population без точного совпадения будет найдена ближайшая более ранняя дата из gdp:

>>> population.join_asof(gdp, on="date", strategy="backward").collect()
shape: (3, 3)
┌────────────┬────────────┬──────┐
│ date       ┆ population ┆ gdp  │
│ ---        ┆ ---        ┆ ---  │
│ date       ┆ f64        ┆ i64  │
╞════════════╪════════════╪══════╡
│ 2016-03-01 ┆ 82.19      ┆ 4164 │
│ 2018-08-01 ┆ 82.66      ┆ 4566 │
│ 2019-01-01 ┆ 83.12      ┆ 4696 │
└────────────┴────────────┴──────┘

Обратите внимание:

• дата 2016-03-01 из population сопоставляется с 2016-01-01 из gdp;
• дата 2018-08-01 из population сопоставляется с 2018-01-01 из gdp.

Это можно проверить, передав coalesce=False:

>>> population.join_asof(
...     gdp, on="date", strategy="backward", coalesce=False
... ).collect()
shape: (3, 4)
┌────────────┬────────────┬────────────┬──────┐
│ date       ┆ population ┆ date_right ┆ gdp  │
│ ---        ┆ ---        ┆ ---        ┆ ---  │
│ date       ┆ f64        ┆ date       ┆ i64  │
╞════════════╪════════════╪════════════╪══════╡
│ 2016-03-01 ┆ 82.19      ┆ 2016-01-01 ┆ 4164 │
│ 2018-08-01 ┆ 82.66      ┆ 2018-01-01 ┆ 4566 │
│ 2019-01-01 ┆ 83.12      ┆ 2019-01-01 ┆ 4696 │
└────────────┴────────────┴────────────┴──────┘

Если вместо этого использовать strategy='forward', то для каждой даты из population без точного совпадения будет найдена ближайшая более поздняя дата из gdp:

>>> population.join_asof(gdp, on="date", strategy="forward").collect()
shape: (3, 3)
┌────────────┬────────────┬──────┐
│ date       ┆ population ┆ gdp  │
│ ---        ┆ ---        ┆ ---  │
│ date       ┆ f64        ┆ i64  │
╞════════════╪════════════╪══════╡
│ 2016-03-01 ┆ 82.19      ┆ 4411 │
│ 2018-08-01 ┆ 82.66      ┆ 4696 │
│ 2019-01-01 ┆ 83.12      ┆ 4696 │
└────────────┴────────────┴──────┘

Обратите внимание:

• дата 2016-03-01 из population сопоставляется с 2017-01-01 из gdp;
• дата 2018-08-01 из population сопоставляется с 2019-01-01 из gdp.

Наконец, strategy='nearest' даёт сочетание двух приведённых выше результатов: каждой дате из population без точного совпадения сопоставляется ближайшая дата из gdp, независимо от того, раньше она или позже:

>>> population.join_asof(gdp, on="date", strategy="nearest").collect()
shape: (3, 3)
┌────────────┬────────────┬──────┐
│ date       ┆ population ┆ gdp  │
│ ---        ┆ ---        ┆ ---  │
│ date       ┆ f64        ┆ i64  │
╞════════════╪════════════╪══════╡
│ 2016-03-01 ┆ 82.19      ┆ 4164 │
│ 2018-08-01 ┆ 82.66      ┆ 4696 │
│ 2019-01-01 ┆ 83.12      ┆ 4696 │
└────────────┴────────────┴──────┘

Обратите внимание:

• дата 2016-03-01 из population сопоставляется с 2016-01-01 из gdp;
• дата 2018-08-01 из population сопоставляется с 2019-01-01 из gdp.

Аргумент by позволяет сначала выполнить соединение по другому столбцу, а затем — asof-соединение. В этом примере сначала выполняется соединение по country, а затем asof-соединение по дате, как и выше.

>>> gdp_dates = pl.date_range(  # fmt: skip
...     date(2016, 1, 1), date(2020, 1, 1), "1y", eager=True
... )
>>> gdp2 = pl.LazyFrame(
...     {
...         "country": ["Germany"] * 5 + ["Netherlands"] * 5,
...         "date": pl.concat([gdp_dates, gdp_dates]),
...         "gdp": [4164, 4411, 4566, 4696, 4827, 784, 833, 914, 910, 909],
...     }
... ).sort("country", "date")
>>>
>>> gdp2.collect()
shape: (10, 3)
┌─────────────┬────────────┬──────┐
│ country     ┆ date       ┆ gdp  │
│ ---         ┆ ---        ┆ ---  │
│ str         ┆ date       ┆ i64  │
╞═════════════╪════════════╪══════╡
│ Germany     ┆ 2016-01-01 ┆ 4164 │
│ Germany     ┆ 2017-01-01 ┆ 4411 │
│ Germany     ┆ 2018-01-01 ┆ 4566 │
│ Germany     ┆ 2019-01-01 ┆ 4696 │
│ Germany     ┆ 2020-01-01 ┆ 4827 │
│ Netherlands ┆ 2016-01-01 ┆ 784  │
│ Netherlands ┆ 2017-01-01 ┆ 833  │
│ Netherlands ┆ 2018-01-01 ┆ 914  │
│ Netherlands ┆ 2019-01-01 ┆ 910  │
│ Netherlands ┆ 2020-01-01 ┆ 909  │
└─────────────┴────────────┴──────┘
>>> pop2 = pl.LazyFrame(
...     {
...         "country": ["Germany"] * 3 + ["Netherlands"] * 3,
...         "date": [
...             date(2016, 3, 1),
...             date(2018, 8, 1),
...             date(2019, 1, 1),
...             date(2016, 3, 1),
...             date(2018, 8, 1),
...             date(2019, 1, 1),
...         ],
...         "population": [82.19, 82.66, 83.12, 17.11, 17.32, 17.40],
...     }
... ).sort("country", "date")
>>>
>>> pop2.collect()
shape: (6, 3)
┌─────────────┬────────────┬────────────┐
│ country     ┆ date       ┆ population │
│ ---         ┆ ---        ┆ ---        │
│ str         ┆ date       ┆ f64        │
╞═════════════╪════════════╪════════════╡
│ Germany     ┆ 2016-03-01 ┆ 82.19      │
│ Germany     ┆ 2018-08-01 ┆ 82.66      │
│ Germany     ┆ 2019-01-01 ┆ 83.12      │
│ Netherlands ┆ 2016-03-01 ┆ 17.11      │
│ Netherlands ┆ 2018-08-01 ┆ 17.32      │
│ Netherlands ┆ 2019-01-01 ┆ 17.4       │
└─────────────┴────────────┴────────────┘
>>> pop2.join_asof(gdp2, by="country", on="date", strategy="nearest").collect()
shape: (6, 4)
┌─────────────┬────────────┬────────────┬──────┐
│ country     ┆ date       ┆ population ┆ gdp  │
│ ---         ┆ ---        ┆ ---        ┆ ---  │
│ str         ┆ date       ┆ f64        ┆ i64  │
╞═════════════╪════════════╪════════════╪══════╡
│ Germany     ┆ 2016-03-01 ┆ 82.19      ┆ 4164 │
│ Germany     ┆ 2018-08-01 ┆ 82.66      ┆ 4696 │
│ Germany     ┆ 2019-01-01 ┆ 83.12      ┆ 4696 │
│ Netherlands ┆ 2016-03-01 ┆ 17.11      ┆ 784  │
│ Netherlands ┆ 2018-08-01 ┆ 17.32      ┆ 910  │
│ Netherlands ┆ 2019-01-01 ┆ 17.4       ┆ 910  │
└─────────────┴────────────┴────────────┴──────┘

join_where(
    other: LazyFrame,
    *predicates: Expr | Iterable[Expr],
    how: JoinWhereStrategy = 'inner',
    suffix: str = '_right',
) → LazyFrame

Выполнить соединение на основе одного или нескольких предикатов (не)равенства.

движок:В памятиЧастично потоковыйЧастично распределённый

Примечание

Порядок строк входных DataFrame не сохраняется.

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

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

Параметры:

other

DataFrame для соединения.

*predicates

Условие (не)равенства для соединения двух таблиц. Если имя столбца встречается в обеих таблицах, в предикате необходимо применить соответствующий суффикс.

how{‘inner’, ‘left’, ‘right’}

Стратегия соединения.

suffix

Суффикс, добавляемый к столбцам с одинаковыми именами.

См. также

join

join_asof

Примеры

Соединение двух LazyFrame на основе двух предикатов, объединённых оператором AND.

>>> east = pl.LazyFrame(
...     {
...         "id": [100, 101, 102],
...         "dur": [120, 140, 160],
...         "rev": [12, 14, 16],
...         "cores": [2, 8, 4],
...     }
... )
>>> west = pl.LazyFrame(
...     {
...         "t_id": [404, 498, 676, 742],
...         "time": [90, 130, 150, 170],
...         "cost": [9, 13, 15, 16],
...         "cores": [4, 2, 1, 4],
...     }
... )
>>> east.join_where(
...     west,
...     pl.col("dur") < pl.col("time"),
...     pl.col("rev") < pl.col("cost"),
... ).collect()
shape: (5, 8)
┌─────┬─────┬─────┬───────┬──────┬──────┬──────┬─────────────┐
│ id  ┆ dur ┆ rev ┆ cores ┆ t_id ┆ time ┆ cost ┆ cores_right │
│ --- ┆ --- ┆ --- ┆ ---   ┆ ---  ┆ ---  ┆ ---  ┆ ---         │
│ i64 ┆ i64 ┆ i64 ┆ i64   ┆ i64  ┆ i64  ┆ i64  ┆ i64         │
╞═════╪═════╪═════╪═══════╪══════╪══════╪══════╪═════════════╡
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 498  ┆ 130  ┆ 13   ┆ 2           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
└─────┴─────┴─────┴───────┴──────┴──────┴──────┴─────────────┘

Чтобы объединить их оператором OR, используйте одно выражение и оператор |.

>>> east.join_where(
...     west,
...     (pl.col("dur") < pl.col("time")) | (pl.col("rev") < pl.col("cost")),
... ).collect()
shape: (6, 8)
┌─────┬─────┬─────┬───────┬──────┬──────┬──────┬─────────────┐
│ id  ┆ dur ┆ rev ┆ cores ┆ t_id ┆ time ┆ cost ┆ cores_right │
│ --- ┆ --- ┆ --- ┆ ---   ┆ ---  ┆ ---  ┆ ---  ┆ ---         │
│ i64 ┆ i64 ┆ i64 ┆ i64   ┆ i64  ┆ i64  ┆ i64  ┆ i64         │
╞═════╪═════╪═════╪═══════╪══════╪══════╪══════╪═════════════╡
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 498  ┆ 130  ┆ 13   ┆ 2           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
│ 102 ┆ 160 ┆ 16  ┆ 4     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
└─────┴─────┴─────┴───────┴──────┴──────┴──────┴─────────────┘

Передайте how="left", чтобы дополнительно сохранить строки левой таблицы, которым ничего не соответствует, заполнив столбцы правой таблицы значениями null.

>>> east.join_where(
...     west,
...     pl.col("dur") < pl.col("time"),
...     pl.col("rev") < pl.col("cost"),
...     how="left",
... ).collect()
shape: (6, 8)
┌─────┬─────┬─────┬───────┬──────┬──────┬──────┬─────────────┐
│ id  ┆ dur ┆ rev ┆ cores ┆ t_id ┆ time ┆ cost ┆ cores_right │
│ --- ┆ --- ┆ --- ┆ ---   ┆ ---  ┆ ---  ┆ ---  ┆ ---         │
│ i64 ┆ i64 ┆ i64 ┆ i64   ┆ i64  ┆ i64  ┆ i64  ┆ i64         │
╞═════╪═════╪═════╪═══════╪══════╪══════╪══════╪═════════════╡
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 498  ┆ 130  ┆ 13   ┆ 2           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
│ 102 ┆ 160 ┆ 16  ┆ 4     ┆ null ┆ null ┆ null ┆ null        │
└─────┴─────┴─────┴───────┴──────┴──────┴──────┴─────────────┘

last() → LazyFrame

Получить последнюю строку DataFrame.

движок:В памятиПотоковыйРаспределённый

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 5, 3],
...         "b": [2, 4, 6],
...     }
... )
>>> lf.last().collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 3   ┆ 6   │
└─────┴─────┘

lazy() → LazyFrame

Вернуть ленивое представление, то есть сам объект.

Полезно при написании кода, ожидающего объект типа DataFrame или LazyFrame. Для LazyFrame этот метод ничего не делает и возвращает тот же объект.

Возвращает:

LazyFrame

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [None, 2, 3, 4],
...         "b": [0.5, None, 2.5, 13],
...         "c": [True, True, False, None],
...     }
... )
>>> lf.lazy()
<LazyFrame at ...>

limit(
    n: int = 5,
) → LazyFrame

Получить первые n строк.

Псевдоним для LazyFrame.head().

движок:В памятиПотоковыйРаспределённый

Параметры:

n

Количество возвращаемых строк.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4, 5, 6],
...         "b": [7, 8, 9, 10, 11, 12],
...     }
... )
>>> lf.limit().collect()
shape: (5, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 7   │
│ 2   ┆ 8   │
│ 3   ┆ 9   │
│ 4   ┆ 10  │
│ 5   ┆ 11  │
└─────┴─────┘
>>> lf.limit(2).collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 7   │
│ 2   ┆ 8   │
└─────┴─────┘

map_batches(
    function: Callable[[DataFrame],
    DataFrame],
    *,
    predicate_pushdown: bool = False,
    projection_pushdown: bool = False,
    slice_pushdown: bool = False,
    no_optimizations: bool | None = None,
    schema: None | SchemaDict = None,
    validate_output_schema: bool = True,
    streamable: bool = False,
) → LazyFrame

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

Важно, чтобы функция возвращала DataFrame Polars.

движок:В памятиПотоковыйРаспределённый

Параметры:

function

Лямбда-функция/функция для применения.

predicate_pushdown

Разрешить оптимизации проталкивания предикатов проходить через этот узел.

projection_pushdown

Разрешить оптимизации проталкивания проекций проходить через этот узел.

slice_pushdown

Разрешить оптимизации проталкивания срезов проходить через этот узел.

no_optimizations

Устарел с версии 1.30.0: Этот параметр устарел и будет удалён в будущем выпуске. Параметры _pushdown теперь по умолчанию принимают значение False, поэтому этот параметр больше не нужен.

schema

Схема вывода функции. Если задано значение None, предполагается, что применённая функция не изменит схему.

validate_output_schema

Крайне важно, чтобы схема Polars была правильной. Этот флаг гарантирует проверку выходной схемы функции на соответствие ожидаемой схеме. Если задать значение False, проверка выполняться не будет, что может привести к трудноотлаживаемым ошибкам.

streamable

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

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

Значение schema для LazyFrame всегда должно быть правильным. Вызывающая сторона отвечает за соблюдение этого инварианта.

Важно правильно задавать флаги оптимизации. Например, если пользовательская функция выполняет агрегирование столбца, не следует разрешать predicate_pushdown, поскольку оно удаляет строки и влияет на результаты агрегирования.

Примечания

UDF, передаваемая в map_batches, должна быть чистой, то есть не изменять и не использовать состояние, отличное от её аргументов.

Примеры

>>> lf = (  
...     pl.LazyFrame(
...         {
...             "a": pl.int_range(-100_000, 0, eager=True),
...             "b": pl.int_range(0, 100_000, eager=True),
...         }
...     )
...     .map_batches(lambda x: 2 * x, streamable=True)
...     .collect(engine="streaming")
... )
shape: (100_000, 2)
┌─────────┬────────┐
│ a       ┆ b      │
│ ---     ┆ ---    │
│ i64     ┆ i64    │
╞═════════╪════════╡
│ -200000 ┆ 0      │
│ -199998 ┆ 2      │
│ -199996 ┆ 4      │
│ -199994 ┆ 6      │
│ …       ┆ …      │
│ -8      ┆ 199992 │
│ -6      ┆ 199994 │
│ -4      ┆ 199996 │
│ -2      ┆ 199998 │
└─────────┴────────┘

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 │
└─────┴─────┘

max() → LazyFrame

Агрегировать столбцы LazyFrame, получив их максимальные значения.

движок:В памятиПотоковыйРаспределённый

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.max().collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 4   ┆ 2   │
└─────┴─────┘

mean() → LazyFrame

Агрегировать столбцы LazyFrame, получив их средние значения.

движок:В памятиПотоковыйРаспределённый

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.mean().collect()
shape: (1, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ f64 ┆ f64  │
╞═════╪══════╡
│ 2.5 ┆ 1.25 │
└─────┴──────┘

median() → LazyFrame

Агрегировать столбцы LazyFrame, получив их медианные значения.

движок:В памятиПотоковыйРаспределённый

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.median().collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ f64 ┆ f64 │
╞═════╪═════╡
│ 2.5 ┆ 1.0 │
└─────┴─────┘

melt(
    id_vars: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    value_vars: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    variable_name: str | None = None,
    value_name: str | None = None,
    *,
    streamable: bool = True,
) → LazyFrame

Преобразовать DataFrame из широкого формата в длинный.

При необходимости оставить столбцы-идентификаторы.

Эта функция полезна для преобразования DataFrame в формат, в котором один или несколько столбцов являются переменными-идентификаторами (id_vars), а все остальные столбцы, считающиеся измеряемыми переменными (value_vars), «разворачиваются» в строки, оставляя только два столбца, не являющихся идентификаторами: ‘variable’ и ‘value’.

Устарел с версии 1.0.0: Вместо него используйте метод unpivot().

Параметры:

id_vars

Столбец (столбцы) или селектор (селекторы), используемые как переменные-идентификаторы.

value_vars

Столбец (столбцы) или селектор (селекторы), используемые как переменные-значения; если value_vars пуст, будут использоваться все столбцы, не входящие в id_vars.

variable_name

Имя столбца variable. По умолчанию “variable”.

value_name

Имя столбца value. По умолчанию “value”.

streamable

Разрешить выполнение этого узла в потоковом движке. При потоковом выполнении порядок результатов операции unpivot не будет стабильным.

merge_sorted(
    other: LazyFrame,
    key: str | Sequence[str],
    *,
    maintain_order: bool = False,
) → LazyFrame

Объединить два отсортированных DataFrame по отсортированному ключу.

Результат этой операции также будет отсортирован. Вызывающая сторона отвечает за сортировку фреймов по ключу (ключам) по возрастанию с размещением ключей null в конце; в противном случае порядок результата не будет иметь смысла.

Схемы обоих LazyFrame должны совпадать.

движок:В памятиПотоковый

Параметры:

other

Другой DataFrame для объединения.

key

Столбец (столбцы) ключа, по которому отсортированы фреймы. Можно передать имя одного столбца или последовательность имён столбцов. Если указано несколько ключей, фреймы объединяются так, как если бы они были отсортированы по этим ключам в заданном порядке.

maintain_order

Если True, гарантируется, что при равных ключах в результате строки левого фрейма будут перед строками правого.

Примечания

Если maintain_order=True, порядок строк результата при совпадении ключей в обоих DataFrame не гарантируется.

Ключи должны быть отсортированы по возрастанию.

Примеры

>>> df0 = pl.LazyFrame(
...     {"name": ["steve", "elise", "bob"], "age": [42, 44, 18]}
... ).sort("age")
>>> df0.collect()
shape: (3, 2)
┌───────┬─────┐
│ name  ┆ age │
│ ---   ┆ --- │
│ str   ┆ i64 │
╞═══════╪═════╡
│ bob   ┆ 18  │
│ steve ┆ 42  │
│ elise ┆ 44  │
└───────┴─────┘
>>> df1 = pl.LazyFrame(
...     {"name": ["anna", "megan", "steve", "thomas"], "age": [21, 33, 42, 20]}
... ).sort("age")
>>> df1.collect()
shape: (4, 2)
┌────────┬─────┐
│ name   ┆ age │
│ ---    ┆ --- │
│ str    ┆ i64 │
╞════════╪═════╡
│ thomas ┆ 20  │
│ anna   ┆ 21  │
│ megan  ┆ 33  │
│ steve  ┆ 42  │
└────────┴─────┘
>>> df0.merge_sorted(df1, key="age").collect()
shape: (7, 2)
┌────────┬─────┐
│ name   ┆ age │
│ ---    ┆ --- │
│ str    ┆ i64 │
╞════════╪═════╡
│ bob    ┆ 18  │
│ thomas ┆ 20  │
│ anna   ┆ 21  │
│ megan  ┆ 33  │
│ steve  ┆ 42  │
│ steve  ┆ 42  │
│ elise  ┆ 44  │
└────────┴─────┘

Для объединения фреймов, отсортированных по составному ключу, можно передать несколько ключей. Фреймы объединяются так, как если бы они были отсортированы сначала по key_1, а затем по key_2.

>>> df0 = pl.LazyFrame({"key_1": [1, 1, 3], "key_2": [1, 4, 2]})
>>> df1 = pl.LazyFrame({"key_1": [1, 2, 3], "key_2": [2, 1, 1]})
>>> df0.merge_sorted(df1, key=["key_1", "key_2"]).collect()
shape: (6, 2)
┌───────┬───────┐
│ key_1 ┆ key_2 │
│ ---   ┆ ---   │
│ i64   ┆ i64   │
╞═══════╪═══════╡
│ 1     ┆ 1     │
│ 1     ┆ 2     │
│ 1     ┆ 4     │
│ 2     ┆ 1     │
│ 3     ┆ 1     │
│ 3     ┆ 2     │
└───────┴───────┘

min() → LazyFrame

Агрегировать столбцы LazyFrame, получив их минимальные значения.

движок:В памятиПотоковыйРаспределённый

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.min().collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 1   │
└─────┴─────┘

null_count() → LazyFrame

Агрегировать столбцы LazyFrame, вычислив сумму количества значений null.

движок:В памятиПотоковыйРаспределённый

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, None, 3],
...         "bar": [6, 7, None],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.null_count().collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ u32 ┆ u32 ┆ u32 │
╞═════╪═════╪═════╡
│ 1   ┆ 1   ┆ 0   │
└─────┴─────┴─────┘

pipe(
    function: Callable[Concatenate[LazyFrame,
    P],
    T],
    *args: P.args,
    **kwargs: P.kwargs,
) → T

Предоставляет структурированный способ применения последовательности пользовательских функций (UDF).

движок:В памятиПотоковыйРаспределённый

Параметры:

function

Вызываемый объект; получит фрейм в качестве первого параметра, за которым последуют переданные args/kwargs.

*args

Аргументы, передаваемые UDF.

**kwargs

Именованные аргументы, передаваемые UDF.

См. также

pipe_with_schema

Примеры

>>> def cast_str_to_int(lf: pl.LazyFrame, col_name: str) -> pl.LazyFrame:
...     return lf.with_columns(pl.col(col_name).cast(pl.Int64))
>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": ["10", "20", "30", "40"],
...     }
... )
>>> lf.pipe(cast_str_to_int, col_name="b").collect()
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 10  │
│ 2   ┆ 20  │
│ 3   ┆ 30  │
│ 4   ┆ 40  │
└─────┴─────┘

>>> lf = pl.LazyFrame(
...     {
...         "b": [1, 2],
...         "a": [3, 4],
...     }
... )
>>> lf.collect()
shape: (2, 2)
┌─────┬─────┐
│ b   ┆ a   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘
>>> lf.pipe(lambda lf: lf.select(sorted(lf.collect_schema()))).collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 3   ┆ 1   │
│ 4   ┆ 2   │
└─────┴─────┘

pipe_with_schema(
    function: Callable[[LazyFrame,
    Schema],
    LazyFrame],
) → LazyFrame

Позволяет изменять ленивый фрейм на этапе построения плана с учётом разрешённой схемы.

В отличие от pipe, этот метод не выполняет function немедленно, а делает это только на этапе построения плана. Благодаря этому можно динамически изменять ленивый фрейм, используя разрешённую схему входных данных. Это также означает, что любые исключения, возникающие в function, будут выданы только на этапе построения плана.

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

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

движок:В памятиПотоковыйРаспределённый

Параметры:

function

Вызываемый объект; получит фрейм в качестве первого параметра, а разрешённую схему — в качестве второго параметра.

См. также

pipe

Примеры

>>> def cast_to_float_if_necessary(
...     lf: pl.LazyFrame, schema: pl.Schema
... ) -> pl.LazyFrame:
...     required_casts = [
...         pl.col(name).cast(pl.Float64)
...         for name, dtype in schema.items()
...         if not dtype.is_float()
...     ]
...     return lf.with_columns(required_casts)
>>> lf = pl.LazyFrame(
...     {"a": [1.0, 2.0], "b": ["1.0", "2.5"], "c": [2.0, 3.0]},
...     schema={"a": pl.Float64, "b": pl.String, "c": pl.Float32},
... )
>>> lf.pipe_with_schema(cast_to_float_if_necessary).collect()
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ f64 ┆ f64 ┆ f32 │
╞═════╪═════╪═════╡
│ 1.0 ┆ 1.0 ┆ 2.0 │
│ 2.0 ┆ 2.5 ┆ 3.0 │
└─────┴─────┴─────┘

pivot(
    on: ColumnNameOrSelector | Sequence[ColumnNameOrSelector],
    on_columns: Sequence[Any] | Series | DataFrame,
    *,
    index: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    values: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    aggregate_function: PivotAgg | Expr | None = None,
    maintain_order: bool = False,
    separator: str = '_',
    column_naming: Literal['auto',
    'combine'] = 'auto',
) → LazyFrame

Создаёт сводную таблицу в стиле электронной таблицы в виде DataFrame.

движок:В памятиЧастично потоковый

Параметры:

on

Столбец(ы), значения которых будут использованы в качестве новых столбцов выходного DataFrame.

on_columns

Какие комбинации значений будут учитываться в выходной таблице.

index

Столбец(ы), которые сохраняются при переходе от входных данных к выходным. В выходном DataFrame будет одна строка для каждой уникальной комбинации значений index. Если задано None, будут использованы все оставшиеся столбцы, не указанные в on и values. Необходимо указать хотя бы один из параметров index и values.

values

Существующий столбец(ы) со значениями, которые будут помещены в новые столбцы вместо индекса. Если указана агрегация, она будет вычисляться по этим значениям. Если задано None, будут использованы все оставшиеся столбцы, не указанные в on и index. Необходимо указать хотя бы один из параметров index и values.

aggregate_function

Выберите один из вариантов:

• None: агрегация не выполняется; будет вызвана ошибка, если в группе несколько значений.
• Предопределённая строка агрегатной функции: одна из {‘min’, ‘max’, ‘first’, ‘last’, ‘sum’, ‘mean’, ‘median’, ‘len’, ‘item’}
• Выражение для выполнения агрегации. Выражение может обращаться только к данным соответствующих столбцов ‘values’, созданных сводной таблицей, через pl.element().

maintain_order

Гарантирует, что значения index будут отсортированы в порядке обнаружения.

separator

Используется в качестве разделителя в именах создаваемых столбцов, если имеется несколько столбцов values.

column_naming{‘auto’, ‘combine’}

Определяет способ формирования имён результирующих столбцов.

• ‘auto’: значение по умолчанию; при наличии нескольких столбцов используется разделитель

  values, в противном случае используются только имена on_columns.

• ‘combine’: Always combine the values columns’ names with

  имена on_columns.

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

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

Возвращает:

DataFrame

Примечания

В некоторых других фреймворках эта операция может быть известна как pivot_wider.

Примеры

С помощью pivot можно преобразовать DataFrame из «длинного» формата в «широкий».

Например, предположим, что у нас есть DataFrame с результатами тестов учащихся, где каждая строка соответствует отдельному тесту.

>>> df = pl.DataFrame(
...     {
...         "name": ["Cady", "Cady", "Karen", "Karen"],
...         "subject": ["maths", "physics", "maths", "physics"],
...         "test_1": [98, 99, 61, 58],
...         "test_2": [100, 100, 60, 60],
...     }
... )
>>> df
shape: (4, 4)
┌───────┬─────────┬────────┬────────┐
│ name  ┆ subject ┆ test_1 ┆ test_2 │
│ ---   ┆ ---     ┆ ---    ┆ ---    │
│ str   ┆ str     ┆ i64    ┆ i64    │
╞═══════╪═════════╪════════╪════════╡
│ Cady  ┆ maths   ┆ 98     ┆ 100    │
│ Cady  ┆ physics ┆ 99     ┆ 100    │
│ Karen ┆ maths   ┆ 61     ┆ 60     │
│ Karen ┆ physics ┆ 58     ┆ 60     │
└───────┴─────────┴────────┴────────┘

Используя pivot, можно преобразовать данные так, чтобы на каждого учащегося приходилась одна строка, разные предметы стали столбцами, а результаты test_1 были представлены в виде значений:

>>> df.lazy().pivot(
...     "subject",
...     on_columns=["maths", "physics"],
...     index="name",
...     values="test_1",
... ).collect()  
shape: (2, 3)
┌───────┬───────┬─────────┐
│ name  ┆ maths ┆ physics │
│ ---   ┆ ---   ┆ ---     │
│ str   ┆ i64   ┆ i64     │
╞═══════╪═══════╪═════════╡
│ Cady  ┆ 98    ┆ 99      │
│ Karen ┆ 61    ┆ 58      │
└───────┴───────┴─────────┘

Также можно использовать селекторы — здесь в сводную таблицу включены результаты всех тестов:

>>> import polars.selectors as cs
>>> df.lazy().pivot(
...     "subject",
...     on_columns=["maths", "physics"],
...     values=cs.starts_with("test"),
... ).collect()  
shape: (2, 5)
┌───────┬──────────────┬────────────────┬──────────────┬────────────────┐
│ name  ┆ test_1_maths ┆ test_1_physics ┆ test_2_maths ┆ test_2_physics │
│ ---   ┆ ---          ┆ ---            ┆ ---          ┆ ---            │
│ str   ┆ i64          ┆ i64            ┆ i64          ┆ i64            │
╞═══════╪══════════════╪════════════════╪══════════════╪════════════════╡
│ Cady  ┆ 98           ┆ 99             ┆ 100          ┆ 100            │
│ Karen ┆ 61           ┆ 58             ┆ 60           ┆ 60             │
└───────┴──────────────┴────────────────┴──────────────┴────────────────┘

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

>>> lf = pl.LazyFrame(
...     {
...         "ix": [1, 1, 2, 2, 1, 2],
...         "col": ["a", "a", "a", "a", "b", "b"],
...         "foo": [0, 1, 2, 2, 7, 1],
...         "bar": [0, 2, 0, 0, 9, 4],
...     }
... )
>>> lf.pivot(
...     "col", on_columns=["a", "b"], index="ix", aggregate_function="sum"
... ).collect()  
shape: (2, 5)
┌─────┬───────┬───────┬───────┬───────┐
│ ix  ┆ foo_a ┆ foo_b ┆ bar_a ┆ bar_b │
│ --- ┆ ---   ┆ ---   ┆ ---   ┆ ---   │
│ i64 ┆ i64   ┆ i64   ┆ i64   ┆ i64   │
╞═════╪═══════╪═══════╪═══════╪═══════╡
│ 1   ┆ 1     ┆ 7     ┆ 2     ┆ 9     │
│ 2   ┆ 4     ┆ 1     ┆ 0     ┆ 4     │
└─────┴───────┴───────┴───────┴───────┘

Также можно передать пользовательскую функцию агрегации, используя polars.element():

>>> lf = pl.LazyFrame(
...     {
...         "col1": ["a", "a", "a", "b", "b", "b"],
...         "col2": ["x", "x", "x", "x", "y", "y"],
...         "col3": [6, 7, 3, 2, 5, 7],
...     }
... )
>>> lf.pivot(
...     "col2",
...     on_columns=["x", "y"],
...     index="col1",
...     values="col3",
...     aggregate_function=pl.element().tanh().mean(),
... ).collect()  
shape: (2, 3)
┌──────┬──────────┬──────────┐
│ col1 ┆ x        ┆ y        │
│ ---  ┆ ---      ┆ ---      │
│ str  ┆ f64      ┆ f64      │
╞══════╪══════════╪══════════╡
│ a    ┆ 0.998347 ┆ null     │
│ b    ┆ 0.964028 ┆ 0.999954 │
└──────┴──────────┴──────────┘

profile(
    *,
    type_coercion: bool = True,
    predicate_pushdown: bool = True,
    projection_pushdown: bool = True,
    simplify_expression: bool = True,
    no_optimization: bool = False,
    slice_pushdown: bool = True,
    comm_subplan_elim: bool = True,
    comm_subexpr_elim: bool = True,
    cluster_with_columns: bool = True,
    collapse_joins: bool = True,
    show_plot: bool = False,
    truncate_nodes: int = 0,
    figsize: tuple[int,
    int] = (18,
    8,
), engine: EngineType = 'auto', optimizations: QueryOptFlags = (), **_kwargs: Any, ) → tuple[DataFrame, DataFrame]

Профилирует LazyFrame.

Устарело с версии 1.43.0: Этот метод предназначался для старого движка, работающего в памяти, но начиная с версии 2.0 Polars по умолчанию использует потоковый движок. Из-за параллельной работы потокового движка сведения о профилировании, полученные этой функцией, могут вводить в заблуждение.

Выполняет запрос и возвращает кортеж, содержащий материализованный DataFrame и DataFrame со сведениями о профилировании каждого выполненного узла.

Единица измерения времени — микросекунда.

Параметры:

type_coercion

Выполнять оптимизацию приведения типов.

Устарело с версии 1.30.0: Используйте параметры optimizations.

predicate_pushdown

Выполнять оптимизацию проталкивания предикатов.

Устарело с версии 1.30.0: Используйте параметры optimizations.

projection_pushdown

Выполнять оптимизацию проталкивания проекций.

Устарело с версии 1.30.0: Используйте параметры optimizations.

simplify_expression

Выполнять оптимизацию упрощения выражений.

Устарело с версии 1.30.0: Используйте параметры optimizations.

no_optimization

Отключить некоторые оптимизации.

Устарело с версии 1.30.0: Используйте параметры optimizations.

slice_pushdown

Оптимизация проталкивания срезов.

Устарело с версии 1.30.0: Используйте параметры optimizations.

comm_subplan_elim

Попытаться кэшировать разветвляющиеся под планы, возникающие при соединении таблицы с самой собой или при объединении.

Устарело с версии 1.30.0: Используйте параметры optimizations.

comm_subexpr_elim

Общие подвыражения будут кэшироваться и использоваться повторно.

Устарело с версии 1.30.0: Используйте параметры optimizations.

cluster_with_columns

Объединять последовательные независимые вызовы with_columns

Устарело с версии 1.30.0: Используйте параметры optimizations.

collapse_joins

Объединять соединение и фильтры в более быстрое соединение

Устарело с версии 1.30.0: Используйте параметры optimizations.

show_plot

Показывать диаграмму Ганта с результатами профилирования

truncate_nodes

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

figsize

Размер графика профилирования в формате matplotlib figsize

engine

Выбрать движок для обработки запроса (по умолчанию "auto"). Также можно передать экземпляр Engine. Поддерживаются следующие названия движков:

• "auto": использовать движок, заданный с помощью Config.set_engine_affinity или переменной окружения POLARS_ENGINE_AFFINITY; если она не задана, использовать "in-memory" (это значение по умолчанию может измениться в будущем выпуске).
• "in-memory": использовать движок, работающий в памяти; это движок по умолчанию.
• "streaming": использовать потоковый движок, который обрабатывает запросы пакетами, снижая нагрузку на память и часто превосходя по производительности движок, работающий в памяти. В ближайшее время он станет движком Polars по умолчанию.
• "gpu": использовать движок CUDA GPU (требуются графический процессор Nvidia и cudf-polars). Для детальной настройки (например, выбора устройства в системах с несколькими GPU) передайте объект GPUEngine.

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

Примечание

Режим GPU считается нестабильным. Не все запросы будут успешно выполняться на GPU, однако, если выполнение не поддерживается, они должны прозрачно переключаться на движок по умолчанию.

Запуск с POLARS_VERBOSE=1 позволяет узнать, что запрос переключился на другой движок и по какой причине.

optimizations

Этапы оптимизации, выполняемые при оптимизации запроса.

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

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

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [1, 2, 3, 4, 5, 6],
...         "c": [6, 5, 4, 3, 2, 1],
...     }
... )
>>> lf.group_by("a", maintain_order=True).agg(pl.all().sum()).sort(
...     "a"
... ).profile()  
(shape: (3, 3)
 ┌─────┬─────┬─────┐
 │ a   ┆ b   ┆ c   │
 │ --- ┆ --- ┆ --- │
 │ str ┆ i64 ┆ i64 │
 ╞═════╪═════╪═════╡
 │ a   ┆ 4   ┆ 10  │
 │ b   ┆ 11  ┆ 10  │
 │ c   ┆ 6   ┆ 1   │
 └─────┴─────┴─────┘,
 shape: (3, 3)
 ┌─────────────────────────┬───────┬──────┐
 │ node                    ┆ start ┆ end  │
 │ ---                     ┆ ---   ┆ ---  │
 │ str                     ┆ u64   ┆ u64  │
 ╞═════════════════════════╪═══════╪══════╡
 │ optimization            ┆ 0     ┆ 5    │
 │ group_by_partitioned(a) ┆ 5     ┆ 470  │
 │ sort(a)                 ┆ 475   ┆ 1964 │
 └─────────────────────────┴───────┴──────┘)

quantile(
    quantile: float | Expr,
    interpolation: QuantileMethod = 'nearest',
) → LazyFrame

Вычисляет агрегатное значение квантиля для столбцов LazyFrame.

движок:В памятиЧастично потоковый

Параметры:

quantile

Квантиль от 0.0 до 1.0.

interpolation{‘nearest’, ‘higher’, ‘lower’, ‘midpoint’, ‘linear’, ‘equiprobable’}

Метод интерполяции.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.quantile(0.7).collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ f64 ┆ f64 │
╞═════╪═════╡
│ 3.0 ┆ 1.0 │
└─────┴─────┘

remote(
    context: pc.ClientContext | None = None,
    *,
    plan_type: pc._typing.PlanTypePreference = 'dot',
    n_retries: int = 0,
    engine: pc._typing.Engine = 'auto',
    scaling_mode: pc._typing.ScalingMode = 'auto',
) → pc.LazyFrameRemote

Выполняет запрос удалённо в Polars Cloud.

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

Подробнее — в публикации с анонсом

Параметры:

context

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

plan_type: {‘plain’, ‘dot’}

Определяет, нужно ли выводить диаграмму в формате dot или текстовое представление логического плана.

n_retries:

Количество повторных попыток выполнения этапа в случае сбоя.

engine: {‘auto’, ‘streaming’, ‘in-memory’}

Подсказка Polars о предпочтительном движке. Это предпочтение необязательно должно соблюдаться.

scaling_mode: {‘auto’, ‘single-node’, ‘distributed’}

Если задано значение auto, запрос, для которого режим масштабирования явно не указан через remote().distributed() или remote().single_node(), будет выполняться в распределённом режиме, если в кластере больше одного узла.

Примеры

Выполнение запроса в облачном экземпляре.

>>> lf = pl.LazyFrame([1, 2, 3]).sum()
>>> in_progress = lf.remote().execute(blocking=False)  
>>> # do some other work
>>> in_progress.await_result()  
shape: (1, 1)
┌──────────┐
│ column_0 │
│ ---      │
│ i64      │
╞══════════╡
│ 6        │
└──────────┘

Явное выполнение запроса в распределённом режиме.

>>> lf = (
...     pl.scan_parquet("s3://my_bucket/").group_by("key").agg(pl.sum("values"))
... )
>>> result = lf.remote().distributed().execute()  
shape: (1, 1)
┌──────────┐
│ column_0 │
│ ---      │
│ i64      │
╞══════════╡
│ 6        │
└──────────┘

remove(
    *predicates: IntoExprColumn | Iterable[IntoExprColumn] | bool | list[bool] | np.ndarray[Any,
    Any],
    **constraints: Any,
) → LazyFrame

Удаляет строки, соответствующие заданным выражениям-предикатам.

Исходный порядок оставшихся строк сохраняется.

Сохраняются строки, для которых предикат фильтрации не принимает значение True (в том числе строки, для которых предикат принимает значение null).

движок:В памятиПотоковыйРаспределённый

Параметры:

predicates

Выражение(я), результатом которых является булева Series. Если передано несколько предикатов, они объединяются с помощью & (логическое И), поэтому строка удаляется, только если каждый предикат для неё принимает значение True.

constraints

Фильтры столбцов; используйте name = value, чтобы фильтровать столбцы по переданному значению. Каждое ограничение действует так же, как pl.col(name).eq(value), и неявно объединяется с другими условиями фильтрации с помощью &.

См. также

filter

Примечания

Если вы переходите с Pandas и выполняете фильтрацию на основе сравнения двух или более столбцов, обратите внимание, что в Polars любое сравнение с участием значений null возвращает результат null, а не логическое значение True или False. Поэтому такие строки не удаляются. Чтобы избежать неожиданного поведения, правильно обрабатывайте нулевые значения (см. примеры ниже).

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "foo": [2, 3, None, 4, 0],
...         "bar": [5, 6, None, None, 0],
...         "ham": ["a", "b", None, "c", "d"],
...     }
... )

Удаление строк, соответствующих условию:

>>> lf.remove(
...     pl.col("bar") >= 5,
... ).collect()
shape: (3, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ i64  ┆ str  │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
│ 4    ┆ null ┆ c    │
│ 0    ┆ 0    ┆ d    │
└──────┴──────┴──────┘

Удаление строк по нескольким условиям, объединённым операторами И/ИЛИ:

>>> lf.remove(
...     (pl.col("foo") >= 0) & (pl.col("bar") >= 0),
... ).collect()
shape: (2, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ i64  ┆ str  │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
│ 4    ┆ null ┆ c    │
└──────┴──────┴──────┘

>>> lf.remove(
...     (pl.col("foo") >= 0) | (pl.col("bar") >= 0),
... ).collect()
shape: (1, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ i64  ┆ str  │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
└──────┴──────┴──────┘

Передача нескольких ограничений с помощью синтаксиса *args:

>>> lf.remove(
...     pl.col("ham").is_not_null(),
...     pl.col("bar") >= 0,
... ).collect()
shape: (2, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ i64  ┆ str  │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
│ 4    ┆ null ┆ c    │
└──────┴──────┴──────┘

Передача ограничений с помощью синтаксиса **kwargs:

>>> lf.remove(foo=0, bar=0).collect()
shape: (4, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ i64  ┆ str  │
╞══════╪══════╪══════╡
│ 2    ┆ 5    ┆ a    │
│ 3    ┆ 6    ┆ b    │
│ null ┆ null ┆ null │
│ 4    ┆ null ┆ c    │
└──────┴──────┴──────┘

Удаление строк путём сравнения двух столбцов друг с другом; в данном случае удаляются строки, в которых значения этих столбцов не равны (используется ne_missing, чтобы считать нулевые значения равными при сравнении):

>>> lf.remove(
...     pl.col("foo").ne_missing(pl.col("bar")),
... ).collect()
shape: (2, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ i64  ┆ str  │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
│ 0    ┆ 0    ┆ d    │
└──────┴──────┴──────┘

rename(
    mapping: Mapping[str,
    str] | Callable[[str],
    str],
    *,
    strict: bool = True,
) → LazyFrame

Переименовывает столбцы.

движок:В памятиПотоковыйРаспределённый

Параметры:

mapping

Пары «ключ-значение», задающие соответствие старых имён новым, или функция, которая принимает старое имя и возвращает новое.

strict

Проверять, что все имена столбцов существуют в текущей схеме, и вызывать исключение, если какие-либо из них отсутствуют. (Обратите внимание: этот параметр ничего не делает, если в mapping передана функция.)

См. также

Expr.name.replace

Примечания

Если существующие имена меняются местами (например, ‘A’ указывает на ‘B’, а ‘B’ — на ‘A’), Polars отключает проталкивание проекций и предикатов на этом узле.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.rename({"foo": "apple"}).collect()
shape: (3, 3)
┌───────┬─────┬─────┐
│ apple ┆ bar ┆ ham │
│ ---   ┆ --- ┆ --- │
│ i64   ┆ i64 ┆ str │
╞═══════╪═════╪═════╡
│ 1     ┆ 6   ┆ a   │
│ 2     ┆ 7   ┆ b   │
│ 3     ┆ 8   ┆ c   │
└───────┴─────┴─────┘
>>> lf.rename(lambda column_name: "c" + column_name[1:]).collect()
shape: (3, 3)
┌─────┬─────┬─────┐
│ coo ┆ car ┆ cam │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 2   ┆ 7   ┆ b   │
│ 3   ┆ 8   ┆ c   │
└─────┴─────┴─────┘

reverse() → LazyFrame

Обращает порядок строк в DataFrame.

движок:В памятиЧастично потоковый

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "key": ["a", "b", "c"],
...         "val": [1, 2, 3],
...     }
... )
>>> lf.reverse().collect()
shape: (3, 2)
┌─────┬─────┐
│ key ┆ val │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ c   ┆ 3   │
│ b   ┆ 2   │
│ a   ┆ 1   │
└─────┴─────┘

rolling(
    index_column: IntoExpr,
    *,
    period: str | timedelta,
    offset: str | timedelta | None = None,
    closed: ClosedInterval = 'right',
    group_by: IntoExpr | Iterable[IntoExpr] | None = None,
) → LazyGroupBy

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

В отличие от group_by_dynamic, границы окон определяются отдельными значениями и не имеют постоянного интервала. Для постоянных интервалов используйте LazyFrame.group_by_dynamic().

Если задан временной ряд <t_0, t_1, ..., t_n>, по умолчанию создаются следующие окна:

• (t_0 - период, t_0]
• (t_1 - период, t_1]
• …
• (t_n - период, t_n]

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

• (t_0 + смещение, t_0 + смещение + период]
• (t_1 + смещение, t_1 + смещение + период]
• …
• (t_n + смещение, t_n + смещение + период]

Аргументы period и offset задаются либо объектом timedelta, либо строкой, составленной по следующему синтаксису:

• 1ns (1 наносекунда)
• 1us (1 микросекунда)
• 1ms (1 миллисекунда)
• 1s (1 секунда)
• 1m (1 минута)
• 1h (1 час)
• 1d (1 календарный день)
• 1w (1 календарная неделя)
• 1mo (1 календарный месяц)
• 1q (1 календарный квартал)
• 1y (1 календарный год)
• 1i (1 индекс)

Или комбинируйте их: “3d12h4m25s” # 3 дня, 12 часов, 4 минуты и 25 секунд

Под «календарным днём» подразумевается соответствующее время следующего дня (который может длиться не 24 часа из-за перехода на летнее время). То же относится к «календарной неделе», «календарному месяцу», «календарному кварталу» и «календарному году».

движок:В памятиЧастично потоковыйЧастично распределённый

Изменено в версии 0.20.14: Параметр by переименован в group_by.

Параметры:

index_column

Столбец, используемый для группировки по временному окну. Обычно имеет тип Date/Datetime. Этот столбец должен быть отсортирован по возрастанию (или, если указан group_by, должен быть отсортирован по возрастанию внутри каждой группы).

При группировке по скользящему окну на индексах тип данных должен быть одним из следующих: {UInt32, UInt64, Int32, Int64}. Обратите внимание, что первые три типа временно приводятся к Int64, поэтому для повышения производительности используйте столбец Int64.

period

Длина окна — должна быть неотрицательной.

offset

Смещение окна. По умолчанию — -period.

closed{‘right’, ‘left’, ‘both’, ‘none’}

Определяет, какие границы временного интервала включаются в него.

group_by

Дополнительно группировать по этому столбцу/этим столбцам

Возвращает:

LazyGroupBy

Объект, для которого можно вызвать .agg, чтобы выполнить агрегацию по группам. Результат будет отсортирован по index_column (но обратите внимание: если переданы столбцы group_by, сортировка будет выполняться только внутри каждой группы).

См. также

group_by_dynamic

Примеры

>>> dates = [
...     "2020-01-01 13:45:48",
...     "2020-01-01 16:42:13",
...     "2020-01-01 16:45:09",
...     "2020-01-02 18:12:48",
...     "2020-01-03 19:45:32",
...     "2020-01-08 23:16:43",
... ]
>>> df = pl.LazyFrame({"dt": dates, "a": [3, 7, 5, 9, 2, 1]}).with_columns(
...     pl.col("dt").str.strptime(pl.Datetime).set_sorted()
... )
>>> out = (
...     df.rolling(index_column="dt", period="2d")
...     .agg(
...         pl.sum("a").alias("sum_a"),
...         pl.min("a").alias("min_a"),
...         pl.max("a").alias("max_a"),
...     )
...     .collect()
... )
>>> out
shape: (6, 4)
┌─────────────────────┬───────┬───────┬───────┐
│ dt                  ┆ sum_a ┆ min_a ┆ max_a │
│ ---                 ┆ ---   ┆ ---   ┆ ---   │
│ datetime[μs]        ┆ i64   ┆ i64   ┆ i64   │
╞═════════════════════╪═══════╪═══════╪═══════╡
│ 2020-01-01 13:45:48 ┆ 3     ┆ 3     ┆ 3     │
│ 2020-01-01 16:42:13 ┆ 10    ┆ 3     ┆ 7     │
│ 2020-01-01 16:45:09 ┆ 15    ┆ 3     ┆ 7     │
│ 2020-01-02 18:12:48 ┆ 24    ┆ 3     ┆ 9     │
│ 2020-01-03 19:45:32 ┆ 11    ┆ 2     ┆ 9     │
│ 2020-01-08 23:16:43 ┆ 1     ┆ 1     ┆ 1     │
└─────────────────────┴───────┴───────┴───────┘

property schema: Schema

Возвращает упорядоченное соответствие имён столбцов их типам данных.

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

Определение схемы LazyFrame может быть затратной операцией. Для определения схемы рекомендуется использовать collect_schema(). Это свойство существует только для симметрии с классом DataFrame.

См. также

collect_schema

Schema

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.schema  
Schema({'foo': Int64, 'bar': Float64, 'ham': String})

select(
    *exprs: IntoExpr | Iterable[IntoExpr],
    **named_exprs: IntoExpr,
) → LazyFrame

Выбирает столбцы из этого LazyFrame.

движок:В памятиПотоковыйРаспределённый

Параметры:

*exprs

Выбираемый столбец(ы), задаваемый позиционными аргументами. Принимает выражения. Строки интерпретируются как имена столбцов, а другие аргументы, не являющиеся выражениями, — как литералы.

**named_exprs

Дополнительные выбираемые столбцы, задаваемые именованными аргументами. Столбцы будут переименованы в соответствии с переданными именами аргументов.

Примеры

Передайте имя столбца, чтобы выбрать его.

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.select("foo").collect()
shape: (3, 1)
┌─────┐
│ foo │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
└─────┘

Несколько столбцов можно выбрать, передав список их имён.

>>> lf.select(["foo", "bar"]).collect()
shape: (3, 2)
┌─────┬─────┐
│ foo ┆ bar │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 6   │
│ 2   ┆ 7   │
│ 3   ┆ 8   │
└─────┴─────┘

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

>>> lf.select(pl.col("foo"), pl.col("bar") + 1).collect()
shape: (3, 2)
┌─────┬─────┐
│ foo ┆ bar │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 7   │
│ 2   ┆ 8   │
│ 3   ┆ 9   │
└─────┴─────┘

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

>>> lf.select(
...     threshold=pl.when(pl.col("foo") > 2).then(10).otherwise(0)
... ).collect()
shape: (3, 1)
┌───────────┐
│ threshold │
│ ---       │
│ i32       │
╞═══════════╡
│ 0         │
│ 0         │
│ 10        │
└───────────┘

select_seq(
    *exprs: IntoExpr | Iterable[IntoExpr],
    **named_exprs: IntoExpr,
) → LazyFrame

Выбирает столбцы из этого LazyFrame.

Все выражения выполняются последовательно, а не параллельно. Используйте этот метод, если вычисления для каждого выражения не требуют больших затрат.

движок:В памятиПотоковыйРаспределённый

Параметры:

*exprs

Выбираемый столбец(ы), задаваемый позиционными аргументами. Принимает выражения. Строки интерпретируются как имена столбцов, а другие аргументы, не являющиеся выражениями, — как литералы.

**named_exprs

Дополнительные выбираемые столбцы, задаваемые именованными аргументами. Столбцы будут переименованы в соответствии с переданными именами аргументов.

См. также

select

serialize(
    file: IOBase | str | Path | None = None,
    *,
    format: SerializationFormat = 'binary',
) → bytes | str | None

Сериализует логический план этого LazyFrame в файл или строку в формате JSON.

Параметры:

file

Путь к файлу, в который следует записать результат. Если задано None (значение по умолчанию), результат возвращается в виде строки.

format

Формат сериализации. Возможные варианты:

• "binary": сериализация в двоичный формат (bytes). Значение по умолчанию.
• "json": сериализация в формат JSON (string) (устарело).

См. также

LazyFrame.deserialize

Примечания

Сериализация не является стабильной между версиями Polars: LazyFrame, сериализованный в одной версии Polars, может не десериализоваться в другой.

Примеры

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

>>> lf = pl.LazyFrame({"a": [1, 2, 3]}).sum()
>>> bytes = lf.serialize()

Позднее байты можно десериализовать обратно в LazyFrame.

>>> import io
>>> pl.LazyFrame.deserialize(io.BytesIO(bytes)).collect()
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 6   │
└─────┘

set_sorted(
    column: str | list[str],
    *more_columns: str,
    descending: bool | list[bool] = False,
    nulls_last: bool | list[bool] = False,
) → LazyFrame

Помечает столбец как отсортированный.

Это может ускорить последующие операции.

движок:В памятиПотоковыйРаспределённый

Параметры:

column

Отсортированный столбец (столбцы)

more_columns

Столбцы, отсортированные после column.

descending

Определяет, отсортирован ли столбец по убыванию.

nulls_last

Определяет, находятся ли нулевые значения в конце.

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

Если данные НЕ отсортированы, это может привести к неверным результатам! Используйте с осторожностью!

shift(
    n: int | IntoExprColumn = 1,
    *,
    fill_value: IntoExpr | None = None,
) → LazyFrame

Сдвигает значения на заданное количество индексов.

движок:В памятиПотоковый

Параметры:

n

Количество индексов для сдвига вперёд. Если передано отрицательное значение, значения сдвигаются в противоположном направлении.

fill_value

Заполнить результирующие значения null этим значением. Принимает скалярное выражение. Входные данные, не являющиеся выражениями, разбираются как литералы.

Примечания

Этот метод аналогичен операции LAG в SQL, когда значение n положительно. При отрицательном значении n он аналогичен LEAD.

Примеры

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

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [5, 6, 7, 8],
...     }
... )
>>> lf.shift().collect()
shape: (4, 2)
┌──────┬──────┐
│ a    ┆ b    │
│ ---  ┆ ---  │
│ i64  ┆ i64  │
╞══════╪══════╡
│ null ┆ null │
│ 1    ┆ 5    │
│ 2    ┆ 6    │
│ 3    ┆ 7    │
└──────┴──────┘

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

>>> lf.shift(-2).collect()
shape: (4, 2)
┌──────┬──────┐
│ a    ┆ b    │
│ ---  ┆ ---  │
│ i64  ┆ i64  │
╞══════╪══════╡
│ 3    ┆ 7    │
│ 4    ┆ 8    │
│ null ┆ null │
│ null ┆ null │
└──────┴──────┘

Укажите fill_value, чтобы заполнить результирующие значения null.

>>> lf.shift(-2, fill_value=100).collect()
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 3   ┆ 7   │
│ 4   ┆ 8   │
│ 100 ┆ 100 │
│ 100 ┆ 100 │
└─────┴─────┘

show(
    limit: int | None = 5,
    *,
    ascii_tables: bool | None = None,
    decimal_separator: str | None = None,
    thousands_separator: str | bool | None = None,
    float_precision: int | None = None,
    fmt_float: FloatFmt | None = None,
    fmt_str_lengths: int | None = None,
    fmt_table_cell_list_len: int | None = None,
    tbl_cell_alignment: Alignment | None = None,
    tbl_cell_numeric_alignment: Alignment | None = None,
    tbl_cols: int | None = None,
    tbl_column_data_type_inline: bool | None = None,
    tbl_dataframe_shape_below: bool | None = None,
    tbl_formatting: TableFormatNames | None = None,
    tbl_hide_column_data_types: bool | None = None,
    tbl_hide_column_names: bool | None = None,
    tbl_hide_dtype_separator: bool | None = None,
    tbl_hide_dataframe_shape: bool | None = None,
    tbl_width_chars: int | None = None,
    trim_decimal_zeros: bool | None = True,
) → None

Показывает первые n строк.

Параметры:

limitint

Количество строк для отображения. Если передано None, возникает ValueError. Это сделано для соответствия сигнатуре DataFrame.show().

ascii_tablesbool

Использовать символы ASCII для отображения границ таблицы. Установите False, чтобы вернуться к стилю форматирования UTF8_FULL_CONDENSED по умолчанию. Дополнительные сведения см. в разделе Config.set_ascii_tables().

decimal_separatorstr

Задаёт символ десятичного разделителя. Дополнительные сведения см. в разделе Config.set_decimal_separator().

thousands_separatorstr, bool

Задаёт символ разделителя групп разрядов. Дополнительные сведения см. в разделе Config.set_thousands_separator().

float_precisionint

Количество десятичных знаков для отображения значений с плавающей точкой. Дополнительные сведения см. в разделе Config.set_float_precision().

fmt_float{“mixed”, “full”}

Управляет отображением значений с плавающей точкой. Дополнительные сведения см. в разделе Config.set_fmt_float(). Поддерживаются следующие варианты:

• «mixed»: ограничивает количество десятичных знаков и использует научную нотацию для больших и малых значений.
• «full»: выводит значение с плавающей точкой с полной точностью.

fmt_str_lengthsint

Количество символов для отображения строковых значений. Дополнительные сведения см. в разделе Config.set_fmt_str_lengths().

fmt_table_cell_list_lenint

Количество элементов для отображения значений типа List. Дополнительные сведения см. в разделе Config.set_fmt_table_cell_list_len().

tbl_cell_alignmentstr

Задаёт выравнивание ячеек таблицы. Дополнительные сведения см. в разделе Config.set_tbl_cell_alignment(). Поддерживаются следующие варианты:

• «LEFT»: выравнивание по левому краю
• «CENTER»: выравнивание по центру
• «RIGHT»: выравнивание по правому краю

tbl_cell_numeric_alignmentstr

Задаёт выравнивание ячеек таблицы для числовых столбцов. Дополнительные сведения см. в разделе Config.set_tbl_cell_numeric_alignment(). Поддерживаются следующие варианты:

• «LEFT»: выравнивание по левому краю
• «CENTER»: выравнивание по центру
• «RIGHT»: выравнивание по правому краю

tbl_colsint

Количество столбцов для отображения. Дополнительные сведения см. в разделе Config.set_tbl_cols().

tbl_column_data_type_inlinebool

Размещает тип данных в одной строке с именем столбца (справа, в скобках). Дополнительные сведения см. в разделе Config.set_tbl_column_data_type_inline().

tbl_dataframe_shape_belowbool

Выводит информацию о форме DataFrame под данными при отображении таблиц. Дополнительные сведения см. в разделе Config.set_tbl_dataframe_shape_below().

tbl_formattingstr

Задаёт стиль форматирования таблицы. Дополнительные сведения см. в разделе Config.set_tbl_formatting(). Поддерживаются следующие варианты:

• «ASCII_FULL»: ASCII, все границы и линии, включая разделители строк.
• «ASCII_FULL_CONDENSED»: как ASCII_FULL, но с уменьшенными интервалами между строками.
• «ASCII_NO_BORDERS»: ASCII, без границ.
• «ASCII_BORDERS_ONLY»: ASCII, только границы.
• «ASCII_BORDERS_ONLY_CONDENSED»: ASCII, только границы, уменьшенные интервалы между строками.
• «ASCII_HORIZONTAL_ONLY»: ASCII, только горизонтальные линии.
• «ASCII_MARKDOWN»: формат Markdown (для усечённых значений используются многоточия ASCII).
• «MARKDOWN»: формат Markdown (для усечённых значений используются многоточия UTF-8).
• «UTF8_FULL»: UTF-8, все границы и линии, включая разделители строк.
• «UTF8_FULL_CONDENSED»: как UTF8_FULL, но с уменьшенными интервалами между строками.
• «UTF8_NO_BORDERS»: UTF-8, без границ.
• «UTF8_BORDERS_ONLY»: UTF-8, только границы.
• «UTF8_HORIZONTAL_ONLY»: UTF-8, только горизонтальные линии.
• «NOTHING»: без границ и других линий.

tbl_hide_column_data_typesbool

Скрывает типы данных столбцов таблицы (i64, f64, str и т. д.). Дополнительные сведения см. в разделе Config.set_tbl_hide_column_data_types().

tbl_hide_column_namesbool

Скрывает имена столбцов таблицы. Дополнительные сведения см. в разделе Config.set_tbl_hide_column_names().

tbl_hide_dtype_separatorbool

Скрывает разделитель «—» между именами столбцов и их типами. Дополнительные сведения см. в разделе Config.set_tbl_hide_dtype_separator().

tbl_hide_dataframe_shapebool

Скрывает информацию о форме DataFrame при отображении таблиц. Дополнительные сведения см. в разделе Config.set_tbl_hide_dataframe_shape().

tbl_width_charsint

Задаёт максимальную ширину таблицы в символах. Дополнительные сведения см. в разделе Config.set_tbl_width_chars().

trim_decimal_zerosbool

Удаляет завершающие нули из значений типа Decimal. Дополнительные сведения см. в разделе Config.set_trim_decimal_zeros().

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

• Этот метод не сохраняет ленивый режим фрейма и collect итоговый результат. Эта операция может оказаться ресурсоёмкой.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4, 5, 6],
...         "b": [7, 8, 9, 10, 11, 12],
...     }
... )
>>> lf.show()
shape: (5, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 7   │
│ 2   ┆ 8   │
│ 3   ┆ 9   │
│ 4   ┆ 10  │
│ 5   ┆ 11  │
└─────┴─────┘
>>> lf.show(2)
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 7   │
│ 2   ┆ 8   │
└─────┴─────┘

show_graph(
    *,
    optimized: bool = True,
    show: bool = True,
    output_path: str | Path | None = None,
    raw_output: bool = False,
    figsize: tuple[float,
    float] = (16.0,
    12.0,
), type_coercion: bool = True, _type_check: bool = True, predicate_pushdown: bool = True, projection_pushdown: bool = True, simplify_expression: bool = True, slice_pushdown: bool = True, comm_subplan_elim: bool = True, comm_subexpr_elim: bool = True, cluster_with_columns: bool = True, collapse_joins: bool = True, engine: EngineType = 'auto', plan_stage: PlanStage | None = None, _check_order: bool = True, optimizations: QueryOptFlags = (), ) → str | None

Показывает график плана запроса.

Обратите внимание, что для визуализации необходимо установить Graphviz (если он ещё не установлен, его можно скачать здесь: https://graphviz.org/download).

Параметры:

optimized

Оптимизировать план запроса.

show

Показать рисунок.

output_path

Сохранить рисунок на диск.

raw_output

Вернуть синтаксис dot. Нельзя использовать вместе с show и/или output_path.

figsize

Передаётся в matplotlib, если show == True.

type_coercion

Выполнить оптимизацию приведения типов.

Устарело с версии 1.30.0: Используйте параметры optimizations.

predicate_pushdown

Выполнить оптимизацию проталкивания предикатов.

Устарело с версии 1.30.0: Используйте параметры optimizations.

projection_pushdown

Выполнить оптимизацию проталкивания проекций.

Устарело с версии 1.30.0: Используйте параметры optimizations.

simplify_expression

Выполнить оптимизацию упрощения выражений.

Устарело с версии 1.30.0: Используйте параметры optimizations.

slice_pushdown

Оптимизация проталкивания срезов.

Устарело с версии 1.30.0: Используйте параметры optimizations.

comm_subplan_elim

Попытается кэшировать ветвящиеся подзапросы, возникающие при самосоединениях или объединениях.

Устарело с версии 1.30.0: Используйте параметры optimizations.

comm_subexpr_elim

Общие подвыражения будут кэшироваться и использоваться повторно.

Устарело с версии 1.30.0: Используйте параметры optimizations.

cluster_with_columns

Объединяет последовательные независимые вызовы with_columns.

Устарело с версии 1.30.0: Используйте параметры optimizations.

collapse_joins

Объединяет соединение и фильтры в более быстрое соединение.

Устарело с версии 1.30.0: Используйте параметры optimizations.

engine

Выберите движок для обработки запроса (по умолчанию "auto"). Также можно передать экземпляр Engine. Поддерживаются следующие имена движков:

• "auto": использовать движок, заданный с помощью Config.set_engine_affinity или переменной среды POLARS_ENGINE_AFFINITY; если она не задана, использовать "in-memory" (это значение по умолчанию может измениться в будущих выпусках).
• "in-memory": использовать движок в памяти; это движок по умолчанию.
• "streaming": использовать потоковый движок, который обрабатывает запросы пакетами, снижая нагрузку на память и зачастую превосходя по скорости движок в памяти. В ближайшее время он станет движком Polars по умолчанию.
• "gpu": использовать движок CUDA GPU (требуется графический процессор Nvidia и cudf-polars). Для более точной настройки (например, выбора устройства в системах с несколькими GPU) передайте объект GPUEngine.

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

Примечание

Режим GPU считается нестабильным. Не все запросы будут успешно выполняться на GPU, однако при отсутствии поддержки выполнения они должны автоматически переключаться на движок по умолчанию.

Запуск с POLARS_VERBOSE=1 позволяет узнать, когда запрос переключается на другой движок и почему.

plan_stage{‘ir’, ‘physical’}

Выберите отображаемый этап. Сейчас отдельный физический этап есть только у потокового движка; у остальных движков IR и физический этап совпадают.

optimizations

Набор оптимизаций, учитываемых при оптимизации запроса.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [1, 2, 3, 4, 5, 6],
...         "c": [6, 5, 4, 3, 2, 1],
...     }
... )
>>> lf.group_by("a", maintain_order=True).agg(pl.all().sum()).sort(
...     "a"
... ).show_graph(plan_stage="ir")  

sink_batches(
    function: Callable[[DataFrame],
    bool | None],
    *,
    chunk_size: int | None = None,
    maintain_order: bool = True,
    lazy: bool = False,
    engine: EngineType = 'auto',
    optimizations: QueryOptFlags = (,
), ) → LazyFrame | None

Выполняет запрос и вызывает пользовательскую функцию для каждого готового пакета.

В некоторых случаях это позволяет передавать потоком результаты, размер которых превышает объём оперативной памяти.

движок:ПотоковыйРаспределённый

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

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

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

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

Параметры:

function

Функция, вызываемая для готового пакета. Если функция возвращает True, это означает, что дальнейшие результаты не нужны, и позволяет досрочно завершить обработку.

chunk_size

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

maintain_order

Сохранять порядок обработки данных. Если задать False, выполнение будет немного быстрее.

lazy: bool

Ожидать вызова collect перед началом выполнения.

engine

Выберите движок для обработки запроса (по умолчанию "auto"). Также можно передать экземпляр Engine. Поддерживаются следующие имена движков:

• "auto": использовать движок, заданный с помощью Config.set_engine_affinity или переменной среды POLARS_ENGINE_AFFINITY; если она не задана, использовать "streaming".
• "in-memory": использовать перед записью движок в памяти; это движок по умолчанию.
• "streaming": использовать потоковый движок, который обрабатывает запросы пакетами, снижая нагрузку на память и зачастую превосходя по скорости движок в памяти. В ближайшее время он станет движком Polars по умолчанию.
• "gpu": использовать движок CUDA GPU (требуется графический процессор Nvidia и cudf-polars). Для более точной настройки передайте объект GPUEngine.

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

optimizations

Этапы оптимизации, выполняемые при оптимизации запроса.

Не влияет на результат, если для lazy задано значение True.

Примеры

>>> lf = pl.scan_csv("/path/to/my_larger_than_ram_file.csv")  
>>> lf.sink_batches(lambda df: print(df))  

sink_csv(
    path: str | Path | IO[bytes] | IO[str] | PartitionBy,
    *,
    include_bom: bool = False,
    compression: Literal['uncompressed',
    'gzip',
    'zstd'] = 'uncompressed',
    compression_level: int | None = None,
    check_extension: bool = True,
    include_header: bool = True,
    separator: str = ',',
    line_terminator: str = '\n',
    quote_char: str = '"',
    batch_size: int = 1024,
    datetime_format: str | None = None,
    date_format: str | None = None,
    time_format: str | None = None,
    float_scientific: bool | None = None,
    float_precision: int | None = None,
    decimal_comma: bool = False,
    null_value: str | None = None,
    quote_style: CsvQuoteStyle | None = None,
    maintain_order: bool = True,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
    sync_on_close: SyncOnCloseMethod | None = None,
    mkdir: bool = False,
    lazy: bool = False,
    engine: EngineType = 'auto',
    optimizations: QueryOptFlags = (,
), ) → LazyFrame | None

Выполняет запрос в потоковом режиме и записывает результат в файл CSV.

Это позволяет записывать на диск потоковые результаты, размер которых превышает объём оперативной памяти.

движок:ПотоковыйРаспределённый

Параметры:

path

Путь к файлу, в который следует записать данные.

include_bom

Добавлять ли BOM UTF-8 в выходной файл CSV.

compression

Формат сжатия.

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

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

compression_level

Уровень сжатия, обычно от 0 до 9, либо None, чтобы позволить движку выбрать уровень самостоятельно.

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

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

check_extension

Проверять ли соответствие имени файла настройкам сжатия. Возникает ошибка, если для сжатия задано значение «uncompressed», а имя файла оканчивается на одно из значений («.gz», «.zst», «.zstd»), либо если compression != ‘uncompressed’, но расширение файла не соответствует настройке. Применяется только к файлам, заданным путём.

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

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

include_header

Добавлять ли заголовок в выходной файл CSV.

separator

Разделять поля CSV этим символом.

line_terminator

Строка, используемая для завершения каждой строки.

quote_char

Байт, используемый в качестве символа кавычек.

batch_size

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

datetime_format

Строка формата со спецификаторами, определёнными в Rust-крейте chrono. Если формат не задан, точность дробной части секунды по умолчанию определяется по максимальной единице времени среди столбцов Datetime фрейма (если они есть).

date_format

Строка формата со спецификаторами, определёнными в Rust-крейте chrono.

time_format

Строка формата со спецификаторами, определёнными в Rust-крейте chrono.

float_scientific

Всегда использовать научную нотацию (true), никогда её не использовать (false) или выбирать автоматически (None) для типов данных с плавающей точкой.

float_precision

Количество записываемых десятичных знаков; применяется к обоим типам данных с плавающей точкой.

decimal_comma

Использовать запятую вместо точки в качестве десятичного разделителя. При необходимости значения с плавающей точкой будут заключены в кавычки; чтобы изменить это поведение, задайте разделитель полей.

null_value

Строка, представляющая значения null (по умолчанию — пустая строка).

quote_style{‘necessary’, ‘always’, ‘non_numeric’, ‘never’}

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

• necessary (по умолчанию): кавычки ставятся вокруг полей только при необходимости. Они необходимы, если поле содержит кавычку, разделитель или символ завершения записи. Кавычки также необходимы при записи пустой записи (которую невозможно отличить от записи с одним пустым полем). Это вариант по умолчанию.
• always: кавычки ставятся вокруг каждого поля. Всегда.
• never: кавычки не ставятся вокруг полей никогда, даже если это приводит к некорректным данным CSV (например, если строки с разделителем остаются без кавычек).
• non_numeric: кавычки ставятся вокруг всех нечисловых полей. То есть при записи поля, которое не разбирается как корректное число с плавающей точкой или целое число, кавычки используются, даже если они не являются строго необходимыми.

maintain_order

Сохранять порядок обработки данных. Если задать False, выполнение будет немного быстрее.

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

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

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.

sync_on_close: { None, ‘data’, ‘all’ }

Синхронизировать ли данные с диском перед закрытием файла.

• None — не выполнять синхронизацию.
• data — синхронизировать содержимое файла.
• all — синхронизировать содержимое файла и метаданные.

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

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

mkdir: bool

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

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

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

lazy: bool

Ожидать вызова collect перед началом выполнения.

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

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

engine

Выберите движок для обработки запроса (по умолчанию "auto"). Также можно передать экземпляр Engine. Поддерживаются следующие имена движков:

• "auto": использовать движок, заданный с помощью Config.set_engine_affinity или переменной среды POLARS_ENGINE_AFFINITY; если она не задана, использовать "streaming".
• "in-memory": использовать перед записью движок в памяти; это движок по умолчанию.
• "streaming": использовать потоковый движок, который обрабатывает запросы пакетами, снижая нагрузку на память и зачастую превосходя по скорости движок в памяти. В ближайшее время он станет движком Polars по умолчанию.
• "gpu": использовать движок CUDA GPU (требуется графический процессор Nvidia и cudf-polars). Для более точной настройки передайте объект GPUEngine.

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

optimizations

Этапы оптимизации, выполняемые при оптимизации запроса.

Не влияет на результат, если для lazy задано значение True.

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

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

Возвращает:

DataFrame

См. также

PartitionBy

Примеры

>>> lf = pl.scan_csv("/path/to/my_larger_than_ram_file.csv")  
>>> lf.sink_csv("out.csv")  

Запись в объект BytesIO.

>>> import io
>>> buf = io.BytesIO()  
>>> pl.LazyFrame({"x": [1, 2, 1]}).sink_csv(buf)  

Разбиение на разделы в стиле секционирования Hive:

>>> pl.LazyFrame({"x": [1, 2, 1], "y": [3, 4, 5]}).sink_csv(
...     pl.PartitionBy("./out/", key="x"),
...     mkdir=True
... )  

sink_delta(
    target: str | Path | deltalake.DeltaTable,
    *,
    mode: Literal['error',
    'append',
    'overwrite',
    'ignore',
    'merge'] = 'error',
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    delta_write_options: dict[str,
    Any] | None = None,
    delta_merge_options: dict[str,
    Any] | None = None,
    engine: EngineType = 'auto',
    optimizations: QueryOptFlags = (,
), ) → deltalake.table.TableMerger | None

Записать DataFrame как таблицу Delta.

движок:ПотоковыйРаспределённый

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

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

Параметры:

target

URI таблицы или объект DeltaTable.

mode{‘error’, ‘append’, ‘overwrite’, ‘ignore’, ‘merge’}

Способ обработки существующих данных.

• Если задано ‘error’, вызвать ошибку, если таблица уже существует (по умолчанию).
• Если задано ‘append’, добавить новые данные.
• Если задано ‘overwrite’, заменить таблицу новыми данными.
• Если задано ‘ignore’, ничего не записывать, если таблица уже существует.
• Если задано ‘merge’, вернуть объект TableMerger для объединения данных DataFrame с существующими данными.

storage_options

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

• Список поддерживаемых параметров хранения для S3 см. здесь.
• Список поддерживаемых параметров хранения для GCS см. здесь.
• Список поддерживаемых параметров хранения для Azure см. здесь.

credential_provider

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

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

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

delta_write_options

Дополнительные именованные аргументы при записи таблицы Delta Lake. Список поддерживаемых параметров записи см. здесь.

delta_merge_options

Именованные аргументы, необходимые для MERGE таблицы Delta Lake. Список поддерживаемых параметров объединения см. здесь.

engine

Выберите движок для обработки запроса (по умолчанию "auto"). Также можно передать экземпляр Engine. Поддерживаются следующие имена движков:

• "auto": использовать движок, заданный с помощью Config.set_engine_affinity или переменной среды POLARS_ENGINE_AFFINITY; если она не задана, использовать "streaming".
• "in-memory": перед записью использовать движок с обработкой в памяти; это движок по умолчанию.
• "streaming": использовать потоковый движок, который обрабатывает запросы пакетами, снижая нагрузку на память и зачастую превосходя по производительности движок с обработкой в памяти. Вскоре он станет движком Polars по умолчанию.
• "gpu": использовать движок CUDA GPU (требуется GPU Nvidia и cudf-polars). Для тонкой настройки передайте объект GPUEngine.

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

optimizations

Этапы оптимизации, выполняемые при оптимизации запроса.

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

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

Исключения:

TypeError

Если DataFrame содержит неподдерживаемые типы данных.

ArrowInvalidError

Если DataFrame содержит типы данных, которые нельзя привести к примитивному типу.

TableNotFoundError

Если таблица Delta не существует и выполняется действие MERGE.

Примечания

Типы данных Polars Null и Time не поддерживаются спецификацией протокола Delta и приведут к возникновению TypeError. При записи столбцы с типом данных Categorical преобразуются в обычные строки (не категориальные).

Столбцы Polars всегда допускают значения NULL. Чтобы записать данные в таблицу Delta со столбцами, не допускающими значения NULL, необходимо передать пользовательскую схему pyarrow в delta_write_options. См. последний пример ниже.

Примеры

Записать в таблицу Delta Lake большой набор данных, который не помещается в память.

>>> lf = pl.scan_parquet(
...     "/path/to/my_larger_than_ram_file.parquet"
... )  
>>> table_path = "/path/to/delta-table/"
>>> lf.sink_delta(table_path)  

Записать DataFrame в локальную файловую систему в виде таблицы Delta Lake.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> table_path = "/path/to/delta-table/"
>>> df.lazy().sink_delta(table_path)  

Добавить данные в существующую таблицу Delta Lake в локальной файловой системе. Обратите внимание: операция завершится ошибкой, если схема новых данных не совпадает со схемой существующей таблицы.

>>> df.lazy().sink_delta(table_path, mode="append")  

Перезаписать таблицу Delta Lake, создав новую версию. Если схемы новых и старых данных совпадают, указывать schema_mode не требуется.

>>> existing_table_path = "/path/to/delta-table/"
>>> df.lazy().sink_delta(
...     existing_table_path,
...     mode="overwrite",
...     delta_write_options={"schema_mode": "overwrite"},
... )  

Записать DataFrame в облачное объектное хранилище, например S3, в виде таблицы Delta Lake.

>>> table_path = "s3://bucket/prefix/to/delta-table/"
>>> df.lazy().sink_delta(
...     table_path,
...     storage_options={
...         "AWS_REGION": "THE_AWS_REGION",
...         "AWS_ACCESS_KEY_ID": "THE_AWS_ACCESS_KEY_ID",
...         "AWS_SECRET_ACCESS_KEY": "THE_AWS_SECRET_ACCESS_KEY",
...     },
... )  

Записать DataFrame в виде таблицы Delta Lake со столбцами, не допускающими значения NULL.

>>> import pyarrow as pa
>>> existing_table_path = "/path/to/delta-table/"
>>> df.lazy().sink_delta(
...     existing_table_path,
...     delta_write_options={
...         "schema": pa.schema([pa.field("foo", pa.int64(), nullable=False)])
...     },
... )  

Записать DataFrame в виде таблицы Delta Lake со сжатием zstd. Сведения обо всех именованных аргументах delta_write_options см. в документации deltalake здесь, а в частности о свойствах Writer — здесь.

>>> import deltalake
>>> df.lazy().sink_delta(
...     table_path,
...     delta_write_options={
...         "writer_properties": deltalake.WriterProperties(compression="zstd"),
...     },
... )  

Объединить DataFrame с существующей таблицей Delta Lake. Сведения обо всех методах TableMerger см. в документации deltalake здесь.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> table_path = "/path/to/delta-table/"
>>> (
...     df.lazy()
...     .sink_delta(
...         "table_path",
...         mode="merge",
...         delta_merge_options={
...             "predicate": "s.foo = t.foo",
...             "source_alias": "s",
...             "target_alias": "t",
...         },
...     )
...     .when_matched_update_all()
...     .when_not_matched_insert_all()
...     .execute()
... )  

sink_iceberg(
    target: str | pyiceberg.table.Table,
    *,
    mode: Literal['append',
    'overwrite'],
    schema_mode: Literal['merge',
    'overwrite'] | None = None,
    snapshot_properties: dict[str,
    str] | None = None,
    catalog: pyiceberg.catalog.Catalog | polars.io.iceberg.IcebergCatalogConfig | None = None,
    storage_options: StorageOptionsDict | None = None,
    engine: EngineType = 'auto',
) → DataFrame

Записать LazyFrame в таблицу Iceberg.

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

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

Параметры:

target

Объект таблицы PyIceberg или строковый идентификатор «namespace.table_name».

mode{‘append’, ‘overwrite’}

Способ обработки существующих данных.

• Если задано ‘append’, добавить новые данные.
• Если задано ‘overwrite’, заменить таблицу новыми данными.

schema_mode{‘merge’, ‘overwrite’}

Способ обработки различий между входящей схемой и схемой таблицы.

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

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

• Если задано ‘merge’, расширить схему таблицы входящими полями и совместимыми преобразованиями типов.
• Если задано ‘overwrite’, заменить схему таблицы входящей схемой. Для этого требуется mode='overwrite'.
• Если задано None, потребовать совпадения схем.

snapshot_properties

Пользовательские свойства для добавления к сводке снимка Iceberg.

catalog

Каталог PyIceberg, из которого следует загрузить таблицу, если в target был передан идентификатор таблицы.

storage_options

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

Дополнительная информация доступна здесь.

engine

Движок, используемый для создания строк локальным средством записи pyiceberg.

Возвращает:

DataFrame

Содержит путь к новым метаданным.

sink_ipc(
    path: str | Path | IO[bytes] | PartitionBy,
    *,
    compression: IpcCompression | None = 'uncompressed',
    compat_level: CompatLevel | None = None,
    record_batch_size: int | None = None,
    maintain_order: bool = True,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
    sync_on_close: SyncOnCloseMethod | None = None,
    mkdir: bool = False,
    lazy: bool = False,
    engine: EngineType = 'auto',
    optimizations: QueryOptFlags = (,
), _record_batch_statistics: bool = False, sinked_paths_callback: SinkedPathsCallback | None = None, ) → LazyFrame | None

Вычислить запрос в потоковом режиме и записать результат в файл IPC.

Это позволяет записывать на диск потоковые результаты, размер которых превышает объём оперативной памяти.

движок:ПотоковыйРаспределённый

Параметры:

path

Путь к файлу, в который следует записать данные.

compression{‘uncompressed’, ‘lz4’, ‘zstd’}

Выберите «zstd» для эффективного сжатия. Выберите «lz4» для быстрого сжатия и распаковки.

compat_level

Уровень совместимости, используемый при экспорте структур данных Polars. Уровень совместимости по умолчанию подходит большинству пользователей. Для максимальной совместимости используйте pl.CompatLevel.oldest(). pl.CompatLevel.newest() использует наивысший поддерживаемый уровень совместимости, но считается нестабильным и может измениться без необходимости считать это несовместимым изменением.

record_batch_size

Размер пакетов записей в количестве строк.

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

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

maintain_order

Сохранять порядок обработки данных. Если задать False, выполнение будет немного быстрее.

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

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

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.

sync_on_close: { None, ‘data’, ‘all’ }

Синхронизировать данные с диском перед закрытием файла.

• None не выполняет синхронизацию.
• data синхронизирует содержимое файла.
• all синхронизирует содержимое файла и метаданные.

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

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

mkdir: bool

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

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

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

lazy: bool

Не начинать выполнение, пока не будет вызван collect.

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

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

engine

Выберите движок для обработки запроса (по умолчанию "auto"). Также можно передать экземпляр Engine. Поддерживаются следующие имена движков:

• "auto": использовать движок, заданный с помощью Config.set_engine_affinity или переменной среды POLARS_ENGINE_AFFINITY; если она не задана, использовать "streaming".
• "in-memory": перед записью использовать движок с обработкой в памяти; это движок по умолчанию.
• "streaming": использовать потоковый движок, который обрабатывает запросы пакетами, снижая нагрузку на память и зачастую превосходя по производительности движок с обработкой в памяти. Вскоре он станет движком Polars по умолчанию.
• "gpu": в настоящее время не поддерживается для этого средства записи.

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

Примечание

В настоящее время движок GPU не поддерживается.

optimizations

Этапы оптимизации, выполняемые при оптимизации запроса.

Это не влияет на результат, если для lazy задано значение True.

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

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

sinked_paths_callback

Вызываемый объект, которому передаются сведения о путях записи.

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

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

Возвращает:

DataFrame

См. также

PartitionBy

Примеры

>>> lf = pl.scan_csv("/path/to/my_larger_than_ram_file.csv")  
>>> lf.sink_ipc("out.arrow")  

Запись в объект BytesIO.

>>> import io
>>> buf = io.BytesIO()  
>>> pl.LazyFrame({"x": [1, 2, 1]}).sink_ipc(buf)  

Разбить на разделы в стиле секционирования Hive:

>>> pl.LazyFrame({"x": [1, 2, 1], "y": [3, 4, 5]}).sink_ipc(
...     pl.PartitionBy("./out/", key="x"),
...     mkdir=True
... )  

sink_ndjson(
    path: str | Path | IO[bytes] | IO[str] | PartitionBy,
    *,
    compression: Literal['uncompressed',
    'gzip',
    'zstd'] = 'uncompressed',
    compression_level: int | None = None,
    check_extension: bool = True,
    maintain_order: bool = True,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
    sync_on_close: SyncOnCloseMethod | None = None,
    mkdir: bool = False,
    lazy: bool = False,
    engine: EngineType = 'auto',
    optimizations: QueryOptFlags = (,
), ) → LazyFrame | None

Вычислить запрос в потоковом режиме и записать результат в файл NDJSON.

Это позволяет записывать на диск потоковые результаты, размер которых превышает объём оперативной памяти.

движок:ПотоковыйРаспределённый

Параметры:

path

Путь к файлу, в который следует записать данные.

compression

Формат сжатия.

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

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

compression_level

Используемый уровень сжатия, обычно от 0 до 9, или None, чтобы позволить движку выбрать значение.

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

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

check_extension

Проверять, соответствует ли имя файла настройкам сжатия. Будет вызвана ошибка, если для сжатия задано ‘uncompressed’, а имя файла заканчивается на одно из значений (“.gz”, “.zst”, “.zstd”), либо если для сжатия задано значение, отличное от ‘uncompressed’, а расширение файла не соответствует ему. Применяется только в том случае, если указан путь к файлу.

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

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

maintain_order

Сохранять порядок обработки данных. Если задать False, выполнение будет немного быстрее.

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

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

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.

sync_on_close: { None, ‘data’, ‘all’ }

Синхронизировать данные с диском перед закрытием файла.

• None не выполняет синхронизацию.
• data синхронизирует содержимое файла.
• all синхронизирует содержимое файла и метаданные.

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

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

mkdir: bool

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

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

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

lazy: bool

Не начинать выполнение, пока не будет вызван collect.

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

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

engine

Выберите движок для обработки запроса (по умолчанию "auto"). Также можно передать экземпляр Engine. Поддерживаются следующие имена движков:

• "auto": использовать движок, заданный с помощью Config.set_engine_affinity или переменной среды POLARS_ENGINE_AFFINITY; если она не задана, использовать "streaming".
• "in-memory": перед записью использовать движок с обработкой в памяти; это движок по умолчанию.
• "streaming": использовать потоковый движок, который обрабатывает запросы пакетами, снижая нагрузку на память и зачастую превосходя по производительности движок с обработкой в памяти. Вскоре он станет движком Polars по умолчанию.
• "gpu": использовать движок CUDA GPU (требуется GPU Nvidia и cudf-polars). Для тонкой настройки передайте объект GPUEngine.

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

optimizations

Этапы оптимизации, выполняемые при оптимизации запроса.

Это не влияет на результат, если для lazy задано значение True.

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

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

Возвращает:

DataFrame

См. также

PartitionBy

Примеры

>>> lf = pl.scan_csv("/path/to/my_larger_than_ram_file.csv")  
>>> lf.sink_ndjson("out.ndjson")  

Запись в объект BytesIO.

>>> import io
>>> buf = io.BytesIO()  
>>> pl.LazyFrame({"x": [1, 2, 1]}).sink_ndjson(buf)  

Разбить на разделы в стиле секционирования Hive:

>>> pl.LazyFrame({"x": [1, 2, 1], "y": [3, 4, 5]}).sink_ndjson(
...     pl.PartitionBy("./out/", key="x"),
...     mkdir=True
... )  

sink_parquet(
    path: str | Path | IO[bytes] | PartitionBy,
    *,
    compression: ParquetCompression = 'zstd',
    compression_level: int | None = None,
    statistics: bool | str | dict[str,
    bool] = True,
    row_group_size: int | None = None,
    data_page_size: int | None = None,
    maintain_order: bool = True,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
    sync_on_close: SyncOnCloseMethod | None = None,
    metadata: ParquetMetadata | None = None,
    arrow_schema: ArrowSchemaExportable | None = None,
    mkdir: bool = False,
    lazy: bool = False,
    engine: EngineType = 'auto',
    optimizations: QueryOptFlags = (,
), sinked_paths_callback: SinkedPathsCallback | None = None, ) → LazyFrame | None

Вычислить запрос в потоковом режиме и записать результат в файл Parquet.

Это позволяет записывать на диск потоковые результаты, размер которых превышает объём оперативной памяти.

движок:Потоковая обработкаРаспределённая обработка

Параметры:

path

Путь к файлу, в который следует записать данные.

compression{‘lz4’, ‘uncompressed’, ‘snappy’, ‘gzip’, ‘brotli’, ‘zstd’}

Выберите «zstd» для хорошего сжатия. Выберите «lz4» для быстрого сжатия и распаковки. Выберите «snappy», если вам нужны более надёжные гарантии обратной совместимости при работе со старыми средствами чтения Parquet.

compression_level

Уровень сжатия. Чем выше уровень сжатия, тем меньше размер файлов на диске.

• «gzip»: минимальный уровень: 0, максимальный уровень: 9, по умолчанию: 6.
• «brotli»: минимальный уровень: 0, максимальный уровень: 11, по умолчанию: 1.
• «zstd»: минимальный уровень: 1, максимальный уровень: 22, по умолчанию: 3.

statistics

Записывать статистику в заголовки Parquet. Это поведение используется по умолчанию.

Возможные значения:

• True: включить набор статистических данных по умолчанию (значение по умолчанию). Некоторые статистические данные могут быть отключены.
• False: отключить все статистические данные
• «full»: вычислить и записать все доступные статистические данные.

• { "statistic-key": True / False, ... }. Доступные ключи:

  • «min»: минимальное значение столбца (по умолчанию: True)
  • «max»: максимальное значение столбца (по умолчанию: True)
  • «distinct_count»: количество уникальных значений в столбце (по умолчанию: False)
  • «null_count»: количество значений null в столбце (по умолчанию: True)

row_group_size

Размер групп строк в количестве строк. Если указано None (значение по умолчанию), используются чанки DataFrame. Запись меньшими чанками может снизить нагрузку на память и повысить скорость записи.

data_page_size

Ограничение размера отдельных страниц данных. Если значение не указано, по умолчанию используется 1024 * 1024 байт.

maintain_order

Сохранять порядок обработки данных. Если задать False, работа будет немного быстрее.

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

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

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.

sync_on_close: { None, ‘data’, ‘all’ }

Синхронизировать данные с диском перед закрытием файла.

• None не выполняет синхронизацию.
• data синхронизирует содержимое файла.
• all синхронизирует содержимое файла и метаданные.

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

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

metadata

Словарь или функция обратного вызова для добавления пар «ключ — значение» в метаданные файла Parquet.

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

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

arrow_schema

Пользовательская схема Arrow для записи в файл. Это позволяет задать пользовательскую схему и метаданные на уровне полей. Имена и типы данных должны совпадать.

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

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

mkdir: bool

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

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

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

lazy: bool

Отложить выполнение до вызова collect.

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

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

engine

Выбрать движок для обработки запроса (по умолчанию "auto"). Также можно передать экземпляр Engine. Поддерживаются следующие названия движков:

• "auto": использовать движок, заданный с помощью Config.set_engine_affinity или переменной окружения POLARS_ENGINE_AFFINITY; если она не задана, использовать "streaming".
• "in-memory": перед записью использовать движок для обработки в памяти; это движок по умолчанию.
• "streaming": использовать потоковый движок, который обрабатывает запросы пакетами, снижая нагрузку на память и зачастую превосходя по производительности движок для обработки в памяти. Вскоре он станет движком Polars по умолчанию.
• "gpu": использовать движок GPU CUDA (требуется GPU Nvidia и cudf-polars). Для детальной настройки передайте объект GPUEngine.

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

optimizations

Этапы оптимизации, выполняемые при оптимизации запроса.

Не влияет на результат, если для lazy задано True.

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

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

sinked_paths_callback

Функция обратного вызова, которой передаются сведения о путях, в которые записаны данные.

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

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

Возвращает:

DataFrame

См. также

PartitionBy

Примеры

>>> lf = pl.scan_csv("/path/to/my_larger_than_ram_file.csv")  
>>> lf.sink_parquet("out.parquet")  

Записать данные в объект BytesIO.

>>> import io
>>> buf = io.BytesIO()  
>>> pl.LazyFrame({"x": [1, 2, 1]}).sink_parquet(buf)  

Разбить данные на разделы в стиле секционирования Hive:

>>> pl.LazyFrame({"x": [1, 2, 1], "y": [3, 4, 5]}).sink_parquet(
...     pl.PartitionBy("./out/", key="x"),
...     mkdir=True
... )  

slice(
    offset: int,
    length: int | None = None,
) → LazyFrame

Получить срез этого DataFrame.

движок:В памятиПотоковая обработкаРаспределённая обработка

Параметры:

offset

Начальный индекс. Поддерживается отрицательная индексация.

length

Длина среза. Если задано None, будут выбраны все строки начиная с указанного смещения.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": ["x", "y", "z"],
...         "b": [1, 3, 5],
...         "c": [2, 4, 6],
...     }
... )
>>> lf.slice(1, 2).collect()
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ y   ┆ 3   ┆ 4   │
│ z   ┆ 5   ┆ 6   │
└─────┴─────┴─────┘

sort(
    by: IntoExpr | Iterable[IntoExpr],
    *more_by: IntoExpr,
    descending: bool | Sequence[bool] = False,
    nulls_last: bool | Sequence[bool] = False,
    maintain_order: bool = False,
    multithreaded: bool = True,
) → LazyFrame

Отсортировать LazyFrame по указанным столбцам.

движок:В памятиЧастично распределённая обработка

Параметры:

by

Столбец или столбцы для сортировки. Принимает выражения, в том числе селекторы. Строки интерпретируются как имена столбцов.

*more_by

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

descending

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

nulls_last

Помещать значения null в конец. Можно указать одно логическое значение для всех столбцов или последовательность логических значений для управления сортировкой каждого столбца.

maintain_order

Следует ли сохранять порядок элементов с одинаковыми значениями. Обратите внимание: при true потоковая обработка невозможна, а производительность может снизиться, поскольку для этого требуется стабильная сортировка.

multithreaded

Выполнять сортировку с использованием нескольких потоков.

Примеры

Передайте имя одного столбца, чтобы отсортировать данные по нему.

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, None],
...         "b": [6.0, 5.0, 4.0],
...         "c": ["a", "c", "b"],
...     }
... )
>>> lf.sort("a").collect()
shape: (3, 3)
┌──────┬─────┬─────┐
│ a    ┆ b   ┆ c   │
│ ---  ┆ --- ┆ --- │
│ i64  ┆ f64 ┆ str │
╞══════╪═════╪═════╡
│ null ┆ 4.0 ┆ b   │
│ 1    ┆ 6.0 ┆ a   │
│ 2    ┆ 5.0 ┆ c   │
└──────┴─────┴─────┘

Также поддерживается сортировка по выражениям.

>>> lf.sort(pl.col("a") + pl.col("b") * 2, nulls_last=True).collect()
shape: (3, 3)
┌──────┬─────┬─────┐
│ a    ┆ b   ┆ c   │
│ ---  ┆ --- ┆ --- │
│ i64  ┆ f64 ┆ str │
╞══════╪═════╪═════╡
│ 2    ┆ 5.0 ┆ c   │
│ 1    ┆ 6.0 ┆ a   │
│ null ┆ 4.0 ┆ b   │
└──────┴─────┴─────┘

Чтобы отсортировать данные по нескольким столбцам, передайте список столбцов.

>>> lf.sort(["c", "a"], descending=True).collect()
shape: (3, 3)
┌──────┬─────┬─────┐
│ a    ┆ b   ┆ c   │
│ ---  ┆ --- ┆ --- │
│ i64  ┆ f64 ┆ str │
╞══════╪═════╪═════╡
│ 2    ┆ 5.0 ┆ c   │
│ null ┆ 4.0 ┆ b   │
│ 1    ┆ 6.0 ┆ a   │
└──────┴─────┴─────┘

Или укажите несколько столбцов для сортировки в виде позиционных аргументов.

>>> lf.sort("c", "a", descending=[False, True]).collect()
shape: (3, 3)
┌──────┬─────┬─────┐
│ a    ┆ b   ┆ c   │
│ ---  ┆ --- ┆ --- │
│ i64  ┆ f64 ┆ str │
╞══════╪═════╪═════╡
│ 1    ┆ 6.0 ┆ a   │
│ null ┆ 4.0 ┆ b   │
│ 2    ┆ 5.0 ┆ c   │
└──────┴─────┴─────┘

sql(
    query: str,
    *,
    table_name: str = 'self',
) → LazyFrame

Выполнить SQL-запрос для LazyFrame.

движок:Потоковая обработка

Добавлено в версии 0.20.23.

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

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

Параметры:

query

SQL-запрос для выполнения.

table_name

Необязательное явное имя таблицы, представляющей текущий фрейм (по умолчанию «self»).

См. также

SQLContext

Примечания

• Текущий LazyFrame автоматически регистрируется как таблица в SQLContext под именем «self». Чтобы получить доступ к DataFrame и LazyFrame из текущего пространства имён globals, используйте функцию верхнего уровня pl.sql.
• Для более гибкого управления регистрацией и выполнением используйте объект SQLContext.

Примеры

>>> lf1 = pl.LazyFrame({"a": [1, 2, 3], "b": [6, 7, 8], "c": ["z", "y", "x"]})
>>> lf2 = pl.LazyFrame({"a": [3, 2, 1], "d": [125, -654, 888]})

Выполнить SQL-запрос для LazyFrame:

>>> lf1.sql("SELECT c, b FROM self WHERE a > 1").collect()
shape: (2, 2)
┌─────┬─────┐
│ c   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ y   ┆ 7   │
│ x   ┆ 8   │
└─────┴─────┘

Применить преобразования SQL (переименовав «self» в «frame»), а затем выполнить фильтрацию средствами Polars (операции SQL и нативные операции можно свободно комбинировать):

>>> lf1.sql(
...     query='''
...         SELECT
...             a,
...             (a % 2 == 0) AS a_is_even,
...             (b::float4 / 2) AS "b/2",
...             CONCAT_WS(':', c, c, c) AS c_c_c
...         FROM frame
...         ORDER BY a
...     ''',
...     table_name="frame",
... ).filter(~pl.col("c_c_c").str.starts_with("x")).collect()
shape: (2, 4)
┌─────┬───────────┬─────┬───────┐
│ a   ┆ a_is_even ┆ b/2 ┆ c_c_c │
│ --- ┆ ---       ┆ --- ┆ ---   │
│ i64 ┆ bool      ┆ f32 ┆ str   │
╞═════╪═══════════╪═════╪═══════╡
│ 1   ┆ false     ┆ 3.0 ┆ z:z:z │
│ 2   ┆ true      ┆ 3.5 ┆ y:y:y │
└─────┴───────────┴─────┴───────┘

std(
    ddof: int = 1,
) → LazyFrame

Вычислить стандартное отклонение для столбцов LazyFrame.

движок:В памятиПотоковая обработкаРаспределённая обработка

Параметры:

ddof

«Число степеней свободы»: делитель, используемый при вычислении, равен N - ddof, где N — количество элементов. По умолчанию ddof равен 1.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.std().collect()
shape: (1, 2)
┌──────────┬─────┐
│ a        ┆ b   │
│ ---      ┆ --- │
│ f64      ┆ f64 │
╞══════════╪═════╡
│ 1.290994 ┆ 0.5 │
└──────────┴─────┘
>>> lf.std(ddof=0).collect()
shape: (1, 2)
┌──────────┬──────────┐
│ a        ┆ b        │
│ ---      ┆ ---      │
│ f64      ┆ f64      │
╞══════════╪══════════╡
│ 1.118034 ┆ 0.433013 │
└──────────┴──────────┘

sum() → LazyFrame

Вычислить сумму значений столбцов LazyFrame.

движок:В памятиПотоковая обработкаРаспределённая обработка

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.sum().collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 10  ┆ 5   │
└─────┴─────┘

tail(
    n: int = 5,
) → LazyFrame

Получить последние n строк.

движок:В памятиПотоковая обработкаРаспределённая обработка

Параметры:

n

Количество возвращаемых строк.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4, 5, 6],
...         "b": [7, 8, 9, 10, 11, 12],
...     }
... )
>>> lf.tail().collect()
shape: (5, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 2   ┆ 8   │
│ 3   ┆ 9   │
│ 4   ┆ 10  │
│ 5   ┆ 11  │
│ 6   ┆ 12  │
└─────┴─────┘
>>> lf.tail(2).collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 5   ┆ 11  │
│ 6   ┆ 12  │
└─────┴─────┘

top_k(
    k: int,
    *,
    by: IntoExpr | Iterable[IntoExpr],
    reverse: bool | Sequence[bool] = False,
) → LazyFrame

Вернуть k строк с наибольшими значениями.

Ненулевые элементы всегда имеют приоритет перед элементами null независимо от значения reverse. Порядок результата не гарантируется; если нужно отсортировать результат, вызовите sort() после этой функции.

движок:В памятиПотоковая обработкаРаспределённая обработка

Изменено в версии 1.0.0: Параметр descending переименован в reverse.

Параметры:

k

Количество возвращаемых строк.

by

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

reverse

Выбрать k наименьших элементов столбца или столбцов by (вместо k наибольших). Для отдельных столбцов можно передать последовательность логических значений.

См. также

bottom_k

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [2, 1, 1, 3, 2, 1],
...     }
... )

Получить строки с 4 наибольшими значениями в столбце b.

>>> lf.top_k(4, by="b").collect()
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ b   ┆ 3   │
│ a   ┆ 2   │
│ b   ┆ 2   │
│ b   ┆ 1   │
└─────┴─────┘

Получить строки с 4 наибольшими значениями при сортировке по столбцам b и a.

>>> lf.top_k(4, by=["b", "a"]).collect()
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ b   ┆ 3   │
│ b   ┆ 2   │
│ a   ┆ 2   │
│ c   ┆ 1   │
└─────┴─────┘

unique(
    subset: IntoExpr | Collection[IntoExpr] | None = None,
    *,
    keep: UniqueKeepStrategy = 'any',
    maintain_order: bool = False,
) → LazyFrame

Удалить повторяющиеся строки из этого LazyFrame.

движок:В памятиПотоковая обработкаРаспределённая обработка

Параметры:

subset

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

keep{‘first’, ‘last’, ‘any’, ‘none’}

Указывает, какие повторяющиеся строки следует оставить.

• ‘any’: не гарантирует, какая именно строка будет сохранена.

  Это позволяет выполнить больше оптимизаций.

• ‘none’: не оставлять повторяющиеся строки.
• ‘first’: оставить первую уникальную строку.
• ‘last’: оставить последнюю уникальную строку.

maintain_order

Сохранить порядок строк исходного DataFrame. Это требует больше вычислительных ресурсов. Если задать True, запуск на потоковом движке будет невозможен.

Возвращает:

LazyFrame

LazyFrame с уникальными строками.

Примечания

Если вы используете Pandas, эта операция аналогична pandas.DataFrame.drop_duplicates.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3, 1, 1],
...         "bar": ["a", "a", "a", "x", "x"],
...         "ham": ["b", "b", "b", "y", "y"],
...     }
... )

По умолчанию при определении уникальных строк учитываются все столбцы:

>>> lf.unique(maintain_order=True).collect()
shape: (4, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ a   ┆ b   │
│ 2   ┆ a   ┆ b   │
│ 3   ┆ a   ┆ b   │
│ 1   ┆ x   ┆ y   │
└─────┴─────┴─────┘

Также можно учитывать только подмножество столбцов и выбирать, какую строку оставить при обнаружении дубликатов:

>>> lf.unique(subset="foo", keep="first", maintain_order=True).collect()
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ a   ┆ b   │
│ 2   ┆ a   ┆ b   │
│ 3   ┆ a   ┆ b   │
└─────┴─────┴─────┘
>>> lf.unique(subset="foo", keep="last", maintain_order=True).collect()
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 2   ┆ a   ┆ b   │
│ 3   ┆ a   ┆ b   │
│ 1   ┆ x   ┆ y   │
└─────┴─────┴─────┘
>>> lf.unique(subset="foo", keep="none", maintain_order=True).collect()
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 2   ┆ a   ┆ b   │
│ 3   ┆ a   ┆ b   │
└─────┴─────┴─────┘

Для задания параметра «subset» можно использовать селекторы:

>>> import polars.selectors as cs
>>> lf.unique(subset=cs.string(), maintain_order=True).collect()
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ a   ┆ b   │
│ 1   ┆ x   ┆ y   │
└─────┴─────┴─────┘

В параметре «subset» также можно использовать произвольное выражение; в этом примере для определения уникальности используется часть метки перед символом «:»:

>>> lf = pl.LazyFrame(
...     {
...         "label": ["xx:1", "xx:2", "yy:3", "yy:4"],
...         "value": [100, 200, 300, 400],
...     }
... )
>>> lf.unique(
...     subset=pl.col("label").str.extract(r"^(\w+):"),
...     maintain_order=True,
...     keep="first",
... ).collect()
shape: (2, 2)
┌───────┬───────┐
│ label ┆ value │
│ ---   ┆ ---   │
│ str   ┆ i64   │
╞═══════╪═══════╡
│ xx:1  ┆ 100   │
│ yy:3  ┆ 300   │
└───────┴───────┘

unnest(
    columns: ColumnNameOrSelector | Collection[ColumnNameOrSelector] | None = None,
    *more_columns: ColumnNameOrSelector,
    separator: str | None = None,
) → LazyFrame

Развернуть столбцы struct в отдельные столбцы для каждого из их полей.

Новые столбцы будут вставлены в DataFrame на место столбца struct.

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

движок:В памятиПотоковая обработкаРаспределённая обработка

Параметры:

columns

Имя столбца или имена столбцов struct для разворачивания.

*more_columns

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

separator

Переименовать выходные столбцы, объединив имя столбца struct, разделитель и имя поля.

Примеры

>>> df = pl.LazyFrame(
...     {
...         "before": ["foo", "bar"],
...         "t_a": [1, 2],
...         "t_b": ["a", "b"],
...         "t_c": [True, None],
...         "t_d": [[1, 2], [3]],
...         "after": ["baz", "womp"],
...     }
... ).select("before", pl.struct(pl.col("^t_.$")).alias("t_struct"), "after")
>>> df.collect()
shape: (2, 3)
┌────────┬─────────────────────┬───────┐
│ before ┆ t_struct            ┆ after │
│ ---    ┆ ---                 ┆ ---   │
│ str    ┆ struct[4]           ┆ str   │
╞════════╪═════════════════════╪═══════╡
│ foo    ┆ {1,"a",true,[1, 2]} ┆ baz   │
│ bar    ┆ {2,"b",null,[3]}    ┆ womp  │
└────────┴─────────────────────┴───────┘
>>> df.unnest("t_struct").collect()
shape: (2, 6)
┌────────┬─────┬─────┬──────┬───────────┬───────┐
│ before ┆ t_a ┆ t_b ┆ t_c  ┆ t_d       ┆ after │
│ ---    ┆ --- ┆ --- ┆ ---  ┆ ---       ┆ ---   │
│ str    ┆ i64 ┆ str ┆ bool ┆ list[i64] ┆ str   │
╞════════╪═════╪═════╪══════╪═══════════╪═══════╡
│ foo    ┆ 1   ┆ a   ┆ true ┆ [1, 2]    ┆ baz   │
│ bar    ┆ 2   ┆ b   ┆ null ┆ [3]       ┆ womp  │
└────────┴─────┴─────┴──────┴───────────┴───────┘

Развернуть все столбцы struct, вызвав метод без аргументов:

>>> df.unnest().collect()
shape: (2, 6)
┌────────┬─────┬─────┬──────┬───────────┬───────┐
│ before ┆ t_a ┆ t_b ┆ t_c  ┆ t_d       ┆ after │
│ ---    ┆ --- ┆ --- ┆ ---  ┆ ---       ┆ ---   │
│ str    ┆ i64 ┆ str ┆ bool ┆ list[i64] ┆ str   │
╞════════╪═════╪═════╪══════╪═══════════╪═══════╡
│ foo    ┆ 1   ┆ a   ┆ true ┆ [1, 2]    ┆ baz   │
│ bar    ┆ 2   ┆ b   ┆ null ┆ [3]       ┆ womp  │
└────────┴─────┴─────┴──────┴───────────┴───────┘

>>> df = pl.LazyFrame(
...     {
...         "before": ["foo", "bar"],
...         "t_a": [1, 2],
...         "t_b": ["a", "b"],
...         "t_c": [True, None],
...         "t_d": [[1, 2], [3]],
...         "after": ["baz", "womp"],
...     }
... ).select(
...     "before",
...     pl.struct(pl.col("^t_.$").name.map(lambda t: t[2:])).alias("t"),
...     "after",
... )
>>> df.unnest("t", separator="::").collect()
shape: (2, 6)
┌────────┬──────┬──────┬──────┬───────────┬───────┐
│ before ┆ t::a ┆ t::b ┆ t::c ┆ t::d      ┆ after │
│ ---    ┆ ---  ┆ ---  ┆ ---  ┆ ---       ┆ ---   │
│ str    ┆ i64  ┆ str  ┆ bool ┆ list[i64] ┆ str   │
╞════════╪══════╪══════╪══════╪═══════════╪═══════╡
│ foo    ┆ 1    ┆ a    ┆ true ┆ [1, 2]    ┆ baz   │
│ bar    ┆ 2    ┆ b    ┆ null ┆ [3]       ┆ womp  │
└────────┴──────┴──────┴──────┴───────────┴───────┘

unpivot(
    on: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    *,
    index: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    variable_name: str | None = None,
    value_name: str | None = None,
    streamable: bool = True,
) → LazyFrame

Преобразовать DataFrame из широкого формата в длинный.

Столбцы-идентификаторы при этом можно оставить.

Эта функция позволяет преобразовать DataFrame в формат, где один или несколько столбцов являются переменными-идентификаторами (индексом), а все остальные столбцы, считающиеся измеряемыми переменными (on), «разворачиваются» по оси строк, оставляя только два столбца, не являющихся идентификаторами: ‘variable’ и ‘value’.

движок:В памятиПотоковая обработкаРаспределённая обработка

Параметры:

on

Столбец или столбцы, селекторы для выбора переменных-значений; если on пуст, столбцы использоваться не будут. Если задано None (значение по умолчанию), будут использоваться все столбцы, отсутствующие в index.

index

Столбец или столбцы, селекторы для выбора переменных-идентификаторов.

variable_name

Имя столбца variable. По умолчанию — «variable».

value_name

Имя столбца value. По умолчанию — «value».

streamable

устарел

Примечания

Если вы используете pandas, эта операция аналогична pandas.DataFrame.melt, но index используется вместо id_vars, а on — вместо value_vars. В других библиотеках эта операция может называться pivot_longer.

Порядок строк в результате не определён.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": ["x", "y", "z"],
...         "b": [1, 3, 5],
...         "c": [2, 4, 6],
...     }
... )
>>> import polars.selectors as cs
>>> lf.unpivot(cs.numeric(), index="a").collect()
shape: (6, 3)
┌─────┬──────────┬───────┐
│ a   ┆ variable ┆ value │
│ --- ┆ ---      ┆ ---   │
│ str ┆ str      ┆ i64   │
╞═════╪══════════╪═══════╡
│ x   ┆ b        ┆ 1     │
│ y   ┆ b        ┆ 3     │
│ z   ┆ b        ┆ 5     │
│ x   ┆ c        ┆ 2     │
│ y   ┆ c        ┆ 4     │
│ z   ┆ c        ┆ 6     │
└─────┴──────────┴───────┘

update(
    other: LazyFrame,
    on: str | Sequence[str] | None = None,
    how: Literal['left',
    'inner',
    'full'] = 'left',
    *,
    left_on: str | Sequence[str] | None = None,
    right_on: str | Sequence[str] | None = None,
    include_nulls: bool = False,
    maintain_order: MaintainOrderJoin | None = 'left',
) → LazyFrame

Обновить значения в этом LazyFrame значениями из other.

движок:В памятиПотоковая обработкаРаспределённая обработка

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

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

Параметры:

other

LazyFrame, значения из которого будут использоваться для обновления

on

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

how{‘left’, ‘inner’, ‘full’}

• ‘left’ сохраняет все строки из левой таблицы; строки могут дублироваться, если нескольким строкам правого фрейма соответствует ключ строки левого фрейма.
• ‘inner’ сохраняет только строки, ключи которых есть в обоих фреймах.
• ‘full’ обновляет существующие строки с совпадающими ключами, а также добавляет новые строки из переданного фрейма.

left_on

Столбец или столбцы левого DataFrame для соединения.

right_on

Столбец или столбцы правого DataFrame для соединения.

include_nulls

Перезаписывать значения левого фрейма значениями null из правого фрейма. Если задано False (значение по умолчанию), значения null в правом фрейме игнорируются.

maintain_order{‘none’, ‘left’, ‘right’, ‘left_right’, ‘right_left’}

Определяет, порядок строк какого из входных фреймов нужно сохранить. Подробности см. в описании join(). В отличие от join эта функция по умолчанию сохраняет порядок строк левого фрейма.

Примечания

Это синтаксический сахар для левого или внутреннего соединения, которое по умолчанию сохраняет порядок строк левого DataFrame, с необязательным объединением столбцов, если задано include_nulls = False.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "A": [1, 2, 3, 4],
...         "B": [400, 500, 600, 700],
...     }
... )
>>> lf.collect()
shape: (4, 2)
┌─────┬─────┐
│ A   ┆ B   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 400 │
│ 2   ┆ 500 │
│ 3   ┆ 600 │
│ 4   ┆ 700 │
└─────┴─────┘
>>> new_lf = pl.LazyFrame(
...     {
...         "B": [-66, None, -99],
...         "C": [5, 3, 1],
...     }
... )

Обновить значения df ненулевыми значениями из new_df, используя индекс строк:

>>> lf.update(new_lf).collect()
shape: (4, 2)
┌─────┬─────┐
│ A   ┆ B   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ -66 │
│ 2   ┆ 500 │
│ 3   ┆ -99 │
│ 4   ┆ 700 │
└─────┴─────┘

Обновить значения df ненулевыми значениями из new_df по индексу строк, оставив только строки, общие для обоих фреймов:

>>> lf.update(new_lf, how="inner").collect()
shape: (3, 2)
┌─────┬─────┐
│ A   ┆ B   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ -66 │
│ 2   ┆ 500 │
│ 3   ┆ -99 │
└─────┴─────┘

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

>>> lf.update(new_lf, left_on=["A"], right_on=["C"], how="full").collect()
shape: (5, 2)
┌─────┬─────┐
│ A   ┆ B   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ -99 │
│ 2   ┆ 500 │
│ 3   ┆ 600 │
│ 4   ┆ 700 │
│ 5   ┆ -66 │
└─────┴─────┘

Обновить значения df, включая значения null из new_df, с помощью стратегии полного внешнего соединения, явно задав столбцы для соединения в каждом фрейме:

>>> lf.update(
...     new_lf, left_on="A", right_on="C", how="full", include_nulls=True
... ).collect()
shape: (5, 2)
┌─────┬──────┐
│ A   ┆ B    │
│ --- ┆ ---  │
│ i64 ┆ i64  │
╞═════╪══════╡
│ 1   ┆ -99  │
│ 2   ┆ 500  │
│ 3   ┆ null │
│ 4   ┆ 700  │
│ 5   ┆ -66  │
└─────┴──────┘

var(
    ddof: int = 1,
) → LazyFrame

Вычислить дисперсию столбцов LazyFrame.

движок:В памятиПотоковая обработкаРаспределённая обработка

Параметры:

ddof

«Число степеней свободы»: делитель, используемый при вычислении, равен N - ddof, где N — количество элементов. По умолчанию ddof равен 1.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.var().collect()
shape: (1, 2)
┌──────────┬──────┐
│ a        ┆ b    │
│ ---      ┆ ---  │
│ f64      ┆ f64  │
╞══════════╪══════╡
│ 1.666667 ┆ 0.25 │
└──────────┴──────┘
>>> lf.var(ddof=0).collect()
shape: (1, 2)
┌──────┬────────┐
│ a    ┆ b      │
│ ---  ┆ ---    │
│ f64  ┆ f64    │
╞══════╪════════╡
│ 1.25 ┆ 0.1875 │
└──────┴────────┘

property width: int

Получить количество столбцов.

Возвращает:

int

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

Чтобы определить ширину LazyFrame, необходимо разрешить его схему, что может быть затратной операцией. Идиоматичный способ разрешить схему — использовать collect_schema(). Это свойство существует только для симметрии с классом DataFrame.

См. также

collect_schema

Schema.len

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [4, 5, 6],
...     }
... )
>>> lf.width  
2

with_columns(
    *exprs: IntoExpr | Iterable[IntoExpr],
    **named_exprs: IntoExpr,
) → LazyFrame

Добавить столбцы в этот LazyFrame.

Добавленные столбцы заменят существующие столбцы с такими же именами.

движок:В памятиПотоковая обработкаРаспределённая обработка

Параметры:

*exprs

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

**named_exprs

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

Возвращает:

LazyFrame

Новый LazyFrame с добавленными столбцами.

Примечания

Создание нового LazyFrame с помощью этого метода не создаёт копию существующих данных.

Примеры

Передайте выражение, чтобы добавить его в качестве нового столбца.

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [0.5, 4, 10, 13],
...         "c": [True, True, False, True],
...     }
... )
>>> lf.with_columns((pl.col("a") ** 2).alias("a^2")).collect()
shape: (4, 4)
┌─────┬──────┬───────┬─────┐
│ a   ┆ b    ┆ c     ┆ a^2 │
│ --- ┆ ---  ┆ ---   ┆ --- │
│ i64 ┆ f64  ┆ bool  ┆ i64 │
╞═════╪══════╪═══════╪═════╡
│ 1   ┆ 0.5  ┆ true  ┆ 1   │
│ 2   ┆ 4.0  ┆ true  ┆ 4   │
│ 3   ┆ 10.0 ┆ false ┆ 9   │
│ 4   ┆ 13.0 ┆ true  ┆ 16  │
└─────┴──────┴───────┴─────┘

Добавленные столбцы заменят существующие столбцы с такими же именами.

>>> lf.with_columns(pl.col("a").cast(pl.Float64)).collect()
shape: (4, 3)
┌─────┬──────┬───────┐
│ a   ┆ b    ┆ c     │
│ --- ┆ ---  ┆ ---   │
│ f64 ┆ f64  ┆ bool  │
╞═════╪══════╪═══════╡
│ 1.0 ┆ 0.5  ┆ true  │
│ 2.0 ┆ 4.0  ┆ true  │
│ 3.0 ┆ 10.0 ┆ false │
│ 4.0 ┆ 13.0 ┆ true  │
└─────┴──────┴───────┘

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

>>> lf.with_columns(
...     (pl.col("a") ** 2).alias("a^2"),
...     (pl.col("b") / 2).alias("b/2"),
...     (pl.col("c").not_()).alias("not c"),
... ).collect()
shape: (4, 6)
┌─────┬──────┬───────┬─────┬──────┬───────┐
│ a   ┆ b    ┆ c     ┆ a^2 ┆ b/2  ┆ not c │
│ --- ┆ ---  ┆ ---   ┆ --- ┆ ---  ┆ ---   │
│ i64 ┆ f64  ┆ bool  ┆ i64 ┆ f64  ┆ bool  │
╞═════╪══════╪═══════╪═════╪══════╪═══════╡
│ 1   ┆ 0.5  ┆ true  ┆ 1   ┆ 0.25 ┆ false │
│ 2   ┆ 4.0  ┆ true  ┆ 4   ┆ 2.0  ┆ false │
│ 3   ┆ 10.0 ┆ false ┆ 9   ┆ 5.0  ┆ true  │
│ 4   ┆ 13.0 ┆ true  ┆ 16  ┆ 6.5  ┆ false │
└─────┴──────┴───────┴─────┴──────┴───────┘

Несколько столбцов также можно добавить, передав список выражений.

>>> lf.with_columns(
...     [
...         (pl.col("a") ** 2).alias("a^2"),
...         (pl.col("b") / 2).alias("b/2"),
...         (pl.col("c").not_()).alias("not c"),
...     ]
... ).collect()
shape: (4, 6)
┌─────┬──────┬───────┬─────┬──────┬───────┐
│ a   ┆ b    ┆ c     ┆ a^2 ┆ b/2  ┆ not c │
│ --- ┆ ---  ┆ ---   ┆ --- ┆ ---  ┆ ---   │
│ i64 ┆ f64  ┆ bool  ┆ i64 ┆ f64  ┆ bool  │
╞═════╪══════╪═══════╪═════╪══════╪═══════╡
│ 1   ┆ 0.5  ┆ true  ┆ 1   ┆ 0.25 ┆ false │
│ 2   ┆ 4.0  ┆ true  ┆ 4   ┆ 2.0  ┆ false │
│ 3   ┆ 10.0 ┆ false ┆ 9   ┆ 5.0  ┆ true  │
│ 4   ┆ 13.0 ┆ true  ┆ 16  ┆ 6.5  ┆ false │
└─────┴──────┴───────┴─────┴──────┴───────┘

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

>>> lf.with_columns(
...     ab=pl.col("a") * pl.col("b"),
...     not_c=pl.col("c").not_(),
... ).collect()
shape: (4, 5)
┌─────┬──────┬───────┬──────┬───────┐
│ a   ┆ b    ┆ c     ┆ ab   ┆ not_c │
│ --- ┆ ---  ┆ ---   ┆ ---  ┆ ---   │
│ i64 ┆ f64  ┆ bool  ┆ f64  ┆ bool  │
╞═════╪══════╪═══════╪══════╪═══════╡
│ 1   ┆ 0.5  ┆ true  ┆ 0.5  ┆ false │
│ 2   ┆ 4.0  ┆ true  ┆ 8.0  ┆ false │
│ 3   ┆ 10.0 ┆ false ┆ 30.0 ┆ true  │
│ 4   ┆ 13.0 ┆ true  ┆ 52.0 ┆ false │
└─────┴──────┴───────┴──────┴───────┘

with_columns_seq(
    *exprs: IntoExpr | Iterable[IntoExpr],
    **named_exprs: IntoExpr,
) → LazyFrame

Добавляет столбцы в этот LazyFrame.

Добавленные столбцы заменят существующие столбцы с теми же именами.

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

движок:В памятиПотоковыйРаспределённый

Параметры:

*exprs

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

**named_exprs

Дополнительные столбцы, передаваемые в виде именованных аргументов. Столбцы будут переименованы в соответствии с именами аргументов.

Возвращает:

LazyFrame

Новый LazyFrame с добавленными столбцами.

См. также

with_columns

with_context(
    other: Self | list[Self],
) → LazyFrame

Добавляет внешний контекст в граф вычислений.

Устарело с версии 1.0.0: Вместо этого используйте concat() с how='horizontal'

Это позволяет выражениям также обращаться к столбцам из DataFrame, не входящих в этот объект.

Параметры:

other

Lazy DataFrame для объединения.

Примеры

>>> lf = pl.LazyFrame({"a": [1, 2, 3], "b": ["a", "c", None]})
>>> lf_other = pl.LazyFrame({"c": ["foo", "ham"]})
>>> lf.with_context(lf_other).select(  
...     pl.col("b") + pl.col("c").first()
... ).collect()
shape: (3, 1)
┌──────┐
│ b    │
│ ---  │
│ str  │
╞══════╡
│ afoo │
│ cfoo │
│ null │
└──────┘

Заполните значения null медианой из другого DataFrame:

>>> train_lf = pl.LazyFrame(
...     {"feature_0": [-1.0, 0, 1], "feature_1": [-1.0, 0, 1]}
... )
>>> test_lf = pl.LazyFrame(
...     {"feature_0": [-1.0, None, 1], "feature_1": [-1.0, 0, 1]}
... )
>>> test_lf.with_context(  
...     train_lf.select(pl.all().name.suffix("_train"))
... ).select(
...     pl.col("feature_0").fill_null(pl.col("feature_0_train").median())
... ).collect()
shape: (3, 1)
┌───────────┐
│ feature_0 │
│ ---       │
│ f64       │
╞═══════════╡
│ -1.0      │
│ 0.0       │
│ 1.0       │
└───────────┘

with_row_count(
    name: str = 'row_nr',
    offset: int = 0,
) → LazyFrame

Добавляет столбец с подсчётом строк по индексу 0.

Устарело с версии 0.20.4: Вместо этого используйте метод with_row_index(). Обратите внимание, что имя столбца по умолчанию изменилось с ‘row_nr’ на ‘index’.

Параметры:

name

Имя добавляемого столбца.

offset

Начальное смещение для подсчёта строк.

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

Это может отрицательно сказаться на производительности запросов. Например, это может блокировать оптимизацию проталкивания предикатов.

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 3, 5],
...         "b": [2, 4, 6],
...     }
... )
>>> lf.with_row_count().collect()  
shape: (3, 3)
┌────────┬─────┬─────┐
│ row_nr ┆ a   ┆ b   │
│ ---    ┆ --- ┆ --- │
│ u32    ┆ i64 ┆ i64 │
╞════════╪═════╪═════╡
│ 0      ┆ 1   ┆ 2   │
│ 1      ┆ 3   ┆ 4   │
│ 2      ┆ 5   ┆ 6   │
└────────┴─────┴─────┘

with_row_index(
    name: str = 'index',
    offset: int = 0,
) → LazyFrame

Добавляет индекс строки в качестве первого столбца LazyFrame.

движок:В памятиПотоковыйРаспределённый

Параметры:

name

Имя столбца индекса.

offset

Начальное смещение индекса. Не может быть отрицательным.

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

Использование этой функции может отрицательно сказаться на производительности запросов. Например, это может блокировать оптимизацию проталкивания предикатов.

Примечания

Полученный столбец не обладает особыми свойствами. Это обычный столбец типа UInt32 (или UInt64 в polars[rt64]).

Примеры

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 3, 5],
...         "b": [2, 4, 6],
...     }
... )
>>> lf.with_row_index().collect()
shape: (3, 3)
┌───────┬─────┬─────┐
│ index ┆ a   ┆ b   │
│ ---   ┆ --- ┆ --- │
│ u32   ┆ i64 ┆ i64 │
╞═══════╪═════╪═════╡
│ 0     ┆ 1   ┆ 2   │
│ 1     ┆ 3   ┆ 4   │
│ 2     ┆ 5   ┆ 6   │
└───────┴─────┴─────┘
>>> lf.with_row_index("id", offset=1000).collect()
shape: (3, 3)
┌──────┬─────┬─────┐
│ id   ┆ a   ┆ b   │
│ ---  ┆ --- ┆ --- │
│ u32  ┆ i64 ┆ i64 │
╞══════╪═════╪═════╡
│ 1000 ┆ 1   ┆ 2   │
│ 1001 ┆ 3   ┆ 4   │
│ 1002 ┆ 5   ┆ 6   │
└──────┴─────┴─────┘

Столбец индекса также можно создать с помощью выражений int_range() и len().

>>> lf.select(
...     pl.int_range(pl.len(), dtype=pl.UInt32).alias("index"),
...     pl.all(),
... ).collect()
shape: (3, 3)
┌───────┬─────┬─────┐
│ index ┆ a   ┆ b   │
│ ---   ┆ --- ┆ --- │
│ u32   ┆ i64 ┆ i64 │
╞═══════╪═════╪═════╡
│ 0     ┆ 1   ┆ 2   │
│ 1     ┆ 3   ┆ 4   │
│ 2     ┆ 5   ┆ 6   │
└───────┴─────┴─────┘