Query parameters

The query and page view actions previously made by the current user.

Coveo Machine Learning content recommendations models use this information to provide contextually relevant output.

Note: Page view actions are typically populated by the coveo.analytics.js script.

Contextual information about the user performing the request and the request itself.

Coveo Machine Learning models may use this information to provide contextually relevant output.

Available parameters:

• userId (string): The ID of the logged user. If not present, the id is obtained from the authentication token.
• clientId (string): A GUID which represents the current client. The clientId and deviceId replace the deprecated visitorId. For compatibility, the cookie and local storage values are still named coveo_visitorId.
• deviceId (string): The name of the device that the end user is using. It has to be explicitly passed from native mobile apps. The clientId and deviceId replace the deprecated visitorId.
• documentLocation (string): The URL of the current page or component. If not present, the referrer is obtained from the Referer header. This information can be obtained from coveo.analytics.js.
• documentReferrer (string): Typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value). This information can be obtained from coveo.analytics.js.
• pageId (string): A GUID representing the page ID. This information can be obtained from coveo.analytics.js.
• userIp (string): The user IP. If not present, the IP is obtained from the X-Forwarded-For and Forwarded headers. This information is required when endpoints are behind a proxy.
• clientRequestId (string): A GUID generated by the client representing the current request. This information is used to identify operations across different apis related to the same request.
• clientTimestamp (string): Client ISO 8601 timestamp with milliseconds.
• userAgent (string): The user agent of the request. If not present, the user agent is obtained from the User-Agent header. This information is required when endpoints are behind a proxy.

Examples:

• {"userId": "user@email.com", "clientId": "6d148f06-5f15-4639-81b4-792a9b94eb5f", "deviceId": "Chrome"}
• {"clientTimestamp": "2020-09-09T19:00:45.603-04:00", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"}

The advanced query expression, typically generated by code (e.g., when toggling facet values).

Note: When logging a Search usage analytics event for a query, the advancedQuery field of that event should be set to the aq value of the corresponding query (for reporting purposes).

Example: @year==2017

Data to easily query a hierarchical field using a path of hierarchical values.

The @-prefixed name of the field to use to be able to identify an item as a child of another item in a folded query result (see Result Folding).

Use a field whose value points to the parentField value of the intended parent. Whenever an item is a child of another item, its childField value must be identical to the parentField value of that other item.

See also the filterField, parentField, and filterFieldRange parameters.

Notes:

• In the index, the values of the childField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
• The values of the childField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).

Example: @foldingparent

The parameters for Coveo for Commerce.

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $context object.

Note: When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Example {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

The constant query expression, typically populated with expressions that must apply to all queries sent from a specific search interface (e.g., from a specific tab). Once evaluated, the result sets of those expressions are kept in a special cache.

Tip: Avoid including dynamic content in the constant query expression. Otherwise you risk filling up the cache with useless data, which can have a negative impact on performance.

Notes:

• Other parts of the query expression can also benefit from the index cache (see the maximumAge parameter). However, using the constant query expression allows you to explicitly cache specific result sets.
• Temporal keywords (now, today, yesterday) in the constant query expression are only re-evaluated once per 3-4 minutes; therefore, you should avoid basing cq expressions on temporal keywords if you require split second accuracy.

Example: @filetype==forumpost

Whether to force a successful response to include debug information.

Notes:

• Debug information can only appear in responses in the JSON format (see the format parameter).
• Avoid setting this parameter to true in production, as it has a negative impact on query performance.

Default: false

A key-value store where each pair corresponds to the name of a dictionary field to query, along with the key to target within that field.

Example: Suppose that in your index, the @price dictionary field contains different values for its storeA and storeB keys. Including "dictionaryFieldContext": { "price": "storeA" } in the query means that any part of the query expression that targets the @price field will in fact only query the storeA values of that field.

The disjunction query expression, typically populated by Coveo ML automatic relevance tuning models to ensure that relevant items are included in the query results. The disjunction query expression is merged with the other parts of the query expression using an OR operator. The resulting query expression is (((q aq) OR (dq)) cq).

Example: @permanentid=aadd702687c62910d6da8347304ec2cedfd0b06d5b4d2794a555ce5688bd

Whether to enable the Did You Mean feature of the index, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

• The Did You Mean feature only processes the basic query expression (see the q parameter).
• When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.
• The Did You Mean feature will return no corrections when the query is processed by an automatic relevance tuning (ART) model whose Intelligent Term Detection (ITD) feature is enabled.

Default: false

Whether to filter out duplicates, so that items resembling one another only appear once in the query results.

Notes:

• Two items must be at least 85% similar to one another to be considered duplicates.
• When a pair of duplicates is found, only the higher-ranked item of the two is kept in the result set.
• Enabling this feature can make the total result count less precise, since only results up to those being retrieved (see the firstResult and numberOfResults parameters) are submitted to duplicate filtering.

Default: false

Important: This feature is still in an experimental state.

Whether to enable the Coveo ML query suggestions Did You Mean feature, which populates the queryCorrections property of a successful response with keyword correction suggestions.

Notes:

• The Coveo ML query suggestions Did You Mean feature only processes the basic query expression (see the q parameter).
• When both enableDidYouMean and enableMLDidYouMean parameter are set to true, the output of both features will appear in the queryCorrections array.

Default: false

Whether to interpret advanced Coveo Cloud query syntax as such in the basic query expression (see the q parameter). See also the lowercaseOperators parameter.

Default: true

The maximum length of result excerpts (in number of characters).

The index generates result excerpts based on the keywords which are present in the query. Those excerpts include the most relevant sentences, in the order in which they appear in the item, up to the specified number of characters.

Note: The maximum length you set using this parameter also applies to retrieved first sentences, if those are included in the results (see the retrieveFirstSentences parameter).

Default: 200

The global configuration options that apply to all facet requests performed along with the query (see the facets query parameter).

The facet operations to perform on the query results.

The names of the fields to exclude from the query results. All other fields will be included with each item in the query result.

Note: If you specify both an array of fields to include (see the fieldsToInclude parameter) and an array of fields to exclude, the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToInclude parameter), each query result item will include all of its available fields.

Example: ["documenttype","size","source"]

The names of the fields to include with each item in the query results. If specified, no other fields will be included.

Note: If you specify both an array of fields to include and an array of fields to exclude (see the fieldsToExclude parameter), the fieldsToExclude parameter has no effect at all.

If you do not explicitly specify an array of values for this parameter (or for the fieldsToExclude parameter), each query result item will include all of its available fields.

Example: ["clickableuri","author","date","filetype","language","coversationid","messageid","childid","adjustednumberoflikes"]

The @-prefixed name of the field to use to group items into distinct folded query results (see Result Folding).

Use a field whose value is identical for all items to group under the same folded query result.

See also the parentField, childField, and filterFieldRange parameters.

Example: @foldingcollection

The maximum number of items to include in the childResults array of a folded query result (see Result Folding).

See also the filterField, parentField, and childField.

Default: 5

The 0-based position of the first result to return in the non-paginated result set.

Along with the numberOfResults parameter, this allows you to retrieve a specific page of result items.

Default: 0

The format of a successful response.

• Use json to get the response in the JSON format.
• Use opensearch-atom or opensearch-rss to get the results in an OpenSearch format (XML).
• Use xlsx to generate an Excel file containing the results (binary).

Note: Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default: json

The Group By operations to perform on the query results, typically to extract facets.

The identifier of the index mirror to forward the request to. See also the indexToken parameter.

If you do not specify an index (or indexToken) value, any index mirror could be used.

Note: Passing an index (or indexToken) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

Example: myorg-nvoqun-Indexer1-pbi2nbuw

The Base64 encoded identifier of the index mirror to forward the request to. See also the index parameter.

If you do not specify an indexToken (or index) value, any index mirror could be used.

Note: Passing an indexToken (or index) value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

Example: ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==

The type of index against which to execute the query. Must correspond to an index that has been configured for the target Coveo Cloud organization.

Default: coveo

Whether the current user is anonymous.

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the anonymous field of that event should be set to the isGuestUser value of the query.

Default: false

The locale of the current user. Must comply with IETF’s BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information can be referred to in query expressions and QPL statements by using the $locale object.

Note: When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

Example: en-US

The identifier for a logical group of indexes that have been configured to include documents form the same sources.

If you do not specify a logicalIndex value, the default grouping will be used, typically including all indexes.

Example: webcontentonly

Whether to treat the AND, NEAR, NOT, and OR keywords in the basic query expression (see the q parameter) as Coveo Cloud query syntax operators even if those keywords are in lowercase.

Note: Setting this parameter to true has no effect unless you also set the enableQuerySyntax parameter to true.

Example: If you set this parameter, and the enableQuerySyntax parameter to true, the index interprets the near keyword in the basic query expression service center near me as the NEAR Coveo Cloud query syntax operator.

Default: false

The large query expression, typically populated with a case description, long textual query, or any other form of text that can help refine a query. The Coveo ML Intelligent Term Detection (ITD) feature can extract relevant keywords from the large query expression and inject those keywords in the basic query expression (see the q parameter).

Example: I am looking for an enterprise-class native cloud SaaS/PaaS solution that ...

The minimum number of keywords that need to be present in the large query expression (see the lq parameter) to convert it to a partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchThreshold parameter.

Default: 5

The maximum number of keywords from the large query expression (see the lq parameter) that will be included in the partial match expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

Note: This parameter applies as a fallback setting when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

Setting this parameter to a high value can negatively impact the performance of queries, while setting it too low can produce less relevant results.

See also the lqPartialMatchThreshold parameter.

Default value: 100

An absolute or relative value indicating the minimum number of partial match expression keywords an item must contain to match the large query expression in case the Coveo ML Intelligent Term Detection (ITD) feature cannot extract relevant keywords from the large query expression.

If specified, the lqPartialMatchThreshold value must either be:

• a 32-bits unsigned integer (e.g., 3),
• a percentage value between 0% and 100% (e.g., 75%),
• the empty string (""), or
• the all string.

The "" and all values are both equivalent to 100%.

Note: This parameter applies when no Coveo ML automatic relevance tuning model is available in the query pipeline to process a query that contains a non-null large query expression (lq).

See also the lqPartialMatchKeywords parameter.

Examples:

• 3
• 75%
• all

Default: 50%

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Note: This parameter is automatically overridden when staticQuery is set to true.

Default: -1 (which corresponds to the internal default value (15 minutes)

The maximum number of milliseconds to allow the request to last before timing out. Maximum: 16000

Minimum/Default: 0, meaning that Coveo determines the most appropriate timeout to use.

The maximum number of Coveo ML Did You Mean candidates to request from the query suggestions model.

Default: 3

The minimum score a query suggestion may have to be allowed as a candidate for the Coveo ML query suggestions Did You Mean feature. For best results, value should typically be in range [0.8, 2].

Default: 1.0

Whether to use facet counts for the Coveo ML Did You Mean feature. Can improve results, but requires more processing.

Default: false

A map of options to pass to the Coveo ML models associated with the request’s target query pipeline.

Available parameters:

• considerUserContext (boolean): Whether the models should attempt to leverage the context object of the request to personalize their output. Applies to CR models only. Default is true.
• maxActionsHistoryItemsToConsider (unsigned integer): The maximum number of items in the actionsHistory array of the request that should be taken into account by the models. Applies to CR models only. By default, all actionsHistory items are considered.
• num (unsigned integer): The maximum number of recommendations/suggestions to request from the models. Must be in range [1, 50], if specified. Applies to ART, CR, and QS models. Default depends on model configuration.
• padding (string enum): The kind of padding the models should complete their output with, if their maximum number of recommendations/suggestions (i.e., num) has not been reached. Applies to CR models only. Allowed values are popular (i.e., pad recommendations with all time most popular items) and trending (i.e., pad recommendations with items that have recently been increasingly popular). By default, no padding applies.
• wordSelection (string): The ITD keyword selection options the models should use. Applies only to ART models with ITD enabled. If specified, must be a string in the format option:value. The only available option is wordsKept (i.e., the maximum number of lq keywords to inject in q); its default value is 5.
• minNumberOfWords (unsigned integer): The minimum number of words a query suggestion may contain to be returned by the model. Applies to QS models only. Must be in range [1, 10] Default is 1, which implies that the model will return all candidates.
• itemId (string): The unique identifier (e.g., SKU) of a product to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering a single item as an input.
• itemIds (array of strings): The unique identifiers (e.g., SKUs) of the products to get recommendations for. Only applies when querying a Product Recommendations model with an association strategy considering multiple items as an input.
• categoryFilter (string): The name of a category of products to get recommendations for.
• brandFilter (string): The name of a brand of products to get recommendations for.
• filters (map of strings): The dimensions along with the values to be used at query time by the model as filters for potential suggestions. Only applies to Automatic relevance Tuning, Query Suggestions, or Dynamic Navigation Experience models that don’t use the default filterFields advanced parameter values. Example: "filters": { "originContext": "<MY-VALUE>", "originLevel2": "<MY-VALUE>" }.

Examples:

• {"num": 3, "padding": "trending", "maxActionsHistoryItemsToConsider": 10, "considerUserContext": false}
• {"wordSelection": "wordsKept:4"}

The number of results to return.

Along with the firstResult parameter, this allows you to retrieve a specific page of result items.

This parameter also defines the maximum number of results which can be returned by the Coveo ML Recommendations feature.

Note: The maximum numberOfResults value depends on the index settings of your Coveo Cloud V2 organization. By default, a Coveo Cloud V2 index can return a maximum of 5000 items per query.

Default: 10

The @-prefixed name of the field to use to be able to identify an item as a parent in a folded query result (see Result Folding).

Use a field whose value can uniquely identify each item. All items whose childField value is identical to the parentField value of another item are considered children of that other item.

See also the filterField, childField, and filterFieldRange parameters.

Notes:

• In the index, the values of the parentField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will make folding fail.
• The values of the parentField must contain 60 characters or less (60 being the default maximum of characters for a word in the index).

Example: @foldingchild

Whether to convert a basic expression containing at least partialMatchKeywords to a partial match expression, so that any item containing at least partialMatchThreshold of those keywords will match the expression.

If you do not set this parameter to true, an item must contain all of the basic expression keywords to match the expression.

Notes:

• This feature only applies to the basic expression (q) of a query, and to the basic queryOverride of its Group By operations.
• When the enableQuerySyntax parameter is set to true, this feature has no effect on a basic expression containing advanced Coveo Cloud query syntax (field expressions, operators, etc.).

Default: false

The minimum number of keywords that need to be present in a basic expression to convert it to a partial match expression.

Notes:

• This parameter has no meaning unless the partialMatch parameter is set to true.
• Repeated keywords in a basic expression count as a single keyword.
• Thesaurus expansions in a basic expression count towards the partialMatchKeywords count.
• Stemming expansions do not count towards the partialMatchKeywords count.

See also the partialMatchThreshold parameter.

Default: 5

An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords an item must contain to match the expression.

If specified, the partialMatchThreshold value must either be:

• a 32-bits unsigned integer (e.g., 3),
• a percentage value between 0% and 100% (e.g., 75%),
• the empty string, or
• the all string.

The "" and the all value are both equivalent to 100%.

Notes:

• This parameter has no meaning unless the partialMatch parameter is set to true.
• A keyword and its stemming expansions count as a single keyword when evaluating whether an item meets the partialMatchThreshold.

See also the partialMatchKeywords parameter.

Examples:

• 3
• 75%
• all

Default: 50%

The name of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

• This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
• For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the pipeline value of the query (or to the "default" string, if no pipeline value was specified in the query).

See also Managing Query Pipelines.

Example: CustomerQueryPipeline

The basic query expression, typically the keywords entered by the end user in a query box.

Note: When logging a Search usage analytics event for a query, the queryText field of that event should be set to the q value of the corresponding query.

Example: Coveo "Cloud V2" platform

The array of query functions to execute on each query result item.

The result of a query function is stored in a temporary, dynamic field created at query time.

Whether to enable question mark characters (?) in the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing question mark characters (?) to the possible matching keywords.

Note: Setting this parameter to true has no effect unless you also set the wildcards parameter to true.

See Using Wildcards in Queries.

Default: false

The array of ranking functions to execute on each query result item.

The result of a ranking function is added to the result score, which can affect sorting (see the Relevancy and qre values of the sortCriteria parameter).

The identifier of the recommendation interface from which the request originates.

Coveo Machine Learning content recommendations models may use this information to provide contextually relevant output.

Example: RecommendedProducts

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

Example: http://www.example.com/

Whether to include the first sentences of textual items in the query results.

First sentences are typically useful when rendering result items such as emails, since the first few sentences of these kinds of items are often more relevant than a contextually generated excerpt (see the excerptLength parameter).

Note: The maximum length of the retrieved sentences (in number of characters) is determined by the value of the excerptLength parameter.

Default: false

Whether the q value contains the URI hash of a specific item that should be returned.

Default: false

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

• This parameter will be overridden if the search request is authenticated by a search token that enforces a specific searchHub.
• When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

Example: CustomerPortal

The criteria to use for sorting the query results.

Allowed values:

• relevancy: use standard index ranking factors (adjacency, TDIDF, etc.) and custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
• date ascending/date descending: use the @date field to sort the query results. This field typically contains the last modification date of each item.
• qre: use only custom ranking expressions (QREs and QRFs) to compute a ranking score for each query result item, and sort the query results by descending score value.
• nosort: do not sort the query results; the index will return result items in an essentially random order.
• @[field] ascending/@[field] descending: sort using the value of a specific sortable field (replace [field] by the target field name).

You can specify a list of comma-separated sort criteria. However, this only works when combining:

• two or more field criteria (e.g., @views descending,@likes descending).
• a single date criteria with one or more field criteria (e.g., date ascending,@views descending).

Examples:

• date ascending
• @author ascending
• date descending,@views descending,@likes descending

Default: relevancy

Whether to execute this query in a way that does not count against the allowed number of queries per month of a Coveo Cloud organization (QPM), but may produce cached/outdated query results (see Rendering Static Content Using Persistent Queries).

Note: Setting this parameter to true overwrites the maximumAge parameter value for this query.

Default: false

The length of the automatically generated item summary.

The index generates a result item summary independently from the query, as opposed to a result item excerpt, which is generated based on query keywords.

Default: 0

The name of the query syntax to apply when interpreting the basic query expression (see the q parameter).

The only value you can specify for this parameter is SOSL (to use the Salesforce Object Search Language syntax). You do not need to set enableQuerySyntax to true to apply SOSL syntax when interpreting the basic query expression.

If you do not specify a value for this parameter and the enableQuerySyntax parameter is set to true, the default Coveo Cloud query syntax is applied (see Coveo Cloud Query Syntax Reference).

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note: When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

Example: ForumTab

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note: While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

Example: America/New_York

The parameters allowing user actions to be retrieved in query results.

A GUID which represents the current user, who can either be authenticated or anonymous.

visitorId is deprecated and has been replaced by clientId in newer versions of the Coveo UI libraries. For compatibility, the new first-party cookie and local storage values are still named coveo_visitorId.

For older versions of the JavaScript Search Framework, the visitor ID is generated by the Coveo Usage Analytics service and stored in a non-expiring third-party cookie. Note: Third-party cookies have also been deprecated. This is unrelated to the deprecation of visitorId.

Example: 5cb98953-9c13-42ff-8176-e6fcba6a50bf

Whether to enable the wildcards feature of the index in order to expand basic expression keywords (see the q parameter) containing wildcard characters (*) to the possible matching keywords. See also the questionMark parameter.

See Using Wildcards in Queries.

Default: false

The action history event name.

Example: PageView

The action history value, which is either a query expression or a page URI, depending on the action history event name.

Example: http://www.example.com/

The time when the action history event was sent from the client.

Example: 2017-08-15T17:34:08.398Z

A GUID which represents the current client.

If your implementation uses the Atomic or Headless libraries, or newer versions of the JavaScript Search Framework, then the client ID is generated automatically in client-side code. This GUID is held in a browser’s local storage as well as a top level domain first-party cookie (coveo_visitorId) that expires after 1 year. Note: The cookie takes precedence over the value in the browser’s local storage.

If you have a custom Coveo implementation, you will have to generate a UUID v4-formatted GUID. You will need to send this ID as analytics.clientId in every event that is sent to Coveo UA and the Search API.

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: The clientId and deviceId replace the deprecated visitorId. For compatibility, the cookie and local storage values are still named coveo_visitorId.

Example: 6d148f06-5f15-4639-81b4-792a9b94eb5f

A GUID generated by the client representing the current request.

This information is used to identify operations across different apis related to the same request.

Example: 6c59a3aa-cb66-492e-9c08-9f1937467b60

Client ISO 8601 timestamp with milliseconds.

Example: 2020-09-09T19:00:45.603-04:00

The name of the device that the end user is using. It has to be explicitly passed from native mobile apps.

Note: The clientId and deviceId replace the deprecated visitorId.

Example: Chrome

The URL of the current page or component.

If not present, the referrer is obtained from the Referer header.

Note: This information can be obtained from coveo.analytics.js.

Example: http://www.example.com/

Typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note: This information can be obtained from coveo.analytics.js.

Example: http://www.example.com/

A GUID representing the page ID.

Note: This information can be obtained from coveo.analytics.js.

Example: c4e3aa42-5afa-4b01-8bfd-79b7b49668f7

The user agent of the request. If not present, the user agent is obtained from the User-Agent header.

Note: This information is required when endpoints are behind a proxy.

Example: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36

The ID of the logged user. If not present, the id is obtained from the authentication token.

Example: user@email.com

The user IP. If not present, the IP is obtained from the X-Forwarded-For and Forwarded headers.

Note: This information is required when endpoints are behind a proxy.

Example: 127.0. 0.1

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: |

The name of the field in which to look for hierarchical values.

Note: You must ensure that the Multi-value facet option is enabled for this field in your index (see Add or Edit Fields).

Example: @categories

Whether to exclude folded result parents when estimating the result count for each facet value.

Default: true

The maximum number of query result items to scan.

Note: Specifying a high injectionDepth value can negatively impact query performance.

Default: 1000

The maximum number of values to return.

Default: 10

The retrieved sequence of hierarchical field values.

The unique identifier of the catalog to query.

A mandatory query expression to apply if the commerce request affects the query.

The way the commerce request should affect query results.

Whether to take the scores generated by the index into account when reordering facets.

Note: Setting this to false implies that only the scores generated by a Coveo ML DNE model will be taken into account when automatically reordering facets. To disable automatic facet reordering entirely, set freezeFacetOrder to true instead.

Default: true

Whether facets should be returned in the same order they were requested.

Note: Setting this to true entirely prevents automatic score-based facet reordering. To allow automatic facet reordering, but only take into account the scores generated by a Coveo ML DNE model, set enableIndexFacetOrdering to false instead.

Default: false

The base path shared by all values for the facet.

Note: This parameter has no effect unless the facet type is hierarchical.

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

Default: []

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 >.

For a hierarchical field containing the following values: c;folder2;folder3;

The delimiting character is ;.

Default: ;

The name of the field on which to base the facet request.

Note: Must reference a field whose Facet option is enabled (see Add or Edit Fields).

Example: author

Whether to use basePath as a filter for the results.

Note: This parameter has no effect unless the facet type is hierarchical.

Default: true

Whether to exclude folded result parents when estimating the result count for each facet value.

Default: true

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

Notes:

• 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.
• This parameter has no effect when the facet type is hierarchical.

Default: false

Whether the index should automatically create range values.

Tip: If you set this parameter to true, you should ensure that the Use cache for numeric queries option is enabled for the Facet field in your index in order to speed up automatic range evaluation (see Add or Edit Fields).

Notes:

• Setting generateAutomaticRanges to true only makes sense when the Facet field references a numeric or date field in the index.
• The index cannot automatically generate range values of a field generated by a query function. In such cases, you must rather use the rangeValues Facet parameter.
• Automatic range generation will fail if the referenced field is dynamically generated by a query function.

Default: false

The maximum number of items to scan for facet values.

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

Default: 1000

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

Default: false

The maximum number of facet values to fetch.

Notes:

• If freezeCurrentValues is true or if requesting range facet values, numberOfValues is automatically set to the currentValues array length.
• When requesting hierarchical facet values, numberOfValues is only taken account when the currentValues array is empty (i.e., when retrieving the first level of values).

Default: 8

Whether to prevent Coveo ML from automatically selecting values.

Default: false

The sort criterion to apply to the returned facet values.

Allowed values:

• score: Sort values in descending score order. Facet value scores are based on the number of occurrences and their position in the ranked query result set.
• alphanumeric: Sort values in ascending alphanumeric order.
• ascending: Sort in ascending order of range facet values. Only applicable to range facets.
• descending: Sort in descending order of range facet values. Only applicable to range facets.
• occurrences: Sort by number of occurrences, with field values having the highest number of occurrences appearing first. Only applicable to hierarchical facets.

Notes:

• The Coveo ML DNE feature only works with the score sort criterion.

By default: Specific facets:

• When isFieldExpanded is false in the facet request, and moreValuesAvailable is true in the corresponding facet response, use score
• Otherwise, use alphanumeric.

Range facets: uses ascending Hierarchical facets: uses occurrences

Determines which algorithm is used to generate the ranges if generateAutomaticRanges is enabled.

Allowed values:

• equiprobable
• even

Default: equiprobable

Equiprobable

This algorithm creates ranges which represent the distribution of the results. For example, if you have a single facet value that matches most of the results, the equiprobable algorithm will resize the ranges to balance the weights.

Even

This algorithm creates ranges of the same length. For example, it could generate the following price ranges:

The kind of values to request for the facet.

Allowed values:

• specific: Request facet values representing specific values (e.g., Alice Smith, Bob Jones, etc.).
• dateRange: Request facet values representing ranges of dates (e.g., 2019-07-01..2019-07-31, 2019-08-01..2019-08-01, etc.).
• numericalRange: Request facet values representing ranges of numbers (e.g., 0..10, 11..20, etc.).
• hierarchical: Request facet values representing hierarchically structured categories (e.g., Electronics > Entertainment > Gaming Consoles;, Electronics > Computers > Laptops, etc.).

Default: specific

The children of this hierarchical facet value.

Each child is a full-fledged hierarchical facet value that may in turn have its own children and so forth, up to a maximum depth of 50 levels.

The value to end the range at. Must be greater (or later) than the start value.

Note: Timezone of date ranges are determined by the timezone parameter of the search request.

Examples:

• 100
• 2019/12/31@23:59:59

Whether to include the end value in the range.

Default: false

Whether to prevent Coveo ML from automatically selecting the facet value.

Default: false

Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

The maximum number of children to retrieve for this hierarchical facet value. Ignored if retrieveChildren is false.

The value to start the range at.

Note: Timezone of date ranges are determined by the timezone parameter of the search request.

Examples:

• 0
• 2019/01/01@00:00:00

The current facet value state in the search interface.

Default: idle

The facet value name.

Note: In the case of a hierarchical facet value, this represents a single path segment.

Example: Alice Smith

The children of this hierarchical facet value.

Each child is a full-fledged hierarchical facet value that may in turn have its own children and so forth, up to a maximum depth of 50 levels.

Whether to prevent Coveo ML from automatically selecting the facet value.

Default: false

Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

The maximum number of children to retrieve for this hierarchical facet value. Ignored if retrieveChildren is false.

The current facet value state in the search interface.

Default: idle

The facet value name.

Note: In the case of a hierarchical facet value, this represents a single path segment.

Example: Alice Smith

The user ID or visitor ID to retrieve user actions for.

Examples:

• asmith@example.com
• c7ab60e2-e6b8-41e8-be6a-ad5c8edc662e