Group by operations

This is for:

Developer
In this article

A Group By operation allows retrieval of the different available values of a field in an unpaginated query result set, along with an estimated number of occurrences for each retrieved value. Group By operations also support advanced options such as computing aggregate operations on other numeric fields for each retrieved value.

This article provides example Group By operations. You can specify an array of Group By operations in a query using the groupBy top-level query parameter.

In a graphical search interface, Group By operations are typically used to retrieve data to render facets.

Example

You want to request Group By values based of the @filetype field from the result set that matches the mostly harmless basic query expression (q). You also want to limit the number of retrieved values to 4 (using maximumNumberOfValues), and sort those values in ascending alphabetical order (using sortCriteria).

POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "q": "mostly harmless",
  "groupBy": [
    {
      "field": "@filetype",
      "maximumNumberOfValues": 4,
      "sortCriteria": "AlphaAscending"
    }
  ]
}
Tip

200 OK response body (excerpt)

{
  ...
  "groupByResults": [
    {
      "field": "filetype",
      "globalComputedFieldResults": [],
      "values": [
        {
          "computedFieldResults": [],
          "lookupValue": "epub",
          "numberOfResults": 3,
          "score": 0,
          "value": "epub",
          "valueType": "Standard"
        },
        {
          "computedFieldResults": [],
          "lookupValue": "mobi",
          "numberOfResults": 1,
          "score": 0,
          "value": "mobi",
          "valueType": "Standard"
        },
        {
          "computedFieldResults": [],
          "lookupValue": "pdf",
          "numberOfResults": 2,
          "score": 0,
          "value": "pdf",
          "valueType": "Standard"
        },
        {
          "computedFieldResults": [],
          "lookupValue": "txt",
          "numberOfResults": 1,
          "score": 0,
          "value": "txt",
          "valueType": "Standard"
        }
      ]
    }
  ],
  ...
}

Computed fields

A computed field is an aggregate operation (average, maximum, minimum, or sum) that’s performed on a specific numeric field during a Group By operation. This aggregate operation is computed for each value retrieved by its parent Group By operation, and considers the values of its target numeric field for each item sharing the same Group By field value in the un-paginated query result set.

This section provides an example of the structure that defines a single computed field operation. You can specify an array of computed field operations in a Group By operation using the computedFields Group By parameter.

Important

You can only perform computed field operations on numeric fields. Otherwise, the aggregate operation will return NaN (not a number).

Example

You want to request Group By values based of the @author field from the result set that matches the @source==Books constant query expression (cq). You also want to limit the number of retrieved values to 3 (using maximumNumberOfValues), and compute the average of the @communityrating field for each of those values (using computedFields) to sort them in descending order (using sortCriteria).

POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "cq": "@source==Books",
  "groupBy": [
    {
      "field": "@author",
      "computedFields": [
        {
          "field": "@communityrating",
          "operation": "average"
        }
      ],
      "maximumNumberOfValues": 3,
      "sortCriteria": "ComputedFieldDescending"
    }
  ]
}
Tip

200 OK response body (excerpt)

{
  ...
  "groupByResults": [
    {
      "field": "author",
      "globalComputedFieldResults": [
        7.110552764
      ],
      "values": [
        {
          "computedFieldResults": [
            9.850877193
          ],
          "lookupValue": "George Orwell",
          "numberOfResults": 12,
          "score": 0,
          "value": "George Orwell",
          "valueType": "Standard"
        },
        {
          "computedFieldResults": [
            9.321762292
          ],
          "lookupValue": "J. R. R. Tolkien",
          "numberOfResults": 30,
          "score": 0,
          "value": "J. R. R. Tolkien",
          "valueType": "Standard"
        },
        {
          "computedFieldResults": [
            9.114909274
          ],
          "lookupValue": "John Steinbeck",
          "numberOfResults": 17,
          "score": 0,
          "value": "John Steinbeck",
          "valueType": "Standard"
        }
      ]
    }
  ],
  ...
}