Polars · Module

df.join

DataFrame.join combines two DataFrames with SQL-like semantics. Choose shared keys with on or distinct key expressions with left_on and right_on, and select the join behavior with how.

How it works

Use DataFrame.join to combine two DataFrames with SQL-like join strategies. Match the same key with on, or distinct left and right keys with left_on and right_on; duplicate right-side column names receive the configured suffix.

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`	DataFrame to join with.
`on`	`str \| Expr \| Sequence[str \| Expr] \| None`	Names, expressions, or selectors used on both DataFrames. If provided, left_on and right_on should be None.
`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 column names.
`validate`	`JoinValidation = 'm:m'`	Validation mode for the join cardinality.
`nulls_equal`	`bool = False`	Whether null join keys should be considered equal.
`coalesce`	`bool \| None = None`	Whether matching join columns should be coalesced.
`maintain_order`	`MaintainOrderJoin \| None = None`	Controls the order-maintenance behavior of the join.
`build_side`	`JoinBuildSide = 'auto'`	Selects the build side used by the join implementation.

Returns

DataFrame

Key points

The method combines two DataFrames using familiar relational join semantics.
The shared-key argument on accepts names, expressions, or selectors applied to both inputs.
A left join preserves every left-side row while adding matching right-side data.
A semi join filters the left DataFrame to rows having at least one right-side match.
A cross join pairs every left row with every right row.

Common mistakes

Do not combine on with left_on or right_on; choose either a shared key specification or separate keys.
Columns duplicated between the inputs are renamed using suffix, which defaults to _right.

Example: Join DataFrames on differently named keys

import polars as pl

customers = pl.DataFrame({"id": [1, 2], "name": ["Ada", "Linus"]})
orders = pl.DataFrame({"customer_id": [1, 1, 3], "total": [10, 15, 20]})

result = customers.join(
    orders,
    left_on="id",
    right_on="customer_id",
    how="left",
)
print(result)

This left join matches differently named key columns and retains every row from the left DataFrame.

When to use it

Enrich records

Combine fact rows with descriptive dimension data using a common identifier.

Preserve left-side rows

Keep a complete primary dataset while optionally attaching matching secondary records.

Semi and anti filtering

Filter left-side records according to existence or absence of matches on the right.

Cartesian combinations

Generate every pair of rows from two small DataFrames.

Interview questions

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

DataFrame.join combines two DataFrames using SQL-like semantics. The default strategy is inner, so only rows with matching keys in both inputs are returned.

Follow-up: How would you preserve unmatched left rows? Use how="left", which retains every left row and fills missing right-side values with nulls.

QWhen should you use on versus left_on and right_on?

Use on when the join key has the same name in both DataFrames. Use left_on and right_on when the key names or expressions differ; on must then be omitted.

Follow-up: How can you join on multiple keys? Pass a sequence of column names or expressions to the relevant key argument.

QWhich join strategies does the method support?

The how argument selects among inner, left, right, full, semi, anti, and cross joins. A cross join produces the Cartesian product, while semi and anti return rows from the left side based on whether a right-side match exists.

Follow-up: Which strategy returns all rows from both inputs? Use full; matching rows are combined and nonmatches receive null values.

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

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