Skip to end of metadata
Go to start of metadata

Query parameters can be specified either through the query string or in the JSON body of the request.

Note:

Specifying the same parameter in both the query string and the body will cause an error.

Top Level Parameters

q

The basic query expression.

This is typically the query expression entered by the user in a query box. Since this part of the query is expected to come from user input, it is processed by the Did You Mean feature.

aq

The advanced query expression.

This is the part of the query expression generated by code based on various rules.

Example:

Selecting a facet value will cause an expression to be added to the advanced query expression.

cq

The constant query expression.

This part of the expression is much alike the advanced query expression, but it is meant to hold expressions that are constant for all users of a search interface/widget. The results of evaluating those expressions are kept in a special index cache, to avoid re-evaluating them on each query. You must be careful to not include dynamic parts in this expression, otherwise you risk filling up the cache with useless data and this might have a negative impact on performance.

Note:

Expressions other than cq also benefit from caching in the index, but using cq allows to explicitly require that a part of the query be included in the cache.

dq

The disjunction query expression.

This is the disjunctive part of the query expression that is merged with the other expression parts using an OR boolean operator. When specified, the final expression evaluated by the index ends up being (((q aq) OR (dq)) cq).

lq

The large query expression.

This part of the expression 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 uses Intelligent Term Detection to extract relevant keywords from the lq value, and then adds those keywords to the basic query expression (see the q parameter).


lqPartialMatchKeywords

 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 is not ready to handle query.

 See also the lqPartialMatchThreshold parameter.

 

lqPartialMatchThreshold

An absolute or relative value indicating the minimum number (rounded up) of partial match expression keywords the large query (see lq) must contain to match the expression in case the Coveo Machine Learning service is not ready to handle the query.

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

This parameter only has a meaning when Coveo Machine Learning does not return any results.

See also the lqPartialMatchKeywords parameter.

partialMatch

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.

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

If not specified, this parameter defaults to false.

partialMatchKeywords

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

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

If not specified, this parameter defaults to 5.

partialMatchThreshold

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

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

If not specified, this parameter defaults to 50%.

wildcards

Whether to enable wildcards on the basic expression keywords.

This enables the wildcard features of the index. Coveo Platform will expand keywords containing wildcard characters to the possible matching keywords to broaden the query. (See Online Help for more information)

If not specified, this parameter defaults to false.

questionMark

Whether to enable question marks with wildcards.

This enables using the question mark ? character within wildcard expressions.

firstResult

Index of the first result to return.

This is the 0-based index of the first result to return.

If not specified, this parameter defaults to 0.

numberOfResults

The number of results to return.

This is the number of results to return, starting from firstResult.

If not specified, this parameter defaults to 10.

sortCriteria

Sort criteria(s) to use to sort results.

This specifies the sort criterion(s) to use to sort results. If not specified, this parameter defaults to Relevancy.

Available in: June 2015 Release
 You can specify multiple sort criteria by separating them with commas (e.g., @myfield1 ascending,@myfield2 ascending,@myfield3 ascending,...). Multiple sort criteria only work when sorting by date or by custom fields (it is not possible to mix Relevancy and field sorting). Multiple sort criteria are evaluated in the order you specify them (just like an SQL ORDER BY clause). Note that if you specify multiple sort criteria, those criteria must all have the same direction (either ascending or descending), otherwise you will get an unsupported feature exception.

The following table lists available sort criteria (the values are case insensitive).

CriterionDescription

Relevancy

Sort by relevancy. This uses all the configured ranking weights as well as any specified ranking expressions to rank results.

DateAscending
DateDescending

Sort using the value of the @sysdate field, which is typically the last modification date of an item in the index.

FieldAscending
FieldDescending

Sort using the value of a custom field specified using the sortField argument.

Icon

This sort criteria has now been deprecated. We recommending the @field ascending and @field descending syntax described below.

qreSort using only the weights applied through ranking expressions. This is much like using Relevancy except that automatic weights based on keyword proximity etc, are not computed.
nosortDo not sort the results. The order in which items are returned is essentially random.

@field ascending
@field descending

Sort using the value of a custom field.

Available in: June 2015 Release

 

sortField 
Deprecated since: June 2015 Release

Name of the field to use for sorting.

This parameter is used along with sortCriteria to specify the name of the field to sort on.

Icon

This parameter has now been deprecated. We recommend using the @field ascending and @field descending syntax described in sortCriteria to sort using a custom field.

filterField

Name of the field to use for folding.

This specifies a field on which folding should be performed.

Folding is a kind of duplicate filtering where only the first result with any given value of the field is included in the result set. It's typically used to return only one result in a conversation, for example when forum posts in a thread are indexed as separate items.

filterFieldRange

Number of results that should be folded.

This specifies the number of results that should be loaded as child results.

childField

Name of the child field to use when loading the parent.

This specifies a field that the parent should match in order to be loaded in the parentResult field of the QueryResult.

Parent loading can be used to load the parent of a result in a result. To do so, you have to specify two fields that will have the same value. So the childField value of the child field must match the parentField value of the parent field in order for the parent to be loaded.

Icon

The values of the childField must only contain alphanumerical characters. Using a childField whose values contain non-indexable characters (such as underscores) will fail.

Example:

Using a childField containing values such as message_123 will fail.

The childField should contain values such as message123 instead.

parentField

Name of the parent field to use when loading the parent.

This specifies a field that the child should match in order to load the parent in the parentResult field of the QueryResult.

Parent loading can be used to load the parent of a result in a result. To do so, you have to specify two fields that will have the same value. So the childField value of the child field must match the parentField value of the parent field in order for the parent to be loaded.

Icon

The values of the parentField must only contain alphanumerical characters. Using a parentdField whose values contain non-indexable characters (such as underscores) will fail.

Example:

Using a parentField containing values such as message_123 will fail.

The parentField should contain values such as message123 instead.

fieldsToInclude

Fields that should be included in the query results.

This specifies an array of fields that should be returned for each result. Use the syntax for a JSON array when passing this value through the query string (e.g., fieldsToInclude=["foo", "bar"]).

If not specified, all fields are returned by default.

fieldsToExclude

Fields that should be excluded from the query results.

This specifies an array of fields that should be excluded from the query results. Use the syntax for a JSON array when passing this value through the query string (e.g., fieldsToExclude=["foo", "bar"]).

If not specified, all fields are returned by default.

excerptLength

Length of the generated excerpts.

This specifies the length (in number of characters) of the excerpts generated by the indexer based on the keywords present in the query. The index includes the top most interesting sentences (in the order they appear in the item) that fit in the specified number of characters. When not specified, the default value is 200

Tip:

When further clipping is performed on the excerptLength value (using text-overflow: ellipsis for example), specify a value that is close to the number of characters that will really be displayed to the user. 

enableDidYouMean

Whether to suggest query corrections.

This enables the query correction feature of the index. By activating this, the index returns an array of QueryCorrection with suggested word corrections.

timezone

The time zone to use for dates in the query and in the results.

Specifies in what time zone dates specified in the query are. This parameter also affects the dates returned for each results. If not specified, the default time zone of the index server is used.

Time zones are referenced by their ID as specified by the well known TZ library. The list of time zones available can be accessed here.

Note:

Starting with CES 7.0.7022 (September 2014 monthly release), the index handles daylight saving time.

enableDuplicateFiltering

Whether to filter duplicates.

If this is enabled, items that resemble others appear only once in the results. Also, the QueryResults.FilteredResults is populated.

Note:

Enabling this feature may render the total result count less precise, as only the results up to those being retrieved are submitted to filtering.

Example:

If you have 10 unique items and then 90 duplicate ones in the results, the first result page displays a total count of 100 results, but when the user jumps to the second page, the count drops to 11 and only one result is displayed.

retrieveFirstSentences

Whether to retrieve the first sentences..

This specifies whether the first sentences of the item should be included in the results.

Tip:

The retrieveFirstSentences option is typically used instead of excerpts when displaying email items, where the first sentence of the email might be of more interest than a contextually generated excerpt.

scope

ID of the GDI scope to use for the query.

This specifies the ID of the GDI scope that the query should use. This feature is only available when using an on-premises index.

queryFunctions

Definition of query functions to execute on the results.

This specifies an array of Query Function operation that will be executed on the result (see Query Function).

rankingFunctions

Definition of ranking functions to alter the ranking.

This specifies an array of Ranking Function operations that will be executed on the result (see Ranking Function).

groupBy

Definition of the facets to compute on the results.

This specifies an array of Group By operations that can be performed on the query results to extract facets (see Group By Parameters).

searchHub

The hub value set from the JavaScript Search Framework Analytics component (see Analytics Component [V1] and Analytics Component [V0.9]).

Represents the search dimension name.

tab

The tab value set from the JavaScript Search Framework Tab component (see Tab Component [V1] and Tab Component [V0.9]).

Represent the current Tab name in use.

thesaurus

Name of the thesaurus to use to expand the query.

This specifies the name of the thesaurus to use to expand the query. By default, the thesaurus named default is used.

debug

Whether to include debug info in the results.

This specifies whether additional debug information should be included in the resulting JSON. This argument is useful for troubleshooting but causes more data to be transferred back to the caller.

debugRankingInformation

Whether to populate the rankingInfo property of each query result item with detailed information about its ranking factors and weights.

Icon
  • Setting this parameter to true is only useful when the sortCriteria query parameter is set to Relevancy.
  • You should only set this parameter to true when you are investigating relevance issues, as this feature can have an adverse effect on query performance.

pipeline

Name of the query pipeline to use.

This specifies the name of the query pipeline to use for the query. If not specified, the default value is default, which means the default query pipeline will be used.  Add this parameter at the beginning of the query string, for example: http://server/MySearchPage?pipeline=MyPipeline

superUserToken

Available in: June 2015 Release

Super user token to use.

This specifies a super user token that should be used to execute the query. The authenticated user must have the right to use the token. By default, no super user token is used.

This feature is only available for on-premises setups.

context

The custom context information to send along with the query. 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 through the userDefinedContext property of the context object (see Query Pipeline Language).

Example:

format

Available in: November 2015 Release

The format of the results. Use xlsx for excel and json for JSON. By default, the service returns the results in a JSON format.

maximumAge

Available in: February 2016 Release

The maximum age for cached query results, in milliseconds. If results for the exact same request (including user identities) are available in the in-memory cache, they will be used if they are not older than the specified value. Otherwise, the query will be sent to the index.

The default value for this parameter is equivalent to 30 minutes.

enableQuerySyntax

Available in: July 2016 Release

Whether to enable the special query syntax such as field references for the basic query expression (parameter q). Setting this parameter to false is equivalent to applying a No syntax block to the basic query expression.

The default value for this parameter is true.

lowercaseOperators

Whether to treat the ANDNEARNOT, 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.

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

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

locale

The locale of the query. This specifies the user's geographic region and language and is made available in Query Expressions, Pipeline Conditions, and QPL.

 

  • No labels