--- title: Implement facets slug: '3199' canonical_url: https://docs.coveo.com/en/3199/ collection: build-a-search-ui source_format: adoc --- # Implement facets A [search interface](https://docs.coveo.com/en/2741/) often includes [facets](https://docs.coveo.com/en/198/) that allow the user to narrow down a [query](https://docs.coveo.com/en/231/) to a specific subset of result [items](https://docs.coveo.com/en/210/) by selecting one or more dynamic [filter](https://docs.coveo.com/en/2736/) values. This article provides guidelines for implementing _facets_ on your own, assuming that you can't use the [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/) or the [Atomic](https://docs.coveo.com/en/lcdf0264/) or [Headless](https://docs.coveo.com/en/lcdf0493/) libraries in your custom search integration with the [Coveo Platform](https://docs.coveo.com/en/186/). > **Note** > > As a reference, you may want to look at the source code of the [`DynamicFacet`](https://coveo.github.io/search-ui/components/dynamicfacet.html) component to see how it's implemented in the [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/). > **Warning** > > Prior to September 2024, these guidelines instructed users to log facet-specific `customData` in addition to the current `facetState` object. > The `customData` object is now deprecated and should no longer be used, since the `facetState` object is sufficient to log facet interactions. ## Standard facet actions The following table lists some actions that you may want to make available in a facet implementation. Every action belongs to a specific [Coveo Analytics event](https://docs.coveo.com/en/260/) category, and each entry indicates the `actionCause`, `eventType` and `eventValue` values that [must be logged](https://docs.coveo.com/en/1373/) when the action is performed. Each entry also includes a link to the corresponding implementation guidelines. [%header,cols="6"] |=== |Facet action |[Coveo Analytics event](https://docs.coveo.com/en/260/) |`actionCause` |`eventType` |`eventValue` |Implementation guidelines |Select a value |Search |`facetSelect` / `documentField` |N/A |N/A |[Toggle facet values](#toggle-facet-values) |Un-select a value |Search |`facetDeselect` / `documentField` / `breadcrumbFacet` |N/A |N/A |[Toggle facet values](#toggle-facet-values) |Reset selected |Search |`facetClearAll` / `breadcrumbResetAll` |N/A |N/A |[Toggle facet values](#toggle-facet-values) |Request more values |Custom |`showMoreFacetResults` |`dynamicFacet` |`showMoreFacetResults` |[Request additional facet values](#request-additional-facet-values) |Request less values |Custom |`showLessFacetResults` |`dynamicFacet` |`showLessFacetResults` |[Request additional facet values](#request-additional-facet-values) |Search for a value |N/A |N/A |N/A |N/A |[Perform facet search](#perform-facet-search) |=== > **Note** > > It's important to use the correct `actionCause`, `eventType` and `eventValue` values when logging an [event](https://docs.coveo.com/en/260/) for a specific type of action in a [search interface](https://docs.coveo.com/en/2741/). > Otherwise: > > * [Coveo Analytics reports](https://docs.coveo.com/en/266/) may become incoherent in the underlying [Coveo organization](https://docs.coveo.com/en/185/), especially if that [organization](https://docs.coveo.com/en/185/) powers both [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/) and custom [search interfaces](https://docs.coveo.com/en/2741/). > > * The [Coveo ML](https://docs.coveo.com/en/188/) service may not function properly. ## Request and render facets Conceptually, a [facet](https://docs.coveo.com/en/198/) relies on an existing [field](https://docs.coveo.com/en/200/) (for example, `@bookauthor`) to render a sorted list of [facet](https://docs.coveo.com/en/198/) values (for example, `Ernest Hemingway`, `Mark Twain`), each of which is accompanied by an estimated number of occurrences in the current [query](https://docs.coveo.com/en/231/) result set. You can request the necessary data to render one or more [facets](https://docs.coveo.com/en/198/) through the [`facets`](https://docs.coveo.com/en/13#operation/searchUsingPost-facets) query parameter. Each valid [object](https://docs.coveo.com/en/13#operation/searchUsingPost-facets) you include in the `facets` query parameter will populate a distinct object in the `facets` array of that [query](https://docs.coveo.com/en/231/) response body. Most of the time, when a [query](https://docs.coveo.com/en/231/) is sent from a faceted [search interface](https://docs.coveo.com/en/2741/), you'll want to request and render or update [facets](https://docs.coveo.com/en/198/). To do so, prepare a new [query](https://docs.coveo.com/en/231/). In the request body: . In the [`facets`](https://docs.coveo.com/en/13#operation/searchUsingPost-facets) query parameter, include a corresponding [`facet`](https://docs.coveo.com/en/13#operation/searchUsingPost-facets) object for each facet to display in the [search interface](https://docs.coveo.com/en/2741/). . In the `facet` object operation, set [`field`](https://docs.coveo.com/en/13#operation/searchUsingPost-facets) to the name of the [field](https://docs.coveo.com/en/200/) that the [facet](https://docs.coveo.com/en/198/) is based on (for example, `@bookauthor`). When the Search API returns, for each [facet](https://docs.coveo.com/en/198/) to render in the [search interface](https://docs.coveo.com/en/2741/): [[step2]] . In the [query](https://docs.coveo.com/en/231/) response body, retrieve the object in the `facets` array whose `field` value matches the [field](https://docs.coveo.com/en/200/) on which the [facet](https://docs.coveo.com/en/198/) relies. . Use the `value`, `numberOfResults`, and `state` attributes of each object in the `values` array from the [query](https://docs.coveo.com/en/231/) response to render or update the [facet](https://docs.coveo.com/en/198/). Call the Usage Analytics Write API to [log the corresponding search event](https://docs.coveo.com/en/1502/). In the request body, include an object containing the following key-value pairs in the `facetState` property for each non-idle [facet](https://docs.coveo.com/en/198/) value: * `"facetType": ` * `"field": ` * `"id": ` * `"state": ` * `"value": ` * `"displayValue": ` (optional) * `"facetPosition": ` (optional) * `"title": ` (optional) * `"valuePosition": <VALUE_POSITION>` (optional) where: * `<TYPE>` (string) is the [facet](https://docs.coveo.com/en/198/) data type (for example, `specific`). * `<FIELDNAME>` (string) is the `@`-prefixed name of the [field](https://docs.coveo.com/en/200/) that this [facet](https://docs.coveo.com/en/198/) is based on (for example, `@booklength`). * `<ID>` (string) is the unique identifier of the [facet](https://docs.coveo.com/en/198/) in which one or more values were toggled. Typically, this is the `@`-prefixed name of the [field](https://docs.coveo.com/en/200/) that this [facet](https://docs.coveo.com/en/198/) is based on (for example, `@booklength`). * `<STATE>` (string) is the current state of the [facet](https://docs.coveo.com/en/198/) value (either `auto_selected` or `selected`). * `<VALUE>` (string) is the name of the toggled [facet](https://docs.coveo.com/en/198/) value (for example, `Hardcover`). * `<DISPLAY_VALUE>` (string) is the display name of the [facet](https://docs.coveo.com/en/198/) value (for example, `Hardcover`). * `<FACET_POSITION>` (integer) is the 1-based position of the [facet](https://docs.coveo.com/en/198/) (for example, `1`). * `<TITLE>` (string) is the [facet](https://docs.coveo.com/en/198/) title (for example, `Format`) * `<VALUE_POSITION>` (integer) is the 1-based position of the value in the [facet](https://docs.coveo.com/en/198/) (for example, `2`). ### Examples of requesting and rendering facets . A customer accesses the Books4Fun [search interface](https://docs.coveo.com/en/2741/). Once loaded, the [search interface](https://docs.coveo.com/en/2741/) retrieves and renders the _Book Format_ and _Author_ [facets](https://docs.coveo.com/en/198/) with the following request: ```http POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1 ​ Accept: application/json Content-Type: application/json Authorization: Bearer **********-****-****-****-************ ``` **Payload (excerpt)** ```json { ... "q": "Doctor Sleep", "cq": "NOT @source==\"Movies4Fun\"", "numberOfResults": 0, ... "facets": [ { "facetId": "@bookformat", "field": "bookformat", "type": "specific", "currentValues": [], "currentValues": [ { "value": "Hardcover", "state": "selected", "preventAutoSelect": false } { "value": "Softcover", "state": "idle", "preventAutoSelect": false }, ... ], "numberOfValues": 3, ... }, { "field": "bookauthor", "facetId": "@bookauthor", "type": "specific", "sortCriteria": "occurrences", "currentValues": [], "currentValues": [ { "value": "Ernest Hemingway", "state": "idle", "preventAutoSelect": false }, { "value": "Mark Twain", "state": "idle", "preventAutoSelect": false } ], "numberOfValues": 6, "isFieldExpanded": true, "numberOfValues": 3, ... } ], ... "language": "en", "originLevel1": "Books4FunSearch", "originLevel2": "All", ... } ``` **200 OK response body (excerpt)** ```json { ... "facets": [ { "facetId": "@bookformat", "field": "bookformat", "moreValuesAvailable": true, "values": [ { "value": "Hardcover", "state": "idle", "state": "selected", "numberOfResults": 83 }, { "value": "Softcover", "state": "idle", "numberOfResults": 47 }, ... ], "indexScore": 0.435 }, { "facetId": "@bookauthor", "field": "bookauthor", "moreValuesAvailable": true, "values": [ { "value": "Ernest Hemingway", "state": "idle", "numberOfResults": 26 }, { "value": "Charles Dickens", "state": "idle", "numberOfResults": 24 }, { "value": "Ernest Hemingway", "state": "idle", "numberOfResults": 26 }, { "value": "Mark Twain", "state": "idle", "numberOfResults": 23 }, { "value": "Stephen King", "state": "idle", "numberOfResults": 14 }, ... ], "indexScore": 0.435 } ], ... } ``` . Logging a search event for this action: ```http POST https://myorgid.analytics.org.coveo.com/rest/ua/v15/analytics/searches?visitor=********-****-****-******** HTTP/1.1 ​ Accept: application/json Content-Type: application/json Authorization: Bearer **********-****-****-****-************ ``` **Payload (excerpt)** [source,json,subs="attributes+"] ``` [ { "actionCause": "showMoreFacetResults", "eventType": "dynamicFacet", "eventValue": "showMoreFacetResults", ... "facetState": [ { "field": "@bookformat", "id": "@bookformat", "title": "Format", "facetType": "specific", "facetPosition": 1, "value": "Hardcover", "valuePosition": 2, "displayValue": "Hardcover", "state": "selected" } ] "facetState": [] } ] ``` ## Toggle facet values In a typical [faceted](https://docs.coveo.com/en/198/) [search interface](https://docs.coveo.com/en/2741/), the user can toggle (that is, select or un-select) any number of [facet](https://docs.coveo.com/en/198/) values to alter the [`facets`](https://docs.coveo.com/en/13#operation/searchUsingPost-facets) [query](https://docs.coveo.com/en/231/) parameter. When the user interacts with a [facet](https://docs.coveo.com/en/198/) in this way, prepare a new [query](https://docs.coveo.com/en/231/). For each [facet](https://docs.coveo.com/en/198/) currently displayed in the [search interface](https://docs.coveo.com/en/2741/), include a corresponding object in the `facets` [query](https://docs.coveo.com/en/231/) parameter: . Set `facetId` to the unique identifier of the [facet](https://docs.coveo.com/en/198/). . Set `field` to the [field](https://docs.coveo.com/en/200/) name that the [facet](https://docs.coveo.com/en/198/) is based on. . Set `type` to `specific`. . If the [facet](https://docs.coveo.com/en/198/) is the one that was just interacted with, set `freezeCurrentValues` to `true`. . If more than the originally specified `numberOfResults` are being requested for the [facet](https://docs.coveo.com/en/198/), set `isFieldExpanded` to `true` (see [Request additional facet values](#request-additional-facet-values)). . For each value currently displayed in the [facet](https://docs.coveo.com/en/198/), include a corresponding object in the [`currentValues`](https://docs.coveo.com/en/13#tag/Search-V2/operation/searchUsingGet-facets-currentValues) array: .. Set the `value` property to the value of the current [facet](https://docs.coveo.com/en/198/). .. Set the `state` property to `idle` if the [facet](https://docs.coveo.com/en/198/) isn't selected, or set it to `selected` otherwise. .. Set `preventAutoSelect` property to `false` to ensure that [Coveo ML](https://docs.coveo.com/en/188/) automatically selects the [facet](https://docs.coveo.com/en/198/) value. . Call the Search API to [execute this query](https://docs.coveo.com/en/1445/). When the Search API returns, call the Usage Analytics Write API to [log the corresponding search event](https://docs.coveo.com/en/1502/). In the request body: . Set the `actionCause` property to: ** `facetSelect` if the user has selected a single [facet](https://docs.coveo.com/en/198/) value. ** `facetUnselect` if the user has un-selected a single [facet](https://docs.coveo.com/en/198/) value. ** `facetClearAll` if the user has cleared all previously selected values. . For each non-idle [facet](https://docs.coveo.com/en/198/), include an object containing the following key-value pairs in the `facetState` property: -- ** `"facetType": <TYPE>` ** `"field": <FIELDNAME>` ** `"id": <ID>` ** `"state": <STATE>` ** `"value": <VALUE>` ** `"displayValue": <DISPLAY_VALUE>`(optional) ** `"facetPosition": <FACET_POSITION>` (optional) ** `"title": <TITLE>`(optional) ** `"valuePosition": <VALUE_POSITION>` (optional) -- where: -- ** `<TYPE>` (string) is the [facet](https://docs.coveo.com/en/198/) data type (for example, `specific`). ** `<FIELDNAME>` (string) is the `@`-prefixed name of the [field](https://docs.coveo.com/en/200/) that this [facet](https://docs.coveo.com/en/198/) is based on (for example, `@booklength`). ** `<ID>` (string) is the unique identifier of the [facet](https://docs.coveo.com/en/198/) in which one or more values were toggled. Typically, this is the `@`-prefixed name of the [field](https://docs.coveo.com/en/200/) that this [facet](https://docs.coveo.com/en/198/) is based on (for example, `@booklength`). ** `<STATE>` (string) is the current state of the [facet](https://docs.coveo.com/en/198/) value (either `auto_selected` or `selected`). ** `<VALUE>` (string) is the name of the toggled [facet](https://docs.coveo.com/en/198/) value (for example, `Hardcover`). ** `<DISPLAY_VALUE>` (string) is the display name of the [facet](https://docs.coveo.com/en/198/) value (for example, `Hardcover`). ** `<FACET_POSITION>` (integer) is the 1-based position of the [facet](https://docs.coveo.com/en/198/) (for example, `1`). ** `<TITLE>` (string) is the [facet](https://docs.coveo.com/en/198/) title (for example, `Format`) ** `<VALUE_POSITION>` (integer) is the 1-based position of the value in the [facet](https://docs.coveo.com/en/198/) (for example, `2`). -- . Set other required or optional properties as needed, such as `language`, `[originLevel1](https://docs.coveo.com/en/1337/)`, or `[originLevel2](https://docs.coveo.com/en/1338/)`. When the Usage Analytics Write API returns successfully: . [Update all of the facets](#request-and-render-facets) in the [search interface](https://docs.coveo.com/en/2741/). . [Update the result list](https://docs.coveo.com/en/1372#render-query-results). ### Interact with a facet indirectly The [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/) includes components that allow users to interact with [facets](https://docs.coveo.com/en/198/) indirectly, such as the [`Breadcrumb`](https://coveo.github.io/search-ui/components/breadcrumb.html) and [`FieldValue`](https://coveo.github.io/search-ui/components/fieldvalue.html) components. If you implement your own components, be sure to use the appropriate `actionCause` value when logging a search [event](https://docs.coveo.com/en/260/) after the user has indirectly toggled one or more [facet](https://docs.coveo.com/en/198/) values: [%header,cols="2"] |=== |Action |`actionCause` |Select or un-select a single [facet](https://docs.coveo.com/en/198/) value by interacting with a [query](https://docs.coveo.com/en/231/) result |`documentField` |Un-select a single [facet](https://docs.coveo.com/en/198/) value by interacting with [breadcrumbs](https://docs.coveo.com/en/2731/) |`breadcrumbFacet` |Clear all selected [facet](https://docs.coveo.com/en/198/) values by interacting with [breadcrumbs](https://docs.coveo.com/en/2731/) |`breadcrumbResetAll` |=== ### Examples of toggling facet values . A customer is browsing products on the Books4Fun site. They select the `Hardcover` value from the _Book Format_ facet, which executes the following query: ```http POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1 ​ Accept: application/json Content-Type: application/json Authorization: Bearer **********-****-****-****-************ ``` **Payload (excerpt)** ```json { ... "q": "Doctor Sleep", "cq": "NOT @source==\"Movies4Fun\"", "numberOfResults": 0, ... "facets": [ { "facetId": "@bookformat", "field": "bookformat", "type": "specific", "currentValues": [], "currentValues": [ { "value": "Hardcover", "state": "selected", "preventAutoSelect": false } { "value": "Softcover", "state": "idle", "preventAutoSelect": false }, ... ], "numberOfValues": 3, ... }, { "field": "bookauthor", "facetId": "@bookauthor", "type": "specific", "sortCriteria": "occurrences", "currentValues": [], "currentValues": [ { "value": "Ernest Hemingway", "state": "idle", "preventAutoSelect": false }, { "value": "Mark Twain", "state": "idle", "preventAutoSelect": false } ], "numberOfValues": 6, "isFieldExpanded": true, "numberOfValues": 3, ... } ], ... "language": "en", "originLevel1": "Books4FunSearch", "originLevel2": "All", ... } ``` **200 OK response body (excerpt)** ```json { ... "facets": [ { "facetId": "@bookformat", "field": "bookformat", "moreValuesAvailable": true, "values": [ { "value": "Hardcover", "state": "idle", "state": "selected", "numberOfResults": 83 }, { "value": "Softcover", "state": "idle", "numberOfResults": 47 }, ... ], "indexScore": 0.435 }, { "facetId": "@bookauthor", "field": "bookauthor", "moreValuesAvailable": true, "values": [ { "value": "Ernest Hemingway", "state": "idle", "numberOfResults": 26 }, { "value": "Charles Dickens", "state": "idle", "numberOfResults": 24 }, { "value": "Ernest Hemingway", "state": "idle", "numberOfResults": 26 }, { "value": "Mark Twain", "state": "idle", "numberOfResults": 23 }, { "value": "Stephen King", "state": "idle", "numberOfResults": 14 }, ... ], "indexScore": 0.435 } ], ... } ``` . Logging a search event for this action: ```http POST https://myorgid.analytics.org.coveo.com/rest/ua/v15/analytics/searches?visitor=********-****-****-******** HTTP/1.1 ​ Accept: application/json Content-Type: application/json Authorization: Bearer **********-****-****-****-************ ``` **Payload (excerpt)** [source,json,subs="attributes+"] ``` [ { "actionCause": "showMoreFacetResults", "eventType": "dynamicFacet", "eventValue": "showMoreFacetResults", ... "facetState": [ { "field": "@bookformat", "id": "@bookformat", "title": "Format", "facetType": "specific", "facetPosition": 1, "value": "Hardcover", "valuePosition": 2, "displayValue": "Hardcover", "state": "selected" } ] "facetState": [] } ] ``` ## Request additional facet values The [`numberOfValues`](https://docs.coveo.com/en/13#operation/searchUsingPost-facets-numberOfValues) [facet](https://docs.coveo.com/en/198/) request parameter lets you specify the maximum number of [facet](https://docs.coveo.com/en/198/) values that the [index](https://docs.coveo.com/en/204/) may retrieve to populate the `values` array of a given `facet` object (the default value is `8`). You may also want to allow the user to autonomously request to display more values in a [facet](https://docs.coveo.com/en/198/). When the user interacts with a [facet](https://docs.coveo.com/en/198/) in this way, prepare a new [query](https://docs.coveo.com/en/231/): . Set the [`numberOfResults`](https://docs.coveo.com/en/13#operation/searchUsingPost-numberOfResults) [query](https://docs.coveo.com/en/231/) parameter to `0`. . In the [`facets`](https://docs.coveo.com/en/13#operation/searchUsingPost-facets) [query](https://docs.coveo.com/en/231/) parameter, include the [`facet`](https://docs.coveo.com/en/13#operation/searchUsingPost-facets) object for which the user has requested additional values. . In the `facet` object operation, set [`field`](https://docs.coveo.com/en/13#operation/searchUsingPost-facets) to the name of the [field](https://docs.coveo.com/en/200/) that the [facet](https://docs.coveo.com/en/198/) is based on (for example, `@bookauthor`). . For each value currently displayed in the [facet](https://docs.coveo.com/en/198/), include a corresponding object in the [`currentValues`](https://docs.coveo.com/en/13#operation/searchUsingPost-facets) array: .. Set the `value` property to the value of the current [facet](https://docs.coveo.com/en/198/). .. Set the `state` property to `idle` if the [facet](https://docs.coveo.com/en/198/) isn't selected, or set it to `selected` otherwise. .. Set `preventAutoSelect` property to `false` to ensure that [Coveo ML](https://docs.coveo.com/en/188/) automatically selects the [facet](https://docs.coveo.com/en/198/) value. . Set [`numberOfValues`](https://docs.coveo.com/en/13#operation/searchUsingPost-facets-numberOfValues) to a higher value than the one that was specified the last time the [facet](https://docs.coveo.com/en/198/) was requested (for example, `16`). . Set [`isFieldExpanded`](https://docs.coveo.com/en/13#operation/searchUsingPost-facets-isFieldExpanded) to `true`. . Set all of the other [facet](https://docs.coveo.com/en/198/) request parameters to the same values as the last time the [facet](https://docs.coveo.com/en/198/) was requested. > **Note** > > Although this [query](https://docs.coveo.com/en/231/) isn't meant to return actual result [items](https://docs.coveo.com/en/210/), you should include the other search request parameters as usual. > This way, it will represent the current state of the [search interface](https://docs.coveo.com/en/2741/), aside from `numberOfResults` being forcefully set to `0` and `facets` not necessarily containing all of the operations required to update [facets](https://docs.coveo.com/en/198/). > Otherwise, the retrieved `facets` object may not contain accurate or consistent [facet](https://docs.coveo.com/en/198/) values or occurrence counts. . Call the Search API to [execute this query](https://docs.coveo.com/en/1445/). When the Search API returns, call the Usage Analytics Write API to [log the corresponding custom event](https://docs.coveo.com/en/2650/). In the request body: . Set the `actionCause` property to `showMoreFacetResults` when showing more results or `showLessFacetResults` when showing less. . Set the `eventType` property to `dynamicFacet`. . Set the `eventValue` property to `showMoreFacetResults` when showing more results or `showLessFacetResults` when showing less. . Set other required or optional properties as needed, such as `language`, `[originLevel1](https://docs.coveo.com/en/1337/)`, or `[originLevel2](https://docs.coveo.com/en/1338/)`. When the Usage Analytics Write API returns successfully, [re-render the facet](#step2) as appropriate. ### Examples of requesting additional facet values . A customer is browsing products on the Books4Fun site. They can't find their favourite author among the currently rendered values in the _Author_ [facet](https://docs.coveo.com/en/198/), so they request to display more values. This interaction executes the following request: ```http POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1 ​ Accept: application/json Content-Type: application/json Authorization: Bearer **********-****-****-****-************ ``` **Payload (excerpt)** ```json { ... "q": "Doctor Sleep", "cq": "NOT @source==\"Movies4Fun\"", "numberOfResults": 0, ... "facets": [ { "facetId": "@bookformat", "field": "bookformat", "type": "specific", "currentValues": [], "currentValues": [ { "value": "Hardcover", "state": "selected", "preventAutoSelect": false } { "value": "Softcover", "state": "idle", "preventAutoSelect": false }, ... ], "numberOfValues": 3, ... }, { "field": "bookauthor", "facetId": "@bookauthor", "type": "specific", "sortCriteria": "occurrences", "currentValues": [], "currentValues": [ { "value": "Ernest Hemingway", "state": "idle", "preventAutoSelect": false }, { "value": "Mark Twain", "state": "idle", "preventAutoSelect": false } ], "numberOfValues": 6, "isFieldExpanded": true, "numberOfValues": 3, ... } ], ... "language": "en", "originLevel1": "Books4FunSearch", "originLevel2": "All", ... } ``` **200 OK response body (excerpt)** ```json { ... "facets": [ { "facetId": "@bookformat", "field": "bookformat", "moreValuesAvailable": true, "values": [ { "value": "Hardcover", "state": "idle", "state": "selected", "numberOfResults": 83 }, { "value": "Softcover", "state": "idle", "numberOfResults": 47 }, ... ], "indexScore": 0.435 }, { "facetId": "@bookauthor", "field": "bookauthor", "moreValuesAvailable": true, "values": [ { "value": "Ernest Hemingway", "state": "idle", "numberOfResults": 26 }, { "value": "Charles Dickens", "state": "idle", "numberOfResults": 24 }, { "value": "Ernest Hemingway", "state": "idle", "numberOfResults": 26 }, { "value": "Mark Twain", "state": "idle", "numberOfResults": 23 }, { "value": "Stephen King", "state": "idle", "numberOfResults": 14 }, ... ], "indexScore": 0.435 } ], ... } ``` . Logging a custom [event](https://docs.coveo.com/en/260/) for this action: ```http POST https://myorgid.analytics.org.coveo.com/rest/ua/v15/analytics/custom?visitor=********-****-****-******** HTTP/1.1 ​ Accept: application/json Content-Type: application/json Authorization: Bearer **********-****-****-****-************ ``` **Payload (excerpt)** [source,json,subs="attributes+"] ``` [ { "actionCause": "showMoreFacetResults", "eventType": "dynamicFacet", "eventValue": "showMoreFacetResults", ... "facetState": [ { "field": "@bookformat", "id": "@bookformat", "title": "Format", "facetType": "specific", "facetPosition": 1, "value": "Hardcover", "valuePosition": 2, "displayValue": "Hardcover", "state": "selected" } ] "facetState": [] } ] ``` ## Perform facet search > **Note** > > The following guidelines suggest a [facet](https://docs.coveo.com/en/198/) search implementation which is similar to that of the [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/) (that is, wildcard pattern matching as the user types). > You may opt to use an entirely different approach for your own implementation. You may want to allow the user to look for specific [facet](https://docs.coveo.com/en/198/) values by typing into a dedicated search input within a [facet](https://docs.coveo.com/en/198/). When the user interacts with a [facet](https://docs.coveo.com/en/198/) in this way, on each valid keystroke: . Retrieve the current value from the [facet](https://docs.coveo.com/en/198/) search input (for example, `a`). . Prepare a new [facet search request](https://platform.cloud.coveo.com/docs?urls.primaryName=Search%20API#/Search/facetSearch). In the request body: .. Set the `field` property to the name of the [field](https://docs.coveo.com/en/200/) that the [facet](https://docs.coveo.com/en/198/) being searched is based on (for example, `bookauthor`). .. Set the `query` property to the `**`-prefixed and `**`-suffixed value that was retrieved in step 1 (for example, `a` becomes `**a**`). .. Set the `numberOfValues` property to the maximum number of matching values to retrieve through [facet](https://docs.coveo.com/en/198/) search (for example, `4`). The default value is `10`. .. Set other optional properties as needed, such as `ignoreValues` or `captions`. . Set all of the other [facet](https://docs.coveo.com/en/198/) request parameters to the same values as the last time the [facet](https://docs.coveo.com/en/198/) was requested. > **Note** > > Although this [query](https://docs.coveo.com/en/231/) isn't meant to return actual result [items](https://docs.coveo.com/en/210/), you should include the other search request parameters as usual. > This way, it will represent the current state of the [search interface](https://docs.coveo.com/en/2741/), aside from `numberOfResults` being forcefully set to `0` and `facets` not necessarily containing all of the operations required to update [facets](https://docs.coveo.com/en/198/). > Otherwise, the retrieved `facets` object may not contain accurate or consistent [facet](https://docs.coveo.com/en/198/) values or occurrence counts. . Call the Search API to [execute this query](https://docs.coveo.com/en/1445/). . When the Search API returns, [render the retrieved facet values](#step2) using the `displayValue` and `count` values of each object in the `values` array in the response body. ### Example of performing facet search A customer is browsing products on the Books4Fun site. They can't find their favourite author among the currently rendered values in the _Author_ [facet](https://docs.coveo.com/en/198/), so they begin typing the author's name into the [facet](https://docs.coveo.com/en/198/) search box. This interaction executes the following request: ```http POST https://myorganizationid9sd8df7s.org.coveo.com/rest/search/v2/facet HTTP/1.1 ​ Accept: application/json Content-Type: application/json Authorization: Bearer **********-****-****-****-************ ``` **Payload (excerpt)** ```json { "field": "bookauthor", "numberOfValues": 4, "query": "*W*" } ``` **200 OK response body (excerpt)** ```json { "values": [ { "displayValue": "William Shakespeare", "rawValue": "William Shakespeare", "count": 10 }, { "displayValue": "William Faulkner", "rawValue": "William Faulkner", "count": 5 }, ... ], "moreValuesAvailable": false } ```