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