---
title: Group by operations
slug: '1453'
canonical_url: https://docs.coveo.com/en/1453/
collection: build-a-search-ui
source_format: adoc
---
# Group by operations
A [Group By](https://docs.coveo.com/en/203/) operation allows retrieval of the different available values of a [field](https://docs.coveo.com/en/200/) in an unpaginated [query](https://docs.coveo.com/en/231/) result set, along with an estimated number of occurrences for each retrieved value.
[Group By](https://docs.coveo.com/en/203/) operations also support advanced options such as computing aggregate operations on other numeric [fields](https://docs.coveo.com/en/200/) for each retrieved value.

This article provides example [Group By](https://docs.coveo.com/en/203/) operations.
You can specify an array of [Group By](https://docs.coveo.com/en/203/) operations in a [query](https://docs.coveo.com/en/231/) using the [`groupBy`](https://docs.coveo.com/en/13#operation/searchUsingPost-groupBy) top-level [query](https://docs.coveo.com/en/231/) parameter.

In a graphical [search interface](https://docs.coveo.com/en/2741/), [Group By](https://docs.coveo.com/en/203/) operations are typically used to retrieve data to render [facets](https://docs.coveo.com/en/198/).

## Group By operation example

You want to request [Group By](https://docs.coveo.com/en/203/) values based on the `@filetype` [field](https://docs.coveo.com/en/200/) from the result set that matches the [basic query expression (`q`)](https://docs.coveo.com/en/178/) `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`.

```http
POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload**

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

**200 OK response body (excerpt)**

```json
{
  ...
  "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](https://docs.coveo.com/en/200/) during a [Group By](https://docs.coveo.com/en/203/) operation.
This aggregate operation is computed for each value retrieved by its parent [Group By](https://docs.coveo.com/en/203/) operation, and considers the values of its target numeric [field](https://docs.coveo.com/en/200/) for each [item](https://docs.coveo.com/en/210/) sharing the same [Group By](https://docs.coveo.com/en/203/) [field](https://docs.coveo.com/en/200/) value in the un-paginated [query](https://docs.coveo.com/en/231/) result set.

This section provides an example of the structure that defines a single computed [field](https://docs.coveo.com/en/200/) operation.
You can specify an array of computed [field](https://docs.coveo.com/en/200/) operations in a [Group By](https://docs.coveo.com/en/203/) operation using the [`computedFields`](https://docs.coveo.com/en/13#operation/searchUsingPost-groupBy-computedFields) [Group By](https://docs.coveo.com/en/203/) parameter.

> **Important**
>
> You can only perform computed [field](https://docs.coveo.com/en/200/) operations on numeric [fields](https://docs.coveo.com/en/200/).
> Otherwise, the aggregate operation will return `NaN` (not a number).

### Computed field example

You want to request [Group By](https://docs.coveo.com/en/203/) values based on the `@author` [field](https://docs.coveo.com/en/200/) from the result set that matches the [constant query expression (`cq`)](https://docs.coveo.com/en/179/) `@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](https://docs.coveo.com/en/200/) for each of those values using `computedFields` to sort them in descending order using `sortCriteria`.

```http
POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload**

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

**200 OK response body (excerpt)**

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