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.

Note:

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

The Coveo Machine Learning Give recommendations models can use this information to provide contextually relevant output.

aq (string)

The advanced query expression, typically generated by code.

Example:

Selecting a facet value in a graphical search interface could append a certain Coveo Cloud query syntax expression to the aq value.

Sample value:

@year==2017

childField (string)

The name of the field to use to identify an item as a child when folding query results into parent-child relationships (see Result Folding).

Whenever an item is a child, its childField value should be the same as the parentField value of its parent item.

See also the filterField, parentField, and filterFieldRange parameters.

Note:

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.

Sample value:

@childid

context (object)

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

The Coveo Machine Learning models can use this information to provide contextually relevant output. Moreover, this information is accessible with the query pipeline language (QPL).

Sample value:

{
  "userName" : "Alice Smith",
  "userRoles" : [
    "RegisteredCustomer",
    "Consultant"
  ]
}

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, which typically holds Coveo Cloud query syntax expressions that must apply to all queries sent from a certain graphical search interface or widget. Once they have been evaluated, the results of these expressions are kept in a special cache.

Example:

Selecting a tab in a graphical search interface could append a certain Coveo Cloud query syntax expression to the cq value.

Tip:

Avoid including dynamic content in the cq value. Otherwise you risk filling up the cache with useless data, which can have a negative impact on performance.

Note:

Other parts of the query expression can also benefit from the index cache (see the maximumAge parameter). However, specifying a cq value allows you to explicitly include (and retrieve) the results of certain query expressions in the cache.

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

dq (string)

The disjunction query expression, which 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:

@date=2016-12-01..2016-12-31

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.

Note:

The Did You Mean feature only processes the basic query expression (see the q parameter).

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.

enableQuerySyntax (boolean)

Whether to interpret Coveo Cloud query syntax such as field references (e.g., @author=="John Doe") in the basic query expression (see the q parameter). See also the lowercaseOperators parameter.

Default value is 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.

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

Sample value:

250

Default value is 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 name of the field to use to group items when folding query results into parent-child relationships (see Result Folding).

This should correspond to a field whose value a parent item and all of its children have in common.

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/Edit a Field: [FieldName] - Panel ). This limitation does not apply to Coveo indexes.

Sample value:

@conversationid

filterFieldRange (integer [int32])

The maximum number of results to fold per parent-child relationship (see Result Folding).

See also the filterField, parentField, and childField.

Sample value:

8

Default value is 5.

firstResult (integer [int32])

The 0-based index position of the first result to return.

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

Sample value:

0

Default value is 0.

format (string)

The format of a successful response.

  • Use json to get the response in the JSON format (this is the default value).
  • 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.

Sample value: xlsx

Default value is "json".

groupBy (array of RestGroupBy)

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

indexToken (string)

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

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

Note:

Passing an indexToken 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 to query.

Allowed values are:

  • coveo
  • elasticsearch

Default value is coveo.

isGuestUser (boolean)

Whether the current user is anonymous.

Note:

This is useful for usage analytics purposes.

locale (string)

The locale of the current user.

Note:

This value must comply with IETF’s BCP 47 definition.

The Coveo Machine Learning models can use this information to provide contextually relevant output. Moreover, this information is accessible with the query pipeline language (QPL).

Sample value:

en-US

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 query syntax operator.

lq (string)

The large query expression, which typically contains a case description, a long textual query, or any other form of text that can help refine a query. The Coveo Machine Learning service extracts relevant keywords from the lq value, and adds those keywords to 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 Machine Learning service cannot extract relevant keywords from the large query expression.

Note:

This parameter applies as a fallback setting when no Coveo Machine Learning topClicks 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.

Sample value:

4

Default value is 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 Machine Learning service 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 Machine Learning topClicks 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 is "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.

The default maximumAge value (-1) is equivalent to the organization default, which is usually 15 minutes.

Sample value: 1800000

Default value is -1.

mlParameters (object)

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

Available parameters:

  • num: The number of results to request. Value must be an integer between 1 and 50 inclusively. This parameter applies to all types of Coveo ML models (i.e., Automated Relevance Tuning, Query Suggestions, and Recommendations).

Note: The configuration of the Coveo Machine Learning models always has precedence over the mlParameters.

Default value is {}.

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.

Sample value:

5

Default value is 10.

parentField (string)

The name of the field to use to identify the parent item when folding query results into parent-child relationships (see Result Folding).

This should correspond to a field whose value can uniquely identify the parent item. Any item whose childField value is the same as the parentField value of a certain item is considered a child of that item.

See also the filterField, childField, and filterFieldRange parameters.

Note:

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.

Sample value:

@messageid

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 Coveo Cloud query syntax (field expressions, operators, etc.).

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.

Sample value:

4

Default value is 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 empty string and the all value are both equivalent to 100%.

Note:

  • 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 is "50%".

pipeline (string)

The name or ID 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 your request 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).

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.

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.

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.

The Coveo Machine Learning Give recommendations models can use this information to provide contextually relevant output.

Sample value:

RecommendedProducts

referrer (string)

The third level of origin of the request, typically the HTTP identifier of the page from which the request originates.

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

See also the searchHub and tab parameters.

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.

searchById (boolean)

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

searchHub (string)

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

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

See also the tab and referrer parameters.

Sample value:

CustomerPortal

sortCriteria (string)

The sort criterion (or criteria) to use when sorting the query results.

The possible values are:

  • Relevancy: use configured ranking weights as well as any specified ranking expressions to sort the results.
  • DateAscending/DateDescending: use the @date field to sort the results. This field typically contains the last modification date of an item in the index
  • qre: sort using only the weights applied through ranking expressions. This is similar to Relevancy, except that automatic weights based on keyword proximity, etc., are not computed.
  • nosort: do not sort the results. The index will return the results in an essentially random order.
  • @[field] ascending/@[field] descending: sort using the value of a custom, sortable field (replace [field] by the actual field name).

You can specify multiple sort criteria by separating each criterion with a comma. However, this only works when combining zero or one date sort criterion with zero or more field sort criteria.

Sample values:

  • DateAscending
  • @author ascending
  • DateDescending,@views descending,@likes descending
Default value is "Relevancy".

staticQuery (boolean)

Whether to execute this query in a way that does not count against the monthly query limit of a Coveo Cloud organization, but may produce cached/outdated query results.

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

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.

Sample value:

250

Default value is 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.

Sample value:

SOSL

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.

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

See also the searchHub and referrer parameters.

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.

Sample value:

America/New_York

visitorId (string)

A GUID representing the current user, who can be authenticated or anonymous.

Note:

This is useful for usage analytics purposes.

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.

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/

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.