About the Facet Generator

This is for:

Developer System Administrator

The Facet Generator is a search interface helper that dynamically generates the most relevant facets for a query, based on your indexed content. These facets appear next to the ones you manually added to your search interface.

It’s not a Coveo Machine Learning feature, but works as a complement to the Dynamic Navigation Experience (DNE) model. However, unlike the DNE model, the Facet Generator works immediately after you enable it, without any training period. This makes it especially relevant when your search interface is going live and you don’t have a lot of usage analytics data yet.

The Facet Generator is most beneficial for commerce search interfaces that have a large number of product attributes, as well as workplace or customer service interfaces.

It specifically aims at:

  • Making it easy to display relevant facets in a search interface, especially in catalogs with a large number of product attributes.

  • Bringing relevant experiences to search interface users immediately, without the training time and usage analytics data that a Coveo ML model usually requires.

  • Enabling end-users to quickly find the product they want.

Example

In a commerce search interface, before a customer makes any query, the facets displayed are generic, such as Category, Brand, and Price.

When a customer searches for Surf Board, the Facet Generator updates the facet list to show the most relevant for this query.

Some facets are specific to surf boards, such as Fin System and Tail Shape, while others are more generic, such as Color, Brand, and Price. Together, they help the customer find the surf board they want.

Example of DNE facets generated for surf board search | Coveo Machine Learning

Change Facet Generator options

Once implemented in your search interface, the Facet Generator chooses facets to display based on the values of facet and multi-value facet fields in your content.

By default, the Facet Generator can use any of these fields as a facet source. To prevent it from using a specific field, you need to turn off the Facet Generator option for that field.

The Facet Generator also uses the field name as the facet title by default. However, you can specify a custom label for the facet.

Excluding fields and changing labels can be done one field at a time on the Fields page of the Coveo Administration Console. See Add or edit a field for details on this process.

Alternatively, you can use the Fields API, which allows batch changes.

Exclude fields or change labels via the Fields API

The Update fields call allows you to update multiple fields at once. You can use it to:

  • Prevent/allow the Facet Generator from using a specific field

  • Change the label of a facet

In the request body, provide field information in the following format:

[
    {
        "name": "field1",                        <<< Field name. The Facet Generator only supports facet and multi-value facet fields.
        "label": "Color",                        <<< Custom facet label to display.
        "type": "STRING",                        <<< Required. The Facet Generator only supports STRING fields.
        "facet": true,                           <<< Required.
        "automaticFacetsCandidate": false        <<< Forbids the Facet Generator to use this field for facet generation.
    },
    {
        "name": "field2",
        "label": "Product Size",
        "type": "STRING",
        "facet": true,
        "automaticFacetsCandidate": true
    }
]

To validate your changes, use the List fields call with the following request body. Coveo will return a list of all fields that the Facet Generator can use.

"page": 0,
"perPage": 100,
"filters": {
"automaticFacetsCandidate": "TRUE_ONLY"
}

The following is an example of a bash script that uses the calls above.

#!/bin/bash
#=== TO EDIT [START] ========================================
ENV="platform"                #platform-au, platform-eu
ORGANIZATION="orgfullname"
TOKEN=xtoken
INPUT_FILE=fields_to_update.json
#=== TO EDIT [END] ==========================================

function execute_fields_batch_update {
    curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header "Authorization: Bearer $TOKEN" \
    -d @$INPUT_FILE \
    "https://$ENV.cloud.coveo.com/rest/organizations/$ORGANIZATION/indexes/fields/batch/update"
}

function execute_fields_search {
    curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header "Authorization: Bearer $TOKEN" \
    "https://$ENV.cloud.coveo.com/rest/organizations/$ORGANIZATION/indexes/fields/search" \
    -d '{
        "page": 0,
        "perPage": 1000,
        "filters": {
            "automaticFacetsCandidate": "TRUE_ONLY"
        }
    }'
}

echo Starting...
execute_fields_batch_update
echo Completed.

echo Retrieving the list of automaticFacetsCandidate...
execute_fields_search > automaticFacetsCandidate_found.json
echo
cat automaticFacetsCandidate.log | jq -r '"*" + ((.totalEntries|tostring) + "* fields found. See automaticFacetsCandidate_found.json")'

Facet Generator limitations

The Facet Generator has the following limitations:

  • It only supports string-type fields.

  • It doesn’t support label variants, which means that it works best in a single-language context.