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

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

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

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

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).
• Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.

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.

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.

This parameter is exposed for backward compatibility reasons. Use the enableQuerySyntax parameter instead.

The disjunction query expression, typically populated by Coveo ML Automatic Relevance Tuning (ART) 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).

Whether to allow the end user to assign an arbitrary 0-5 star rating to each individual query result item.

You need to contact Coveo support if you want to enable this feature in your index. Otherwise, setting enableCollaborativeRating to true has no effect.

Tip: Coveo Machine Learning automatic relevance tuning models provides a much more reliable way to boost query result items based on end user interaction.

Default: false

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.
• Duplicate filtering and result folding are mutually exclusive.

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

An excerpt is a segmented text generated at query time by the index from the body of an item. When a query is performed, the excerpt yields relevant item body sections in which the queried terms are highlighted.

An excerpt includes the most relevant sentences in which the queried keywords appear, 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 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.

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.

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.

Notes::

• Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.

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.

Notes::

• Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.

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.

Note: This can't be greater than the maximumResults value configured for your index. By default, maximumResults is set to 5,000 items.

Default: 0

The format of a successful response.

• Use json to get the response in the JSON format.
• 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

Generate facets based on the most relevant fields in the index.

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

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

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

This parameter is exposed for backward compatibility reasons. Use the locale parameter instead.

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

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

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

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

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.

Such cache hits improve responsiveness but still count as queries in your queries per month (QPM) count.

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 ER 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 ER 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, ER, 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 ER 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 ART, QS, and DNE 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 is 2,000 items.

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).
• Result folding and duplicate filtering (using the enableDuplicateFiltering parameter) are mutually exclusive.

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 final pipeline value used in the query execution. This value is determined from the query response. If no pipeline was specified, it uses the "default" value.

See also Managing Query Pipelines.

This defines generic parameters to be used by rules. It defines the "scopes", or in other words, the rules in which the parameters should be used. The generic parameters are defined within a particular scope and are only be accessible inside of it. This is a read-only parameter, so its value will not be overridden.

{ "scope": { "parameterName" : "parameterValue" } }

While using Gen AI, if additional document fields are required for the resulting citations, these fields can be specified through the 'citationsFieldToInclude' property of the 'mlGenerativeQuestionAnswering' scope.

Note: Getting dictionary fields for citations is not supported.

Examples:

• {"mlGenerativeQuestionAnswering": { "responseFormat": { "answerStyle": "bullet" } } }
• {"mlGenerativeQuestionAnswering": { "citationsFieldToInclude": ["field1", "field2"] } }

Max Size: 1KB

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.

This parameter controls the behavior of the Coveo query correction feature.

Once enabled, this feature will:

• Attempt to correct your query if it doesn't return enough results.
• If corrections are found, the API will automatically correct your query.

Query corrections are derived from the index's Did You Mean feature and ML query corrections.

Correction information will be returned in the queryCorrection property of the response.

If the query was automatically corrected, it will return:

• The original query
• The corrected query

Otherwise, it will return:

• A list of corrections generated by our system.

This feature is off by default for backward compatiblity reasons.

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 (see CoveoRecommendation).

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

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.

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

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 pipeline, or a searchHub that routes queries to a specific pipeline via a query pipeline condition.
• 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.

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

This parameter is exposed for backward compatibility reasons. Use the sortCriteria parameter along with the @[field] ascending/@[field] descending syntax instead.

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 Coveo Platform uses a linguistic algorithm that relies on term frequency and proximity to generate an item summary made of sentences identified to be the most important ones in the item.

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

Default: 0

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.

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.

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.

The name of the field against which to execute the facet search request.

The shared base path for all values in the facet to search against.

If a basePath is specified, the search request will be executed against hierarchical values that begin with that base path only (i.e., other hierarchical values will be filtered out).

A dictionary that maps index field values to facet value display names.

Note:

When specifying display captions for hierarchical facet values, you can use full values (e.g., all;electronics;laptops), and/or for "leaf" values (e.g., laptops) as keys. If both are provided, the full value takes priority.

Examples:

• Specific (i.e., scalar) facet values: {\"#FF8000\": \"Orange\", \"#8000FF\": \"Purple\"}
• Hierarchical facet values:** `{"all;electronics;laptops": "Laptops", "smartphones": "Smart Phones"} "

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

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

Note: The target folding field must be a facet field with the Use cache for nested queries options enabled (see Add or Edit a Field).

Default: false

A list of paths to filter out from the hierarchical facet search results.

The maximum number of values to fetch.

**Default: 10

The string to match.

Note: Typically, this should be set to the text entered by the end-user in the facet search box, to which one or more wildcard characters (*) may be added.