---
title: Result folding
slug: '1466'
canonical_url: https://docs.coveo.com/en/1466/
collection: build-a-search-ui
source_format: adoc
---
# Result folding
Result folding allows you to group [items](https://docs.coveo.com/en/210/) that have a certain [field](https://docs.coveo.com/en/200/) value in common, and identify parent-child relationships between those [items](https://docs.coveo.com/en/210/) in the [query](https://docs.coveo.com/en/231/) result set.

This article provides information and an example for using result folding in your search integration with the [Coveo Platform](https://docs.coveo.com/en/186/).

> **Notes**
>
> In a [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/) [search interface](https://docs.coveo.com/en/2741/), you can request folded [query](https://docs.coveo.com/en/231/) results using the `Folding` or `FoldingForThread` component, and render those results using the `ResultFolding` or `ResultAttachments` result template components.
> 
> * Result folding and [duplicate filtering](https://docs.coveo.com/en/13#operation/searchUsingPost-enableDuplicateFiltering) are mutually exclusive.

## Parameters

The following search request parameters allow you to request folded [query](https://docs.coveo.com/en/231/) results.

### `filterField` (String)

The @-prefixed name of the [field](https://docs.coveo.com/en/200/) to use to group [items](https://docs.coveo.com/en/210/) into distinct folded [query](https://docs.coveo.com/en/231/) results.

Use a [field](https://docs.coveo.com/en/200/) whose value is identical for all [items](https://docs.coveo.com/en/210/) to group under the same folded [query](https://docs.coveo.com/en/231/) result (for example, @folding_collection_id).

### `parentField` (String)

The @-prefixed name of the [field](https://docs.coveo.com/en/200/) to use to be able to identify an [item](https://docs.coveo.com/en/210/) as a parent in a folded [query](https://docs.coveo.com/en/231/) result.

Use a [field](https://docs.coveo.com/en/200/) whose value can uniquely identify each [item](https://docs.coveo.com/en/210/) (for example, @folding_item_id).
All [items](https://docs.coveo.com/en/210/) whose `childField` value is the same as the `parentField` value of another [item](https://docs.coveo.com/en/210/) are considered children of that other [item](https://docs.coveo.com/en/210/).

> **Important**
>
> In the [index](https://docs.coveo.com/en/204/), the values of the `parentField` must only contain alphanumeric characters.
> Using a `parentField` whose values contain non-[indexable](https://docs.coveo.com/en/204/) characters, such as underscores, will make folding fail.
> 
> For example, using a `parentField` containing values such as `message_123` will fail.
> The `parentField` should contain values such as `123` instead.
> 
> Moreover, the values of the `parentField` must contain `60` characters or less.
> `60` is the default maximum of characters for a word in the [index](https://docs.coveo.com/en/204/).

### `childField` (String)

The @-prefixed name of the [field](https://docs.coveo.com/en/200/) to use to be able to identify an [item](https://docs.coveo.com/en/210/) as a child of another [item](https://docs.coveo.com/en/210/) in a folded [query](https://docs.coveo.com/en/231/) result.

Use a [field](https://docs.coveo.com/en/200/) whose value points to the `parentField` value of the intended parent (for example, @folding_parent_item_id).
Whenever an [item](https://docs.coveo.com/en/210/) is a child of another [item](https://docs.coveo.com/en/210/), its `childField` value must be the same as the `parentField` value of that other [item](https://docs.coveo.com/en/210/).

> **Important**
>
> In the [index](https://docs.coveo.com/en/204/), the values of the `childField` must only contain alphanumeric characters.
> Using a `childField` whose values contain non-[indexable](https://docs.coveo.com/en/204/) characters, such as underscores, will make folding fail.
> 
> For example, using a `childField` containing values such as `message_123` will fail.
> The `childField` should contain values such as `123` instead.
> 
> Moreover, the values of the `childField` must contain `60` characters or less.
> `60` is the default maximum of characters for a word in the [index](https://docs.coveo.com/en/204/).

### `filterFieldRange` (Unsigned Integer)

The maximum number of [items](https://docs.coveo.com/en/210/) to include in the `childResults` array of a folded [query](https://docs.coveo.com/en/231/) result.

Default value is `5`.

## Example

In a [Coveo organization](https://docs.coveo.com/en/185/), you have a Push [source](https://docs.coveo.com/en/246/) that [indexes](https://docs.coveo.com/en/204/) forum post [items](https://docs.coveo.com/en/210/) (that is, messages and their attachments).

In the [indexing pipeline](https://docs.coveo.com/en/184/) [mapping](https://docs.coveo.com/en/217/) phase, a pushed forum post [item](https://docs.coveo.com/en/210/) notably populates the following set of [fields](https://docs.coveo.com/en/200/) in the [index](https://docs.coveo.com/en/204/):

* `@folding_collection_id` with a unique identifier for the conversation thread that the forum post [item](https://docs.coveo.com/en/210/) belongs to.
This [field](https://docs.coveo.com/en/200/) will be used as the `filterField` when requesting folded [query](https://docs.coveo.com/en/231/) results.

* `@folding_item_id` with a unique identifier for the forum post [item](https://docs.coveo.com/en/210/) itself.
This [field](https://docs.coveo.com/en/200/) will be used as the `parentField` when requesting folded [query](https://docs.coveo.com/en/231/) results.

* `@folding_parent_item_id` with the `@folding_item_id` value of the forum post [item](https://docs.coveo.com/en/210/) parent (when applicable).
This [field](https://docs.coveo.com/en/200/) will be used as the `childField` when requesting folded [query](https://docs.coveo.com/en/231/) results.

Currently, the following forum post [items](https://docs.coveo.com/en/210/) have been [indexed](https://docs.coveo.com/en/204/) through your Push [source](https://docs.coveo.com/en/246/):

```text
- Message 1
    @folding\_collection\_id: "1"
    @folding\_item\_id: "101"
    - Message 2
        @folding\_collection\_id: "1"
        @folding\_item\_id: "102"
        @folding\_parent\_item\_id: "101"
    - Message 3
        @folding\_collection\_id: "1"
        @folding\_item\_id: "103"
        @folding\_parent\_item\_id: "101"
        - Attachment 1
            @folding\_collection\_id: "1"
            @folding\_item\_id: "104"
            @folding\_parent\_item\_id: "103"
        - Attachment 2
            @folding\_collection\_id: "1"
            @folding\_item\_id: "105"
            @folding\_parent\_item\_id: "103"
    - Message 4
        @folding\_collection\_id: "1"
        @folding\_item\_id: "106"
        @folding\_parent\_item\_id: "101"
- Message 5
    @folding\_collection\_id: "2"
    @folding\_item\_id: "107"
    - Message 6
        @folding\_collection\_id: "2"
        @folding\_item\_id: "108"
        @folding\_parent\_item\_id: "107"
```

When you [query](https://docs.coveo.com/en/231/) your Push [source](https://docs.coveo.com/en/246/), you want the Search API to:

* Return matching [items](https://docs.coveo.com/en/210/) as folded [query](https://docs.coveo.com/en/231/) results based on the conversation thread they each belong to.

* Return only up to four child results per folded [query](https://docs.coveo.com/en/231/) result.

* Sort [query](https://docs.coveo.com/en/231/) results from oldest to newest.

To do so, you include the following payload in your search request to the Search API:

```json
{
  "filterField": "@folding_collection_id",
  "parentField": "@folding_item_id",
  "childField": "@folding_parent_item_id",
  "filterFieldRange": 4,
  "sortCriteria": "dateascending"
}
```

When the Search API returns, the response body contains the following [query](https://docs.coveo.com/en/231/) results.
For the sake of brevity, this sample only includes result [item](https://docs.coveo.com/en/210/) properties that are pertinent to the current use case:

```json
{
  "results": [
    {
      "title": "Message 1",
      "parentResult": null,
      "childResults": [
        {
          "title": "Message 2",
          "parentResult": {
            "title": "Message 1"
          }
        },
        {
          "title": "Message 3",
          "parentResult": {
            "title": "Message 1"
          }
        },
        {
          "title": "Attachment 1",
          "parentResult": {
            "title": "Message 3"
          }
        },
        {
          "title": "Attachment 2",
          "parentResult": {
            "title": "Message 3"
          }
        }
      ],
      "totalNumberOfChildResults": 4
    },
    {
      "title": "Message 5",
      "parentResult": null,
      "childResults": [
        {
          "title": "Message 6",
          "parentResult": {
            "title": "Message 5"
          }
        }
      ],
      "totalNumberOfChildResults": 1
    }
  ],
  "totalCount": 2
}
```

As you can see:

* The `results` array contains two folded [query](https://docs.coveo.com/en/231/) results, which are sorted from oldest to newest.

** The first folded [query](https://docs.coveo.com/en/231/) result contains the four oldest [items](https://docs.coveo.com/en/210/) whose `@folding_collection_id` [field](https://docs.coveo.com/en/200/) value is `"1"`.

** The second folded [query](https://docs.coveo.com/en/231/) result contains the [items](https://docs.coveo.com/en/210/) whose `@folding_collection_id` value is `"2"`.

* A folded [query](https://docs.coveo.com/en/231/) result **isn't** a recursive tree-like structure, but merely an [item](https://docs.coveo.com/en/210/) with a sorted array of `childResults`.

* Each folded result [item](https://docs.coveo.com/en/210/) (including the base [item](https://docs.coveo.com/en/210/)) has a `parentResult` property whose value points to its parent [item](https://docs.coveo.com/en/210/).
This property is currently `null` for the base [item](https://docs.coveo.com/en/210/) of both folded [query](https://docs.coveo.com/en/231/) results, as those items are "root" parents that don't themselves have parents.

If you were to perform another search request, this time using `relevancy` as a `sortCriteria`, the response could instead look like the following.
For the sake of brevity, this sample only includes result [item](https://docs.coveo.com/en/210/) properties that are pertinent to the current use case:

```json
{
  "results": [
    {
      "title": "Attachment 2",
      "parentResult": {
        "title": "Message 3"
      },
      "childResults": [
        {
          "title": "Attachment 1",
          "parentResult": {
            "title": "Message 3"
          }
        },
        {
          "title": "Message 3",
          "parentResult": {
            "title": "Message 1"
          }
        },
        {
          "title": "Message 2",
          "parentResult": {
            "title": "Message 1"
          }
        },
        {
          "parentResult": null,
          "title": "Message 1"
        }
      ],
      "totalNumberOfChildResults": 4
    },
    {
      "title": "Message 5",
      "parentResult": {
        "title": "Message 4"
      },
      "childResults": [
        {
          "parentResult": null,
          "title": "Message 4"
        }
      ],
      "totalNumberOfChildResults": 1
    }
  ],
  "totalCount": 2
}
```

As you can see:

* A folded [query](https://docs.coveo.com/en/231/) result doesn't necessarily have its "root" parent as a base [item](https://docs.coveo.com/en/210/).
The first [item](https://docs.coveo.com/en/210/) (and the ordering of its `childResults` array) is determined by the current `sortCriteria`.

* The [items](https://docs.coveo.com/en/210/) in the `childResults` array of a folded [query](https://docs.coveo.com/en/231/) result base [item](https://docs.coveo.com/en/210/) may consequently not even be children of that base [item](https://docs.coveo.com/en/210/).

In summary, the `childResults` array of a folded [query](https://docs.coveo.com/en/231/) result is a sorted array of [items](https://docs.coveo.com/en/210/) that have the same `filterField` [field](https://docs.coveo.com/en/200/) value.
This means that to display folded [query](https://docs.coveo.com/en/231/) result [items](https://docs.coveo.com/en/210/) in a graphical [search interface](https://docs.coveo.com/en/2741/) that **doesn't** rely on the [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/), you'll likely need to write client-side logic that will resolve parent-child relationships within each folded [query](https://docs.coveo.com/en/231/) result, using the `parentResult` property of each [item](https://docs.coveo.com/en/210/) (including the base [item](https://docs.coveo.com/en/210/)).