assert_frame_equal.html)
    * [ polars.testing.assert_frame_not_equal ](../../api/polars.testing.assert_frame_not_equal.html)
    * [ polars.testing.assert_series_equal ](../../api/polars.testing.assert_series_equal.html)
    * [ polars.testing.assert_series_not_equal ](../../api/polars.testing.assert_series_not_equal.html)
    * [ polars.testing.parametric.dataframes ](../../api/polars.testing.parametric.dataframes.html)
    * [ polars.testing.parametric.series ](../../api/polars.testing.parametric.series.html)
    * [ polars.testing.parametric.column ](../../api/polars.testing.parametric.column.html)
    * [ polars.testing.parametric.columns ](../../api/polars.testing.parametric.columns.html)
    * [ polars.testing.parametric.create_list_strategy ](../../api/polars.testing.parametric.create_list_strategy.html)
    * [ polars.testing.parametric.load_profile ](../../api/polars.testing.parametric.load_profile.html)
    * [ polars.testing.parametric.set_profile ](../../api/polars.testing.parametric.set_profile.html)

  * [ Metadata ](../../metadata.html) __
    * [ polars.build_info ](../../api/polars.build_info.html)
    * [ polars.get_index_type ](../../api/polars.get_index_type.html)
    * [ polars.show_versions ](../../api/polars.show_versions.html)
    * [ polars.thread_pool_size ](../../api/polars.thread_pool_size.html)
    * [ polars.threadpool_size ](../../api/polars.threadpool_size.html)

  * [ __ ](../../../index.html)
  * [ Python API reference ](../../index.html)
  * __
  * [ Manipulation/selection ](../modify_select.html)
  * polars.Expr.top_k 

#  polars.Expr.top_k  #

Expr.  top_k  (

     _ k  :  [ int  ](https://docs.python.org/3/library/functions.html#int "\(in Python v3.12\)") |  IntoExprColumn  =  5  _ , 
     _ *  _ , 
     _ by  :  IntoExpr  |  Iterable  [  IntoExpr  ]  |  [ None  ](https://docs.python.org/3/library/constants.html#None "\(in Python v3.12\)") =  None  _ , 
     _ descending  :  [ bool  ](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)") |  Sequence  [  [ bool  ](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)") ]  =  False  _ , 
     _ nulls_last  :  [ bool  ](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)") =  False  _ , 
     _ maintain_order  :  [ bool  ](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)") =  False  _ , 
     _ multithreaded  :  [ bool  ](https://docs.python.org/3/library/functions.html#bool "\(in Python v3.12\)") =  True  _ , 
)  →  Self  [ [source]  ](https://github.com/pola-rs/polars/blob/main/py-
polars/polars/expr/expr.py#L2034-L2198) #

    

Return the ` k  ` largest elements.

This has time complexity:

\\[\begin{split}O(n + k \\\log{}n - \frac{k}{2})\end{split}\\]

Parameters  :

    

**k**

    

Number of elements to return.

**by**

    

Column(s) included in sort order. Accepts expression input. Strings are parsed
as column names. If not provided, each column will be treated induvidually.

**descending**

    

Return the k smallest. Top-k by multiple columns can be specified per column
by passing a sequence of booleans.

**nulls_last**

    

Place null values last.

**maintain_order**

    

Whether the order should be maintained if elements are equal.

**multithreaded**

    

Sort using multiple threads.

See also

[ ` bottom_k  ` ](polars.Expr.bottom_k.html#polars.Expr.bottom_k
"polars.Expr.bottom_k")

    

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