The response of a BQL query can be sorted on one or multiple queried fields.
The sorting uses the position of the field in the query, which is 0-based.

The sort key is a list of objects that can contain three keys:

  • index: an integer that can be 0 or greater
  • type: that can be metrics or dimensions (dimensions by default)
  • order: that can be asc or desc (asc by default)

Example BQL:

{
  "collections": ["search_console"],
  "periods": [
    ["2020-12-01", "2020-12-31"]
  ],
  "query": {
    "dimensions": ["url", "keyword"],
    "metrics": ["search_console.period_0.count_clicks"],
    "sort": [
      {
        "index": 0,
        "type": "metrics",
        "order": "desc",
      },
      0,
      {
        "index": 1,
        "order": "desc"
      }
    ]
  }
}

The result is sorted on three elements, in this order:

  1. The first metric in a descending order, meaning that the greatest number of clicks will appear first.
  2. The first dimension in an ascending order, meaning that when the number of clicks is the same, we sort by the URL in alphabetical order.
  3. The second dimension in a descending order, meaning that when the number of clicks is the same and the URLs are the same, then we filter on the keyword in a descending alphabetical order.

As seen in the example, we can omit some keys, and even omit a JSON object when filtering on a dimension in an ascending order.