polars.Expr.top_k#

Expr.top_k( k: int | IntoExprColumn = 5, *, nulls_last: bool | None = None, maintain_order: bool | None = None, multithreaded: bool | None = None, ) → Self[source]#

Return the k largest elements.

This has time complexity:

\[O(n + k \log{n})\]

Parameters:

k: Number of elements to return.
nulls_last: Place null values last.

Deprecated since version 0.20.31: This parameter will be removed in the next breaking release. Null values will be considered lowest priority and will only be included if k is larger than the number of non-null elements.
maintain_order: Whether the order should be maintained if elements are equal.

Deprecated since version 0.20.31: This parameter will be removed in the next breaking release. There will be no guarantees about the order of the output.
multithreaded: Sort using multiple threads.

Deprecated since version 0.20.31: This parameter will be removed in the next breaking release. Polars itself will determine whether to use multithreading or not.

See also

top_k_by
bottom_k
bottom_k_by

Examples

Get the 5 largest values in series.

>>> df = pl.DataFrame(
...     {
...         "value": [1, 98, 2, 3, 99, 4],
...     }
... )
>>> df.select(
...     pl.col("value").top_k().alias("top_k"),
...     pl.col("value").bottom_k().alias("bottom_k"),
... )
shape: (5, 2)
┌───────┬──────────┐
│ top_k ┆ bottom_k │
│ ---   ┆ ---      │
│ i64   ┆ i64      │
╞═══════╪══════════╡
│ 99    ┆ 1        │
│ 98    ┆ 2        │
│ 4     ┆ 3        │
│ 3     ┆ 4        │
│ 2     ┆ 98       │
└───────┴──────────┘