Clarify which column is kept in join with left_on and right_on

[jxu]

Description

import polars as pl
df1 = pl.DataFrame({"a": ["x","y","z"], "lk": [1,2,3]})
df2 = pl.DataFrame({"b": ["x","y","z"], "rk": [1,2,3]})

print(df1.join(df2, how="inner", left_on="lk", right_on="rk"))

Result: only lk column is kept. IIRC in SQL, in a SELECT with a join, both columns are kept around and you can choose which ones to keep with columns in SELECT. But doing a polars .select("rk") won't work because it's already gone.

Link

https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.join.html

[alexander-beedie]

FYI, you can return both columns by setting coalesce=False, though we could probably make the "coalesce" docstring even more explicit about what it means to coalesce the join columns (eg: keeps the left-hand column) 🤔

df1.join(df2, how="inner", left_on="lk", right_on="rk", coalesce=False)
# shape: (3, 4)
# ┌─────┬─────┬─────┬─────┐
# │ a   ┆ lk  ┆ b   ┆ rk  │
# │ --- ┆ --- ┆ --- ┆ --- │
# │ str ┆ i64 ┆ str ┆ i64 │
# ╞═════╪═════╪═════╪═════╡
# │ x   ┆ 1   ┆ x   ┆ 1   │
# │ y   ┆ 2   ┆ y   ┆ 2   │
# │ z   ┆ 3   ┆ z   ┆ 3   │
# └─────┴─────┴─────┴─────┘

[jxu]

I see. There's no indication that an inner join will only keep the left key, especially since inner joins are symmetric.
Incidentally, SQL has a poorly names COALESCE function that does something completely different.