#docs #tql

Top N Query

Groups a set of events by a dimension and aggregates them by a metric.

A Top N query allows you to list the top N values of a dimension, ordered by a metric. For example, you can list the top 10 versions of your app by number of users.


  "aggregations": [{ "name": "count", "type": "count" }],
  "dataSource": "telemetry-signals",
  "dimension": {
    "dimension": "appVersion",
    "outputName": "appVersion",
    "type": "default"
  "granularity": "all",
  "metric": {
    "ordering": "version",
    "type": "dimension"
  "filter": {
    "dimension": "appID",
    "type": "selector",
    "value": "AAABBBCCC"
  "queryType": "topN",
  "threshold": 10


All default properties and the following properties are supported:

dimensionA single DimensionSpec defining the dimension that you want the top taken for.
metricA TopNMetricSpec object specifying the metric to sort by for the top list.
threshold (optional)An integer defining the N in the topN (how many results you want in the top list).