polars.merge_sorted#

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

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 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 that is sorted.
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 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  │
└────────┴─────┘