:nosearch:

.. _op_ai_onnx_TopK-10:

TopK - version 10
=================

This page documents version **10** of operator **TopK**. See :doc:`TopK` for the latest version (since version 11).

- **Domain**: ``ai.onnx``
- **Since version**: 10

Retrieve the top-K elements along a specified axis. Given an input tensor of
shape [a_0, a_1, ..., a{n-1}] and integer argument k, return two outputs:

.. code-block:: text

    -Value tensor of shape [a_0, a_1, ..., a_{axis-1}, k, a_{axis+1}, ... a_{n-1}]
      which contains the values of the top k elements along the specified axis
    -Index tensor of shape [a_0, a_1, ..., a_{axis-1}, k, a_{axis+1}, ... a_{n-1}] which
     contains the indices of the top k elements (original indices from the input
     tensor).

Given two equivalent values, this operator uses the indices along the axis  as

.. code-block:: text

    a tiebreaker. That is, the element with the lower index will appear first.


**Inputs**

- **X** (*T*): Tensor of shape [a_0, a_1, ..., a{n-1}]
- **K** (*tensor(int64)*): A 1-D tensor containing a single positive value corresponding to the number of top elements to retrieve

**Outputs**

- **Values** (*T*): Tensor of shape [a_0, a_1, ..., a{axis-1}, k, a{axis+1}, ... a{n-1}] containing top K values from the input tensor
- **Indices** (*I*): Tensor of shape [a_0, a_1, ..., a{axis-1}, k, a{axis+1}, ... a{n-1}] containing the corresponding input tensor indices for the top K values.

**Attributes**

- **axis** (*int*): Dimension on which to do the sort.

**Type Constraints**

- **T**: Constrain input and output types to float tensors.
  Allowed types: tensor(double), tensor(float), tensor(float16).
- **I**: Constrain index tensor to int64
  Allowed types: tensor(int64).

Differences with previous version (1)
-------------------------------------

**SchemaDiff**: ``TopK`` (domain ``'ai.onnx'``)

* old version: 1
* new version: 10
* breaking: **yes**

**Breaking reasons:**

* input 'K' (added): at position 1; option=Single; type_str='tensor(int64)'
* attribute 'k' (removed): type=INT; required=True

**Inputs:**

* [BREAKING] added 'K': at position 1; option=Single; type_str='tensor(int64)'

**Attributes:**

* [BREAKING] removed 'k': type=INT; required=True

**Documentation:**

* line similarity: 0.95 (+1/-0 lines)

.. code-block:: diff

    --- TopK v1
    +++ TopK v10
    @@ -6,5 +6,6 @@
       -Index tensor of shape [a_0, a_1, ..., a_{axis-1}, k, a_{axis+1}, ... a_{n-1}] which
        contains the indices of the top k elements (original indices from the input
        tensor).
    +
     Given two equivalent values, this operator uses the indices along the axis  as
      a tiebreaker. That is, the element with the lower index will appear first.