# rank

> AQL Window Function: A window function that returns the rank of rows within a partition of a table. Tie values are assigned the same rank. The next rank in the sequence is not consecutive. E.g. 1, 1, 3, 4, 4, 6, ...


:::tip Knowledge Checkpoint
Readings that will help you understand this documentation better:
- [Window Functions Overview](/reference/aql/window-function)
:::

## Definition
A window function that returns the rank of rows within a partition of a table. Tie values are assigned the same rank. The next rank in the sequence is not consecutive. E.g. 1, 1, 3, 4, 4, 6, ...

To get consecutive rank, use [dense_rank](/reference/aql/dense_rank).

**Syntax**
```aml
rank(order: order_expr)
rank(order: order_expr, ..., partition: partition_expr, ...)
```

```aml title="Examples"
rank(order: count(orders.id) | desc())
rank(order: count(orders.id), order: average(users.age))

// with partition
rank(order: count(orders.id), partition: orders.status)

// Axis-aware examples
rank(order: 'rows')                              // Rank by row/x-axis order
rank(order: 'columns' | desc())                  // Rank by column/legend order (descending)
rank(order: revenue | desc(), partition: 'rows') // Rank within each row
```

**Input**
- `order` (**required**, **repeatable**): A field that is used for ordering. The order defaults to ascending. The order can be set explicitly with `asc()` or `desc()`. You can also use [axis references](/reference/aql/window-function#axis-aware-window-functions):
  - `'rows'` or `'x_axis'`: Order by dimensions mapped to rows/x-axis
  - `'columns'` or `'legend'`: Order by dimensions mapped to columns/legend
  - E.g. `rank(order: count(orders.id) | desc())` or `rank(order: 'rows')`
- `partition` (**repeatable**, **optional**): A field that is used for partitioning the table. You can use [axis references](/reference/aql/window-function#axis-aware-window-functions) like `'rows'`, `'columns'`, `'x_axis'`, or `'legend'`. E.g. `rank(order: count(orders.id), partition: orders.status)` or `rank(order: revenue, partition: 'rows')`

**Output**

Rank of the current row within its partition (if no partition is specified, the whole table is considered as a single partition). If two rows are tied for a rank, each tied rows receives the same rank. The next rank in the sequence is not consecutive. E.g. 1, 1, 3, 4, 4, 6, ...

## Sample Usages

<SampleCode title="Rank top buyer by gender and age group" rawResult={example1} />

<SampleCode title="Rank top buyer by age group partition by gender" rawResult={example2} />

Using rank in a dimension definition is straight-forward. Remember that the rank is calculated against all rows in the model.

```aml
dimension ranking_by_age {
  label: 'Rank By Age'
  type: 'number'
  hidden: false
  description: ''
  definition: @aql rank(order: users.age | desc()) ;;
}
```

You can see that users with the same age are assigned the same rank

<SampleCode title="Rank users by Age" rawResult={example3} />

You can also use it in `filter()` to filter out the top 10 users by age:

<SampleCode title="Filter top 1 Youngest Users" rawResult={example4} />

## See also

- [`dense_rank()`](/reference/aql/dense_rank): same value gets same rank, no gaps
- [`percent_rank()`](/reference/aql/percent_rank)
- [`ntile()`](/reference/aql/ntile)
- [Window Functions](/reference/aql/window-function)