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

partialMatch

Whether to enable partial matching of the basic expression keywords.

This enables the partial match feature of the index. By activating this, when the basic expression contains at least partialMatchKeywords keywords, items containing only the number of keywords specified by partialMatchThreshold will also match the query. Without this option, items are required to contain all the keywords in order to match the query.

This feature is automatically turned off if the basic expression contains special query syntax such as operators, field expressions, etc.

If not specified, this parameter defaults to false.

partialMatchKeywords

The minimum number of keywords needed to activate partial match.

This specifies the minimum number of keywords needed for the partial match feature to activate. If the basic expression contains less than this number of keywords, no transformation is applied on the query.

If not specified, this parameter defaults to 5.

partialMatchThreshold

The threshold to use for matching items when partial match is enabled.

This specifies the minimum number of query keywords that an item must contain when partial match is enabled. This value can either be an absolute number or a percentage value based on the total number of keywords.

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.

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.

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.

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

Value of the context JSON object to use.

This specifies the JSON of the Context userDefinedContext to send in the query. This then makes it available to use with the QPL (see Query Pipeline Language)

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.

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