> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-poc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# topn()

> Get the top N most common values from a space-saving aggregate

<Icon icon="tag" iconType="duotone" /> Since [1.16.0][toolkit-1.16.0]

Get the top N most common values from a space-saving aggregate. The space-saving aggregate can be created from either [`freq_agg`][freq-agg] or [`mcv_agg`][mcv-agg].

## Samples

Get the 20 most frequent `zip_codes` from an `employees` table:

```sql theme={"dark"}
SELECT topn(mcv_agg(20, zip_code)) FROM employees;
```

## Arguments

The syntax is:

```sql theme={"dark"}
topn (
    agg SpaceSavingAggregate,
    n INTEGER
) RETURNS SETOF AnyElement
```

| Name  | Type                 | Default | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----- | -------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agg` | SpaceSavingAggregate | -       | ✔        | A space-saving aggregate created using either [`freq_agg`][freq-agg] or [`mcv_agg`][mcv-agg]                                                                                                                                                                                                                                                                                                                                           |
| `n`   | INTEGER              | -       | ✔        | The number of values to return. Required only for frequency aggregates. For top N aggregates, defaults to target N of the aggregate itself, and requests for a higher N return an error. In some cases, the function might return fewer than N values. This might happen if a frequency aggregate doesn't contain N values above the minimum frequency, or if the data isn't skewed enough to support N values from a top N aggregate. |

## Returns

| Column | Type             | Description                                 |
| ------ | ---------------- | ------------------------------------------- |
| topn   | SETOF AnyElement | The N most-frequent values in the aggregate |

[freq-agg]: /api-reference/timescaledb-toolkit/frequency-analysis/freq_agg/freq_agg

[mcv-agg]: /api-reference/timescaledb-toolkit/frequency-analysis/freq_agg/mcv_agg

[toolkit-1.16.0]: https://github.com/timescale/timescaledb-toolkit/releases/tag/1.16.0