polars.LazyFrame.merge_sorted

LazyFrame.merge_sorted(

other: LazyFrame,

key: str | Sequence[str],

*,

maintain_order: bool = False,

) → LazyFrame

Take two sorted DataFrames and merge them by the sorted key.

The output of this operation will also be sorted. It is the callers responsibility that the frames are sorted in ascending order by the key(s), with null keys at the end, otherwise the order of the output will not make sense.

The schemas of both LazyFrames must be equal.

Parameters:

other

Other DataFrame that must be merged

key

Key column(s) that the frames are sorted by. A single column name or a sequence of column names can be passed. When multiple keys are given the frames are merged as if sorted by those keys in order.

maintain_order

If True, the output is guaranteed to have left-biased ordering for equal keys: rows from the left frame appear before rows from the right frame when their keys are equal.

Notes

Unless maintain_order=True, no guarantee is given over the output row order when the key is equal between the both dataframes.

The key(s) must be sorted in ascending order.

Examples

>>> df0 = pl.LazyFrame(
...     {"name": ["steve", "elise", "bob"], "age": [42, 44, 18]}
... ).sort("age")
>>> df0.collect()
shape: (3, 2)
┌───────┬─────┐
│ name  ┆ age │
│ ---   ┆ --- │
│ str   ┆ i64 │
╞═══════╪═════╡
│ bob   ┆ 18  │
│ steve ┆ 42  │
│ elise ┆ 44  │
└───────┴─────┘
>>> df1 = pl.LazyFrame(
...     {"name": ["anna", "megan", "steve", "thomas"], "age": [21, 33, 42, 20]}
... ).sort("age")
>>> df1.collect()
shape: (4, 2)
┌────────┬─────┐
│ name   ┆ age │
│ ---    ┆ --- │
│ str    ┆ i64 │
╞════════╪═════╡
│ thomas ┆ 20  │
│ anna   ┆ 21  │
│ megan  ┆ 33  │
│ steve  ┆ 42  │
└────────┴─────┘
>>> df0.merge_sorted(df1, key="age").collect()
shape: (7, 2)
┌────────┬─────┐
│ name   ┆ age │
│ ---    ┆ --- │
│ str    ┆ i64 │
╞════════╪═════╡
│ bob    ┆ 18  │
│ thomas ┆ 20  │
│ anna   ┆ 21  │
│ megan  ┆ 33  │
│ steve  ┆ 42  │
│ steve  ┆ 42  │
│ elise  ┆ 44  │
└────────┴─────┘

Multiple keys can be passed to merge frames sorted by a composite key. The frames are merged as if sorted by key_1, then key_2.

>>> df0 = pl.LazyFrame({"key_1": [1, 1, 3], "key_2": [1, 4, 2]})
>>> df1 = pl.LazyFrame({"key_1": [1, 2, 3], "key_2": [2, 1, 1]})
>>> df0.merge_sorted(df1, key=["key_1", "key_2"]).collect()
shape: (6, 2)
┌───────┬───────┐
│ key_1 ┆ key_2 │
│ ---   ┆ ---   │
│ i64   ┆ i64   │
╞═══════╪═══════╡
│ 1     ┆ 1     │
│ 1     ┆ 2     │
│ 1     ┆ 4     │
│ 2     ┆ 1     │
│ 3     ┆ 1     │
│ 3     ┆ 2     │
└───────┴───────┘