polars.DataFrame.join

DataFrame.join(
    other: DataFrame,
    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',
) → DataFrame

Соединение в стиле SQL.

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

Параметры:

other

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

Имя или имена столбцов для соединения в левой таблице.

right_on

Имя или имена столбцов для соединения в правой таблице.

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	Всегда использовать правую сторону.

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

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

См. также

join_asof

join_where

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> other_df = pl.DataFrame(
...     {
...         "apple": ["x", "y", "z"],
...         "ham": ["a", "b", "d"],
...     }
... )
>>> df.join(other_df, on="ham")
shape: (2, 4)
┌─────┬─────┬─────┬───────┐
│ foo ┆ bar ┆ ham ┆ apple │
│ --- ┆ --- ┆ --- ┆ ---   │
│ i64 ┆ f64 ┆ str ┆ str   │
╞═════╪═════╪═════╪═══════╡
│ 1   ┆ 6.0 ┆ a   ┆ x     │
│ 2   ┆ 7.0 ┆ b   ┆ y     │
└─────┴─────┴─────┴───────┘

>>> df.join(other_df, on="ham", how="full")
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      │
└──────┴──────┴──────┴───────┴───────────┘

>>> df.join(other_df, on="ham", how="full", coalesce=True)
shape: (4, 4)
┌──────┬──────┬─────┬───────┐
│ foo  ┆ bar  ┆ ham ┆ apple │
│ ---  ┆ ---  ┆ --- ┆ ---   │
│ i64  ┆ f64  ┆ str ┆ str   │
╞══════╪══════╪═════╪═══════╡
│ 1    ┆ 6.0  ┆ a   ┆ x     │
│ 2    ┆ 7.0  ┆ b   ┆ y     │
│ null ┆ null ┆ d   ┆ z     │
│ 3    ┆ 8.0  ┆ c   ┆ null  │
└──────┴──────┴─────┴───────┘

>>> df.join(other_df, on="ham", how="left")
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  │
└─────┴─────┴─────┴───────┘

>>> df.join(other_df, on="ham", how="semi")
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ f64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6.0 ┆ a   │
│ 2   ┆ 7.0 ┆ b   │
└─────┴─────┴─────┘

>>> df.join(other_df, on="ham", how="anti")
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ f64 ┆ str │
╞═════╪═════╪═════╡
│ 3   ┆ 8.0 ┆ c   │
└─────┴─────┴─────┘

>>> df.join(other_df, how="cross")
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         │
└─────┴─────┴─────┴───────┴───────────┘