#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.
thresholdAn integer defining the N in the topN (how many results you want in the top list).