# Interface IQuery

The IQuery interface describes a query that can be performed on the Coveo REST Search API.

For basic usage, see the IQuery.q and IQuery.aq properties.

In a normal scenario, a query is built by the QueryBuilder class.

## Index

### Properties

- actionsHistory
- allowQueriesWithoutKeywords
- aq
- categoryFacets
- childField
- commerce
- context
- cq
- debug
- dq
- enableCollaborativeRating
- enableDidYouMean
- enableQuerySyntax
- excerptLength
- facetOptions
- facets
- fieldsToExclude
- fieldsToInclude
- filterField
- filterFieldRange
- firstResult
- format
- groupBy
- lowercaseOperators
- lq
- maximumAge
- numberOfResults
- parentField
- partialMatch
- partialMatchKeywords
- partialMatchThreshold
- pipeline
- q
- queryFunctions
- questionMark
- rankingFunctions
- recommendation
- retrieveFirstSentences
- searchHub
- sortCriteria
- tab
- userActions
- wildcards

## Properties

### Optional actionsHistory

actionsHistory: string

- Defined in rest/Query.ts :268

The actions history represents the past actions a user made and is used by the Coveo Machine Learning service to suggest recommendations. It is generated by the page view script (https://github.com/coveo/coveo.analytics.js)

### Optional allowQueriesWithoutKeywords

allowQueriesWithoutKeywords: boolean

- Defined in rest/Query.ts :282

Specifies if the Search API should perform queries even when no keywords were entered by the end user.

End user keywords are present in either the IQuery.q or IQuery.lq part of the query.

This parameter is normally controlled by {@link SearchInterface.options.allowEmptyQuery} option.

### Optional aq

aq: string

- Defined in rest/Query.ts :74

The advanced query expression.
This is the part of the query expression generated by code based on various rules.
eg: Selecting a facet value will cause an expression to be added to the advanced query expression.

### Optional categoryFacets

categoryFacets: ICategoryFacetRequest[]

- Defined in rest/Query.ts :228

Specifies an array of request to retrieve facet values for the CategoryFacet component

### Optional childField

childField: string

- Defined in rest/Query.ts :254

Specifies the childField when doing parent-child loading (See: Folding)

### Optional commerce

commerce: ICommerceRequest

- Defined in rest/Query.ts :306

The commerce request to execute.

### Optional context

context: Context

- Defined in rest/Query.ts :262

The context is a map of key_value that can be used in the Query pipeline in the Coveo platform.

### Optional cq

cq: string

- Defined in rest/Query.ts :82

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

### Optional debug

debug: boolean

- Defined in rest/Query.ts :238

Whether to include debug information from the Search API in the query response.

Note:

> This debug information does not include ranking information.

Setting this property to `true` can have an adverse effect on query performance, so it should always be left to `false` in a production environment.

### Optional dq

dq: string

- Defined in rest/Query.ts :96

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 cq) OR (dq).

### Optional enableCollaborativeRating

enableCollaborativeRating: boolean

- Defined in rest/Query.ts :250

Whether the index should take collaborative rating in account when ranking result. See: ResultRating

### Optional enableDidYouMean

enableDidYouMean: boolean

- Defined in rest/Query.ts :212

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

### Optional enableQuerySyntax

enableQuerySyntax: boolean

- Defined in rest/Query.ts :245

Whether to enable the special query syntax such as field references for the basic query expression (parameter q). It is equivalent to a No syntax block applied to the basic query expression. If not specified, the parameter defaults to false

### Optional excerptLength

excerptLength: number

- Defined in rest/Query.ts :202

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.

### Optional facetOptions

facetOptions: IFacetOptions

- Defined in rest/Query.ts :292

The global configuration options to apply to the requests in the facets array.

### Optional facets

facets: IFacetRequest[]

- Defined in rest/Query.ts :287

Specifies an array of request to retrieve facet values for the DynamicFacet component.

### Optional fieldsToExclude

fieldsToExclude: string[]

- Defined in rest/Query.ts :196

Specifies an array of fields that should be excluded from the query results.
eg: ['@foo','@bar']

### Optional fieldsToInclude

fieldsToInclude: string[]

- Defined in rest/Query.ts :190

Specifies an array of fields that should be returned for each result.
eg: ['@foo','@bar']

### Optional filterField

filterField: string

- Defined in rest/Query.ts :180

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.

### Optional filterFieldRange

filterFieldRange: number

- Defined in rest/Query.ts :184

Number of results that should be folded, using the IQuery.filterField

### Optional firstResult

firstResult: number

- Defined in rest/Query.ts :158

This is the 0-based index of the first result to return.
If not specified, this parameter defaults to 0.

### Optional format

format: ResponseFormat

- Defined in rest/Query.ts :311

The format of a successful response. If not specified, this parameter defaults to 'json'.

### Optional groupBy

groupBy: IGroupByRequest[]

- Defined in rest/Query.ts :224

Specifies an array of Group By operations that can be performed on the query results to extract facets

### Optional lowercaseOperators

lowercaseOperators: boolean

- Defined in rest/Query.ts :133

Whether to enable the support for operator in lowercase (AND OR -> and or)

### Optional lq

lq: string

- Defined in rest/Query.ts :90

The contextual text.
This is the contextual text part of the query. It uses the Coveo Machine Learning service to pick key keywords from the text and add them to the basic expression. This field is mainly used to pass context such a case description, long textual query or any other form of text that might help in refining the query.

### Optional maximumAge

maximumAge: number

- Defined in rest/Query.ts :117

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.

### Optional numberOfResults

numberOfResults: number

- Defined in rest/Query.ts :163

This is the number of results to return, starting from IQuery.firstResult.
If not specified, this parameter defaults to 10.

### Optional parentField

parentField: string

- Defined in rest/Query.ts :258

Specifies the parentField when doing parent-child loading (See: Folding)

### Optional partialMatch

partialMatch: boolean

- Defined in rest/Query.ts :140

Whether to enable partial matching of the basic expression keywords.
By activating this, when the basic expression contains at least IQuery.partialMatchKeywords, items containing only the number of keywords specified by IQuery.partialMatchThreshold will also match the query.
Without this option, items are required to contain all the keywords in order to match the query.
If not specified, this parameter defaults to false.

### Optional partialMatchKeywords

partialMatchKeywords: number

- Defined in rest/Query.ts :147

The minimum number of keywords needed to activate partial match.
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.

### Optional partialMatchThreshold

partialMatchThreshold: string

- Defined in rest/Query.ts :153

The threshold to use for matching items when partial match is enabled.
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%.

### Optional pipeline

pipeline: string

- Defined in rest/Query.ts :111

Name of the query pipeline to use.
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.

### q

q: string

- Defined in rest/Query.ts :68

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.

### Optional queryFunctions

queryFunctions: IQueryFunction[]

- Defined in rest/Query.ts :216

Specifies an array of Query Function operation that will be executed on the results.

### Optional questionMark

questionMark: boolean

- Defined in rest/Query.ts :129

Whether to enable question marks with wildcards.
This enables using the question mark ? character within wildcard expressions.

### Optional rankingFunctions

rankingFunctions: IRankingFunction[]

- Defined in rest/Query.ts :220

Specifies an array of Ranking Function operations that will be executed on the result

### Optional recommendation

recommendation: string

- Defined in rest/Query.ts :273

This is the id of the recommendation interface that generated the query.

### Optional retrieveFirstSentences

retrieveFirstSentences: boolean

- Defined in rest/Query.ts :207

Specifies whether the first sentences of the item should be included in the results.
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.

### Optional searchHub

searchHub: string

- Defined in rest/Query.ts :101

The hub value set from the Analytics component.
Used for analytics reporting in the Coveo platform

### Optional sortCriteria

sortCriteria: string

- Defined in rest/Query.ts :173

Specifies the sort criterion(s) to use to sort results. If not specified, this parameter defaults to Relevancy.
Possible values are :
-- 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 @date field, which is typically the last modification date of an item in the index.
-- qre : Sort 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.
-- nosort : Do 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.

### Optional tab

tab: string

- Defined in rest/Query.ts :105

The tab value set from the Tab component.

### Optional userActions

userActions: IUserActionsRequest

- Defined in rest/Query.ts :302

The user ID or visitor ID whose item views should be tagged in the query results (see the isUserActionView property of the IQueryResult interface).

Examples:

- asmith@example.com
- 6318b0c6-9397-4d70-b393-cf4770fd1bab

### Optional wildcards

wildcards: boolean

- Defined in rest/Query.ts :124

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 Using Wildcards in Queries.
If not specified, this parameter defaults to false.

### Hierarchy

- IQuery