Query Parameters

This topic provides reference documentation for the top-level query parameters.

Full reference documentation for accessible Search API endpoints is also available (see Search API - Reference Documentation).

actionsHistory (array of ActionHistory)

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.

aq (string)

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

Sample value: @year==2017

categoryFacets (array of RestCategoryFacet)

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

childField (string)

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

Sample value: @foldingparent

context (object)

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.

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

Additional properties:

[PROPERTY_NAME] (object)

A custom context key-value pair. Value must be a string or an array of strings.

cq (string)

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.

Sample value: @filetype==forumpost

debug (boolean)

Whether to force a successful response to include debug information.

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

Default value: false

dq (string)

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

Sample value: @permanentid=aadd702687c62910d6da8347304ec2cedfd0b06d5b4d2794a555ce5688bd

enableDidYouMean (boolean)

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

enableDuplicateFiltering (boolean)

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

Note: 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 value: false

enableMLDidYouMean (boolean)

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

enableQuerySyntax (boolean)

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

excerptLength (integer [int32])

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.

Notes:

  • 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).
  • On an Elasticsearch index, actual excerpts may be slightly longer than the requested excerpt length.

Default value: 200

fieldsToExclude (array of string)

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.

Sample value: ["documenttype","size","source"]

fieldsToInclude (array of string)

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.

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

filterField (string)

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.

Note: In an Elasticsearch index, the corresponding field must be configured as a Facet and/or Sortable field (see Add or Edit Fields). This limitation does not apply to a Coveo index.

Sample value: @foldingcollection

filterFieldRange (integer [int32])

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

firstResult (integer [int32])

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

format (string)

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

groupBy (array of RestGroupBy)

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

index (string)

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

Sample value: myorg-nvoqun-Indexer1-pbi2nbuw

indexToken (string)

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

Sample value: ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==

indexType (string)

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 value: coveo.

isGuestUser (boolean)

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 value: false.

locale (string)

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

Sample value: en-US

logicalIndex (string)

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.

Sample value: webcontentonly

lowercaseOperators (boolean)

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

lq (string)

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

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

lqPartialMatchKeywords (integer [int32])

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

lqPartialMatchThreshold (string)

An absolute or relative value indicating the minimum number (rounded up) 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.

Sample values:

  • 3
  • 75%
  • all

Default value: 50%

maximumAge (integer [int32])

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 value: -1 (which corresponds to the internal default value (15 minutes)

mlDidYouMeanMaxCandidates (integer [int32])

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

Default value: 3

mlDidYouMeanMinScore (number [double])

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

mlDidYouMeanUseFacetCount (boolean)

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

Default value: false

mlParameters (object)

A map of parameters to pass to Coveo Machine Learning models for this request.

Available parameters:

  • num (unsigned integer): The maximum number of recommendations to request from the ML models. Value must be in range [1, 50], if specified. Applies to all types of Coveo ML models (i.e., automatic relevance tuning, query suggestions, and event recommendations).

  • padding (string enum): The kind of padding the ML models should use to complete their recommendation output if their requested number of items has not been otherwise reached. Applies to event recommendations ML models only. Allowed values: popular (i.e., pad recommendations with all time most popular items), trending (i.e., pad recommendations with items that have recently been increasingly popular).

  • wordSelection (string): The ITD keyword selection options to use. Applies to ART Coveo ML models with ITD enabled. Value must be a string in the format option:value. Available option: wordsKept (integer): The maximum number of lq keywords to inject in q. Default value: wordsKept:5.

Sample values:

  • {"num": 3, "padding": "popular"}
  • {"wordSelection": "wordsKept:4"}

Additional properties:

[PROPERTY_NAME] (object)

A parameter to pass to the Coveo Machine Learning models.

numberOfResults (integer [int32])

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 1000 items per query.

Default value: 10

parentField (string)

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

Sample value: @foldingchild

partialMatch (boolean)

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

partialMatchKeywords (integer [int32])

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

partialMatchThreshold (string)

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.

Sample values:

  • 3
  • 75%
  • all

Default value: 50%

pipeline (string)

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

Sample value: CustomerQueryPipeline

q (string)

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.

Sample value: Coveo "Cloud V2" platform

queryFunctions (array of RestQueryFunction)

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.

questionMark (boolean)

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

rankingFunctions (array of RestRankingFunction)

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

recommendation (string)

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

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

Sample value: RecommendedProducts

referrer (string)

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.

Sample value: http://www.example.com/

retrieveFirstSentences (boolean)

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

searchById (boolean)

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

Default value: false

searchHub (string)

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.

Sample value: CustomerPortal

sortCriteria (string)

The criteria to use for sorting the query results.

The possible values are:

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

Sample values:

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

Default value: relevancy

staticQuery (boolean)

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

summaryLength (integer [int32])

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

syntax (string)

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

tab (string)

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.

Sample value: ForumTab

timezone (string)

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.

Sample value: America/New_York

visitorId (string)

A GUID representing the current user, who can be authenticated or anonymous. This GUID is normally generated by the usage analytics service and stored in a non-expiring browser cookie.

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

Sample value: 5cb98953-9c13-42ff-8176-e6fcba6a50bf

wildcards (boolean)

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

Query Sub-models

This section provides (or links to) reference documentation for the ActionHistory, RestGroupBy, RestQueryFunction, and RestRankingFunction query sub-models.

ActionHistory

Describes a single query or page view action (see the actionsHistory top-level search request parameter).

name (string)

The action history event name.

Sample value: PageView

Allowed values are:

  • Query
  • PageView

time (string)

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

Sample value: 2017-08-15T17:34:08.398Z

value (string)

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

Sample value: http://www.example.com/

RestCategoryFacet

Describes a single category facet to request along with the query (see the categoryFacets top-level search request parameter).

delimitingCharacter (string)

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

Example:

For a multi-value field containing the following values:

@field: c; c>folder2; c>folder2>folder3;

The delimiting character is >.

Default value: |

Default value is "|".

field (string)

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

Sample value: @categories

filterFacetCount (boolean)

Whether to adjust facet count when filtering, or not.

Default value: true

injectionDepth (integer [int32])

The maximum number of query result items to scan.

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

Default value: 1000

Default value is 1000.

maximumNumberOfValues (integer [int32])

The maximum number of values to return.

Default value: 10

Default value is 10.

path (array of string)

The retrieved sequence of hierarchical field values.

RestGroupBy

Describes a single Group By operation to perform along with a query (see the groupBy query parameter).

See Group By Operations - Group By Parameters.

RestQueryFunction

Describes a single query function to perform along with a query (see the queryFunctions query parameter).

See Query Functions - Query Function Parameters.

RestRankingFunction

Describes a single ranking function to perform along with a query (see the rankingFunctions query parameter).

See Ranking Functions - Ranking Function Parameters.

People also viewed