polars.LazyFrame.join

LazyFrame.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

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

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

Примечание

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

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