Computed Fields

A computed field is an aggregate operation (average, maximum, minimum, or sum) that is 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 takes into account 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 article describes the members 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).

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

Computed Field Parameters

This section provides reference documentation for the available computed field parameters.

field (string)

The name of the numeric field on which to perform the aggregate operation.

Tip: You should ensure that the Use cache for computed fields option is enabled for that field in your index in order to speed up evaluation (see Add or Edit Fields).

Sample value: @wordcount

operation (string)

The aggregate operation to perform on the field values.

The available operations are:

  • sum: get the sum of all values.
  • average: get the average of all values.
  • minimum: get the smallest value.
  • maximum: get the largest value.

Sample value: average