polars.DataFrame.join¶

DataFrame.join(df: polars.internals.frame.DataFrame, left_on: Optional[Union[str, polars.internals.expr.Expr, List[Union[str, polars.internals.expr.Expr]]]] = None, right_on: Optional[Union[str, polars.internals.expr.Expr, List[Union[str, polars.internals.expr.Expr]]]] = None, on: Optional[Union[str, polars.internals.expr.Expr, List[Union[str, polars.internals.expr.Expr]]]] = None, how: str = 'inner', suffix: str = '_right', asof_by: Optional[Union[str, List[str]]] = None, asof_by_left: Optional[Union[str, List[str]]] = None, asof_by_right: Optional[Union[str, List[str]]] = None) → polars.internals.frame.DF¶

SQL like joins.

Parameters

df

DataFrame to join with.

left_on

Name(s) of the left join column(s).

right_on

Name(s) of the right join column(s).

on

Name(s) of the join columns in both DataFrames.

how

Join strategy

“inner”
“left”
“outer”
“asof”
“cross”
“semi”
“anti”

suffix

Suffix to append to columns with a duplicate name.

asof_by

join on these columns before doing asof join

asof_by_left

join on these columns before doing asof join

asof_by_right

join on these columns before doing asof join

Returns

Joined DataFrame

Examples

>>> 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   ┆ a   ┆ x     │
├╌╌╌╌╌┼╌╌╌╌╌┼╌╌╌╌╌┼╌╌╌╌╌╌╌┤
│ 2   ┆ 7   ┆ b   ┆ y     │
└─────┴─────┴─────┴───────┘

>>> df.join(other_df, on="ham", how="outer")
shape: (4, 4)
┌──────┬──────┬─────┬───────┐
│ foo  ┆ bar  ┆ ham ┆ apple │
│ ---  ┆ ---  ┆ --- ┆ ---   │
│ i64  ┆ f64  ┆ str ┆ str   │
╞══════╪══════╪═════╪═══════╡
│ 1    ┆ 6    ┆ a   ┆ x     │
├╌╌╌╌╌╌┼╌╌╌╌╌╌┼╌╌╌╌╌┼╌╌╌╌╌╌╌┤
│ 2    ┆ 7    ┆ b   ┆ y     │
├╌╌╌╌╌╌┼╌╌╌╌╌╌┼╌╌╌╌╌┼╌╌╌╌╌╌╌┤
│ null ┆ null ┆ d   ┆ z     │
├╌╌╌╌╌╌┼╌╌╌╌╌╌┼╌╌╌╌╌┼╌╌╌╌╌╌╌┤
│ 3    ┆ 8    ┆ c   ┆ null  │
└──────┴──────┴─────┴───────┘

Asof join This is similar to a left-join except that we match on near keys rather than equal keys. The direction is backward The keys must be sorted to perform an asof join

polars.DataFrame.is_unique polars.DataFrame.join_asof