Group by operations

This is for:

Developer

In this article

Group By operation example
Computed fields

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.

Group By operation example

You want to request Group By values based on the @filetype field from the result set that matches the basic query expression (q) mostly harmless.

You want to limit the number of retrieved values to 4 using maximumNumberOfValues. You also want to 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"
    }
  ]
}

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.

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

Computed field example

You want to request Group By values based on the @author field from the result set that matches the constant query expression (cq) @source==Books.

You want to limit the number of retrieved values to 3 using maximumNumberOfValues. You also want to 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"
    }
  ]
}

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"
        }
      ]
    }
  ],
  ...
}

Reference

See the Search API groupBy parameters reference documentation.