polars.merge_sorted

polars.merge_sorted(
    items: Iterable[PolarsType],
    key: str | Sequence[str],
    *,
    maintain_order: bool = False,
) → PolarsType

Merge multiple sorted DataFrames or LazyFrames 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 that key(s) otherwise the output will not make sense.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Parameters:

items

DataFrames or LazyFrames to merge.

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 dataframes.

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

Examples

>>> df0 = pl.DataFrame(
...     {"name": ["steve", "elise", "bob"], "age": [42, 44, 18]}
... ).sort("age")
>>> df1 = pl.DataFrame(
...     {"name": ["anna", "megan", "steve", "thomas"], "age": [21, 33, 17, 20]}
... ).sort("age")
>>> df2 = pl.DataFrame({"name": ["ida", "maya"], "age": [37, 27]}).sort("age")
>>> pl.merge_sorted([df0, df1, df2], key="age")
shape: (9, 2)
┌────────┬─────┐
│ name   ┆ age │
│ ---    ┆ --- │
│ str    ┆ i64 │
╞════════╪═════╡
│ steve  ┆ 17  │
│ bob    ┆ 18  │
│ thomas ┆ 20  │
│ anna   ┆ 21  │
│ maya   ┆ 27  │
│ megan  ┆ 33  │
│ ida    ┆ 37  │
│ steve  ┆ 42  │
│ elise  ┆ 44  │
└────────┴─────┘