Interface IFacetRequest

A Search API facet request.



Optional basePath

basePath: string[]

The base path shared by all values for a given hierarchical facet.

Default (Search API): []

Optional currentValues

currentValues: IFacetRequestValue[]

The values displayed by the facet in the search interface at the moment of the request.

See IFacetRequestValue.

Default (Search API): []

Optional delimitingCharacter

delimitingCharacter: string

The character to use to split field values into a hierarchical sequence.

Example: For a multi-value field containing the following values: c; c>folder2; c>folder2>folder3; The delimiting character is >.

Default (Search API): ;


facetId: string

The unique identifier of the facet in the search interface.

Note: Must match ^[A-Za-z0-9-_]{1,60}$.

Example: author-1


field: string

Required (Search API). The name of the field on which to base the facet request.

Note: Must reference an index field whose Facet option is enabled.

Example: author

Optional filterByBasePath

filterByBasePath: boolean

Whether to use the [basePath]{@link FacetRequest.basePath} as a filter for the results.

Note: This parameter is ignored unless the facet [type]{@link FacetRequest.type} is hierarchical.

Default (Search API): true

Optional filterFacetCount

filterFacetCount: boolean

Whether to exclude folded result parents when estimating result counts for facet values.

Default (Search API): true

Optional freezeCurrentValues

freezeCurrentValues: boolean

Whether to include the facet request's currentValues in the corresponding facet response's values array.

Note: Setting this to true is useful to ensure that the facet does not move around while the end-user is interacting with it in the search interface.

Default (Search API): false

Optional generateAutomaticRanges

generateAutomaticRanges: boolean

Whether to automatically generate range values for the facet.


  • Setting this to true is only effective when type is set to [dateRange]{@link FaceType.dateRange} or numericalRange, and the referenced field is of a corresponding type (i.e., date or numeric).
  • Automatic range generation will fail if the referenced field is dynamically generated by a query function.
  • Enabling the Use cache for numeric queries option on the referenced field will speed up automatic range generation (see Add or Edit Fields).

Default (Search API): false

Optional injectionDepth

injectionDepth: number

The maximum number of items to scan for facet values.

Note: A high injectionDepth may negatively impact the facet request performance.

Default (Search API): 1000

Optional isFieldExpanded

isFieldExpanded: boolean

Whether the facet is expanded in the search interface at the moment of the request.

Default (Search API): false

Optional numberOfValues

numberOfValues: number

The maximum number of facet values to fetch.

Note: If freezeCurrentValues is true, numberOfValues must be equal to the currentValues array length.

Default (Search API): 8

Optional preventAutoSelect

preventAutoSelect: boolean

Whether to prevent Coveo ML from automatically selecting values from that facet.

Default: false

Optional sortCriteria

sortCriteria: FacetSortCriteria

The sort criterion to apply to the returned facet values.

Default behavior (Search API):

Optional type

type: FacetType

The kind of values to request for the facet.

Default (Search API): [Specific]{@link FacetType.Specific}


  • IFacetRequest