feat!: Preserve left and right join keys in outer joins

[ritchie46]

Previously, the result of an outer join did not contain the join keys of the left and right frames.
Rather, it contained a coalesced version of the left key and right key.
This loses information and does not conform to default SQL behavior.

The behavior has been changed to include the original join keys.
Name clashes are solved by appending a suffix (_right by default) to the right join key name.
The previous behavior can be retained by setting how="outer_coalesce".

Example

Before:

>>> df1 = pl.DataFrame({"L1": ["a", "b", "c"], "L2": [1, 2, 3]})
>>> df2 = pl.DataFrame({"L1": ["a", "c", "d"], "R2": [7, 8, 9]})
>>> df1.join(df2, on="L1", how="outer")
shape: (4, 3)
┌─────┬──────┬──────┐
│ L1  ┆ L2   ┆ R2   │
│ --- ┆ ---  ┆ ---  │
│ str ┆ i64  ┆ i64  │
╞═════╪══════╪══════╡
│ a   ┆ 1    ┆ 7    │
│ c   ┆ 3    ┆ 8    │
│ d   ┆ null ┆ 9    │
│ b   ┆ 2    ┆ null │
└─────┴──────┴──────┘

After:

>>> df1.join(df2, on="L1", how="outer")
shape: (4, 4)
┌──────┬──────┬──────────┬──────┐
│ L1   ┆ L2   ┆ L1_right ┆ R2   │
│ ---  ┆ ---  ┆ ---      ┆ ---  │
│ str  ┆ i64  ┆ str      ┆ i64  │
╞══════╪══════╪══════════╪══════╡
│ a    ┆ 1    ┆ a        ┆ 7    │
│ b    ┆ 2    ┆ null     ┆ null │
│ c    ┆ 3    ┆ c        ┆ 8    │
│ null ┆ null ┆ d        ┆ 9    │
└──────┴──────┴──────────┴──────┘
>>> df1.join(df2, on="a", how="outer_coalesce")  # Keeps previous behavior
shape: (4, 3)
┌─────┬──────┬──────┐
│ L1  ┆ L2   ┆ R2   │
│ --- ┆ ---  ┆ ---  │
│ str ┆ i64  ┆ i64  │
╞═════╪══════╪══════╡
│ a   ┆ 1    ┆ 7    │
│ c   ┆ 3    ┆ 8    │
│ d   ┆ null ┆ 9    │
│ b   ┆ 2    ┆ null │
└─────┴──────┴──────┘

[yusufshalaby]

This makes a lot of sense. Btw this breaking change was not listed in the release info and took me a bit of time to track.

[MarcoGorelli]

@yusufshalaby it's listed here:

and also is the first item appearing in the upgrade guide: https://pola-rs.github.io/polars/releases/upgrade/0.20/

Perhaps you're looking at the wrong release notes?

[yusufshalaby]

Sorry! Didn't read it carefully enough. Thanks for clarifying.

[eJamie98]

echoing the comments from #9335 , should this also be implemented for other join types? I've been tripped up a few times by left joins deleting my rh join column

[ritchie46]

Will add add an option for left joins later