Polars · Function

join

DataFrame.join combines two DataFrames by matching key columns or expressions. Its default inner strategy keeps only matching rows; other strategies control which unmatched rows are retained.

Since: 1.24

How it works

DataFrame.join combines two DataFrames using matching key columns or expressions. Choose a join strategy to control which rows remain, and use separate left_on/right_on keys when the join columns have different names.

Syntax

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

Parameters

Name	Type	Description
`other`	`DataFrame`	The DataFrame to join with.
`on`	`str \| Expr \| Sequence[str \| Expr] \| None`	Names, expressions, or selectors used on both DataFrames.
`how`	`JoinStrategy = 'inner'`	Join strategy: inner, left, right, full, semi, anti, or cross.
`left_on`	`str \| Expr \| Sequence[str \| Expr] \| None`	Join column names, expressions, or selectors from the left DataFrame.
`right_on`	`str \| Expr \| Sequence[str \| Expr] \| None`	Join column names, expressions, or selectors from the right DataFrame.
`suffix`	`str = '_right'`	Suffix appended to duplicate right-side column names.
`validate`	`JoinValidation = 'm:m'`	Cardinality validation mode.
`nulls_equal`	`bool = False`	Whether null join keys should match each other.
`coalesce`	`bool \| None = None`	Whether join-key columns should be coalesced when applicable.
`maintain_order`	`MaintainOrderJoin \| None = None`	Controls join-order maintenance.
`build_side`	`JoinBuildSide = 'auto'`	Selects the join build side.

Returns

DataFrame

Key points

DataFrame.join combines two DataFrames using relational, SQL-style matching.
An inner join keeps only rows whose join keys match on both sides.
A left join preserves the complete left input and appends available right-side matches.
A full join retains both inputs and uses nulls where a counterpart is absent.
A cross join produces every left-row/right-row combination.
The on argument accepts shared column names, expressions, or selectors.

Common mistakes

Do not provide on together with a cross join; use how='cross' without an equi-join key.
Use nulls_equal in current stable code; join_nulls is the former parameter name.

Example: Join on different key names

import polars as pl

users = pl.DataFrame({"id": [1, 2], "name": ["Ada", "Linus"]})
orders = pl.DataFrame({"user_id": [1, 1, 3], "amount": [10, 20, 5]})

result = users.join(
    orders,
    left_on="id",
    right_on="user_id",
    how="left",
)
print(result)

A left join keeps every user and attaches matching order columns; unmatched users receive nulls.

When to use it

Equi-join related datasets

Combine records from two tables that share an identifier.

Preserve a complete left dataset

Keep every record from a primary table while enriching it when matches exist.

Join with distinct key names

Match tables whose key columns have different names.

Create a Cartesian product

Generate all combinations between two inputs.

Interview questions

QWhat does DataFrame.join do, and what is its default behavior?

The default strategy is inner, which returns only rows with matching values in both DataFrames. Other strategies include left, right, full, semi, anti, and cross.

Follow-up: How would you retain unmatched left rows? Use how="left"; matching right columns are added, while missing matches are represented with nulls.

QWhen should on versus left_on and right_on be used?

Use on when both DataFrames use the same join key name. Use left_on and right_on when the key names or expressions differ.

Follow-up: Can on be combined with left_on or right_on? No: choose the shared-key form or the separate-left/right-key form.

QHow are duplicate columns and null join keys handled?

The method returns a DataFrame containing columns from the joined inputs according to the selected strategy. Duplicate right-side column names receive the suffix specified by suffix, whose default is '_right'.

Follow-up: How can null keys match each other? Set nulls_equal=True when null values should be considered equal during matching.

polars.DataFrame.join_where
polars.DataFrame.join_asof
polars.LazyFrame.join

Source: polars.DataFrame.join — Polars documentation. Checked 2026-10-15.