(l-onnx-doc-TopK)=

# TopK


(l-onnx-op-topk-11)=

## TopK - 11

### Version

- **name**: [TopK (GitHub)](https://github.com/onnx/onnx/blob/main/docs/Operators.md#TopK)
- **domain**: `main`
- **since_version**: `11`
- **function**: `False`
- **support_level**: `SupportType.COMMON`
- **shape inference**: `True`

This version of the operator has been available
**since version 11**.

### Summary

Retrieve the top-K largest or smallest 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:

* 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).

* If "largest" is 1 (the default value) then the k largest elements are returned.
* If "sorted" is 1 (the default value) then the resulting k elements will be sorted.
* If "sorted" is 0, order of returned 'Values' and 'Indices' are undefined.

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.

### Attributes

* **axis - INT** (default is `'-1'`):

  Dimension on which to do the sort. Negative value means counting dimensions from the back. Accepted range is [-r, r-1] where r = rank(input).

* **largest - INT** (default is `'1'`):

  Whether to return the top-K largest or smallest elements.

* **sorted - INT** (default is `'1'`):

  Whether to return the elements in sorted order.

### Inputs

- **X** (heterogeneous) - **T**:

  Tensor of shape [a_0, a_1, ..., a_{n-1}]
- **K** (heterogeneous) - **tensor(int64)**:

  A 1-D tensor containing a single positive value corresponding to the number of top elements to retrieve

### Outputs

- **Values** (heterogeneous) - **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** (heterogeneous) - **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.

### Type Constraints

* **T** in ( `tensor(double)`, `tensor(float)`, `tensor(float16)`, `tensor(int16)`, `tensor(int32)`, `tensor(int64)`, `tensor(int8)`, `tensor(uint16)`, `tensor(uint32)`, `tensor(uint64)`, `tensor(uint8)` ):

  Constrain input and output types to numeric tensors.
* **I** in ( `tensor(int64)` ):

  Constrain index tensor to int64

```{toctree}
text_diff_TopK_10_11
```

(l-onnx-op-topk-10)=

## TopK - 10

### Version

- **name**: [TopK (GitHub)](https://github.com/onnx/onnx/blob/main/docs/Operators.md#TopK)
- **domain**: `main`
- **since_version**: `10`
- **function**: `False`
- **support_level**: `SupportType.COMMON`
- **shape inference**: `True`

This version of the operator has been available
**since version 10**.

### Summary

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:
  -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
 a tiebreaker. That is, the element with the lower index will appear first.

### Attributes

* **axis - INT** (default is `'-1'`):

  Dimension on which to do the sort.

### Inputs

- **X** (heterogeneous) - **T**:

  Tensor of shape [a_0, a_1, ..., a_{n-1}]
- **K** (heterogeneous) - **tensor(int64)**:

  A 1-D tensor containing a single positive value corresponding to the number of top elements to retrieve

### Outputs

- **Values** (heterogeneous) - **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** (heterogeneous) - **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.

### Type Constraints

* **T** in ( `tensor(double)`, `tensor(float)`, `tensor(float16)` ):

  Constrain input and output types to float tensors.
* **I** in ( `tensor(int64)` ):

  Constrain index tensor to int64

```{toctree}
text_diff_TopK_1_11
text_diff_TopK_1_10
```

(l-onnx-op-topk-1)=

## TopK - 1

### Version

- **name**: [TopK (GitHub)](https://github.com/onnx/onnx/blob/main/docs/Operators.md#TopK)
- **domain**: `main`
- **since_version**: `1`
- **function**: `False`
- **support_level**: `SupportType.COMMON`
- **shape inference**: `True`

This version of the operator has been available
**since version 1**.

### Summary

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:
  -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
 a tiebreaker. That is, the element with the lower index will appear first.

### Attributes

* **axis - INT** (default is `'-1'`):

  Dimension on which to do the sort.

* **k - INT** (required) :

  Number of top elements to retrieve

### Inputs

- **X** (heterogeneous) - **T**:

  Tensor of shape [a_0, a_1, ..., a_{n-1}]

### Outputs

- **Values** (heterogeneous) - **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** (heterogeneous) - **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.

### Type Constraints

* **T** in ( `tensor(double)`, `tensor(float)`, `tensor(float16)` ):

  Constrain input and output types to float tensors.
* **I** in ( `tensor(int64)` ):

  Constrain index tensor to int64