# Class QueryBuilder

The QueryBuilder is used to build a IQuery that will be able to be executed using the Search API.

The class exposes several members and methods that help components and external code to build up the final query that is sent to the Search API.

## Index

### Methods

- addContext
- addContextValue
- addFieldsToExclude
- addFieldsToInclude
- build
- computeCompleteExpression
- computeCompleteExpressionExcept
- computeCompleteExpressionParts
- computeCompleteExpressionPartsExcept
- containsEndUserKeywords

### Properties

- actionsHistory
- advancedExpression
- allowQueriesWithoutKeywords
- categoryFacets
- childField
- commerce
- constantExpression
- context
- disjunctionExpression
- enableCollaborativeRating
- enableDebug
- enableDidYouMean
- enableLowercaseOperators
- enablePartialMatch
- enableQuerySyntax
- enableQuestionMarks
- enableWildcards
- excerptLength
- expression
- facetOptions
- facetRequests
- filterField
- filterFieldRange
- firstResult
- groupByRequests
- longQueryExpression
- maximumAge
- numberOfResults
- parentField
- partialMatchKeywords
- partialMatchThreshold
- pipeline
- queryFunctions
- rankingFunctions
- recommendation
- searchHub
- sortCriteria
- sortField
- tab
- userActions

## Methods

### addContext

- addContext(values: object): void

- - Defined in ui/Base/QueryBuilder.ts :511

  Merges the specified `values` into the `context` object.

  #### Parameters

  - ##### values: object

    The object to merge into the `context` object. Can contain multiple key-value pairs, where each value should be a string or an array of strings. If some keys are already present in the `context` object, their values are updated.

    - ##### [key: string]: any

  #### Returns void

### addContextValue

- addContextValue(key: string, value: any): void

- - Defined in ui/Base/QueryBuilder.ts :499

  Adds or updates a single context key-value pair in the `context` object.

  #### Parameters

  - ##### key: string

    The context key. If this key is already present in the `context` object, its value is updated.

  - ##### value: any

    The context value. This should be a string or an array of strings.

  #### Returns void

### addFieldsToExclude

- addFieldsToExclude(fields: string[]): void

- - Defined in ui/Base/QueryBuilder.ts :481

  Add fields to specifically exclude when the results return.

  This can be used to accelerate the execution time of every query, as there is much less data to process if you blacklist specific fields.

  #### Parameters

  - ##### fields: string[]

  #### Returns void

### addFieldsToInclude

- addFieldsToInclude(fields: string[]): void

- - Defined in ui/Base/QueryBuilder.ts :467

  Add fields to specifically include when the results return.

  This can be used to accelerate the execution time of every query, as there is much less data to process if you whitelist specific fields.

  #### Parameters

  - ##### fields: string[]

  #### Returns void

### build

- build(): IQuery

- - Defined in ui/Base/QueryBuilder.ts :337

  Build the current content or state of the query builder and return a IQuery.

  build can be called multiple times on the same QueryBuilder.

  #### Returns IQuery

### computeCompleteExpression

- computeCompleteExpression(): string

- - Defined in ui/Base/QueryBuilder.ts :398

  Return only the expression(s) part(s) of the query, as a string.

  This means the basic, advanced and constant part in a complete expression IQuery.q, IQuery.aq, IQuery.cq.

  #### Returns string

### computeCompleteExpressionExcept

- computeCompleteExpressionExcept(except: string): string

- - Defined in ui/Base/QueryBuilder.ts :422

  Return only the expression(s) part(s) of the query, as a string, except the given expression.

  This is used by Facet, to build their group by request with query override.

  #### Parameters

  - ##### except: string

  #### Returns string

### computeCompleteExpressionParts

- computeCompleteExpressionParts(): QueryBuilderExpression

- - Defined in ui/Base/QueryBuilder.ts :406

  Return only the expression(s) part(s) of the query, as an object.

  #### Returns QueryBuilderExpression

### computeCompleteExpressionPartsExcept

- computeCompleteExpressionPartsExcept(except: string): QueryBuilderExpression

- - Defined in ui/Base/QueryBuilder.ts :433

  Return only the expression(s) part(s) of the query, as an object, except the given expression.

  This is used by Facet, to build their group by request with query override.

  #### Parameters

  - ##### except: string

  #### Returns QueryBuilderExpression

### containsEndUserKeywords

- containsEndUserKeywords(): boolean

- - Defined in ui/Base/QueryBuilder.ts :523

  Returns true if the current query contains any expression that are considered "end user input".

  This usually means anything entered in the basic (see [q]{@link IQuery.options.q}) or long (see [lq]{@link IQuery.options.lq}) part of the query.

  #### Returns boolean

## Properties

### actionsHistory

actionsHistory: string

- Defined in ui/Base/QueryBuilder.ts :310

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

### advancedExpression

advancedExpression: ExpressionBuilder

- Defined in ui/Base/QueryBuilder.ts :32

Used to build the advanced part of the query expression.

This part is typically formed of filter expressions generated by components such as facets, external code, etc.

type

  {Coveo.ExpressionBuilder}

### allowQueriesWithoutKeywords

allowQueriesWithoutKeywords: boolean

- Defined in ui/Base/QueryBuilder.ts :322

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.

### categoryFacets

categoryFacets: ICategoryFacetRequest[]

- Defined in ui/Base/QueryBuilder.ts :298

Specifies an array of request for the CategoryFacet component.

### childField

childField: string

- Defined in ui/Base/QueryBuilder.ts :227

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

### commerce

commerce: ICommerceRequest

- Defined in ui/Base/QueryBuilder.ts :330

A request for a commerce query.

### constantExpression

constantExpression: ExpressionBuilder

- Defined in ui/Base/QueryBuilder.ts :39

Used to build the advanced part of the query expression.

This part is similar to `advancedExpression`, but its content is interpreted as a constant expression by the index and it takes advantage of special caching features.

type

  {Coveo.ExpressionBuilder}

### context

context: object

- Defined in ui/Base/QueryBuilder.ts :305

The custom context information to send along with the query. Each value should be a string or an array of strings.

Custom context information can influence the output of Coveo Machine Learning models and can also be used in query pipeline conditions.

#### Type declaration

- ##### [key: string]: any

### disjunctionExpression

disjunctionExpression: ExpressionBuilder

- Defined in ui/Base/QueryBuilder.ts :56

Used to build the disjunctive part of the query expression.

When present, this part is evaluated separately from the other expressions and the matching results are merged to those matching expressions, `advancedExpression` and `constantExpression`.

The final boolean expression for the query is thus (basic advanced constant) OR (disjunction).

type

  {Coveo.ExpressionBuilder}

### enableCollaborativeRating

enableCollaborativeRating: boolean

- Defined in ui/Base/QueryBuilder.ts :251

Note:

> The Coveo Cloud V2 platform does not support collaborative rating. Therefore, this property is obsolete in Coveo Cloud V2.

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

### enableDebug

enableDebug: boolean

- Defined in ui/Base/QueryBuilder.ts :243

Whether to enable debug info on the query.

This will return additional information on the resulting JSON response from the Search API.

Mostly: execution report (a detailed breakdown of the parsed and executed query).

### enableDidYouMean

enableDidYouMean: boolean

- Defined in ui/Base/QueryBuilder.ts :235

Whether to enable query corrections on this query (see DidYouMean).

### enableLowercaseOperators

enableLowercaseOperators: boolean

- Defined in ui/Base/QueryBuilder.ts :141

Whether to interpret the `AND`, `NOT`, `OR`, and `NEAR` keywords in the basic `expression` as query operators, even if those keywords are in lowercase.

Setting this attribute to `true` has no effect unless `enableQuerySyntax` is also `true`.

Note:

> Normally, the `enableLowercaseOperators` option of the `Querybox` component determines the value of this attribute during the initialization of the search page.

### enablePartialMatch

enablePartialMatch: boolean

- Defined in ui/Base/QueryBuilder.ts :155

Whether to automatically convert the basic `expression` to a partial match expression if it contains at least a certain number of keywords (see `partialMatchKeywords`), so that items containing at least a certain subset of those keywords (see `partialMatchThreshold`) will match the query.

Note:

> Normally, the `enablePartialMatch` option of the `Querybox` component determines the value of this attribute during the initialization of the search page.

### enableQuerySyntax

enableQuerySyntax: boolean

- Defined in ui/Base/QueryBuilder.ts :127

Whether to interpret special query syntax (e.g., `@objecttype=message`) in the basic `expression` (see Coveo Query Syntax Reference).

See also `enableLowercaseOperators`.

Note:

> Normally, the `enableQuerySyntax` option of the `Querybox` component determines the value of this attribute during the initialization of the search page. End user preferences can also modify the value of this attribute.

Default value is `false`

### enableQuestionMarks

enableQuestionMarks: boolean

- Defined in ui/Base/QueryBuilder.ts :111

Whether to interpret question mark characters (`?`) in the basic `expression` keywords (see Using Wildcards in Queries.

Setting this attribute to `true` has no effect unless `enableWildcards` is also `true`.

Note:

> Normally, the `enableQuestionMarks` option of the `Querybox` component determines the value of this attribute during the initialization of the search page.

### enableWildcards

enableWildcards: boolean

- Defined in ui/Base/QueryBuilder.ts :97

Whether to interpret wildcard characters (`*`) in the basic `expression` keywords.

Setting this attribute to `true` enables the wildcards features of the index, effectively expanding keywords containing wildcard characters (`*`) to the possible matching keywords in order to broaden the query (see Using Wildcards in Queries).

See also `enableQuestionMarks`.

Note:

> Normally, the `enableWildcards` option of the `Querybox` component determines the value of this attribute during the initialization of the search page.

### excerptLength

excerptLength: number

- Defined in ui/Base/QueryBuilder.ts :207

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.

### expression

expression: ExpressionBuilder

- Defined in ui/Base/QueryBuilder.ts :25

Used to build the basic part of the query expression.

This part typically consists of user-entered content such as query keywords, etc.

type

  {Coveo.ExpressionBuilder}

### facetOptions

facetOptions: IFacetOptions

- Defined in ui/Base/QueryBuilder.ts :293

The global configuration options to apply to the requests in the [facets]{@link QueryBuilder.facets} array.

### facetRequests

facetRequests: IFacetRequest[]

- Defined in ui/Base/QueryBuilder.ts :288

Specifies an array of request for the DynamicFacet component. Cannot be used alongside `groupByRequests`

### filterField

filterField: string

- Defined in ui/Base/QueryBuilder.ts :215

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

filterFieldRange: number

- Defined in ui/Base/QueryBuilder.ts :219

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

### firstResult

firstResult: number

- Defined in ui/Base/QueryBuilder.ts :193

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

If not specified, this parameter defaults to 0.

### groupByRequests

groupByRequests: IGroupByRequest[]

- Defined in ui/Base/QueryBuilder.ts :282

Specifies an array of Group By operations that can be performed on the query results to extract facets. Cannot be used alongside `facetRequests`

### longQueryExpression

longQueryExpression: ExpressionBuilder

- Defined in ui/Base/QueryBuilder.ts :47

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.

### maximumAge

maximumAge: number

- Defined in ui/Base/QueryBuilder.ts :81

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.

### numberOfResults

numberOfResults: number

- Defined in ui/Base/QueryBuilder.ts :199

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

If not specified, this parameter defaults to 10.

### parentField

parentField: string

- Defined in ui/Base/QueryBuilder.ts :223

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

### partialMatchKeywords

partialMatchKeywords: number

- Defined in ui/Base/QueryBuilder.ts :171

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

The value of this attribute has no meaning unless `enablePartialMatch` is `true`.

See also `partialMatchThreshold`.

Note:

> Normally, the `partialMatchKeywords` option of the `Querybox` component determines the value of this attribute during the initialization of the search page.

### partialMatchThreshold

partialMatchThreshold: string

- Defined in ui/Base/QueryBuilder.ts :187

An absolute or relative (percentage) value indicating the minimum number of partial match expression keywords an item must contain to match the query.

The value of this attribute has no meaning unless `enablePartialMatch` is `true`.

See also `partialMatchKeywords`.

Note:

> Normally, the `partialMatchThreshold` option of the `Querybox` component determines the value of this attribute during the initialization of the search page.

### pipeline

pipeline: string

- Defined in ui/Base/QueryBuilder.ts :73

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.

### queryFunctions

queryFunctions: IQueryFunction[]

- Defined in ui/Base/QueryBuilder.ts :273

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

### rankingFunctions

rankingFunctions: IRankingFunction[]

- Defined in ui/Base/QueryBuilder.ts :277

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

### recommendation

recommendation: string

- Defined in ui/Base/QueryBuilder.ts :314

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

### searchHub

searchHub: string

- Defined in ui/Base/QueryBuilder.ts :62

The hub value set from the Analytics component.

Used for analytics reporting in the Coveo platform.

### sortCriteria

sortCriteria: string

- Defined in ui/Base/QueryBuilder.ts :262

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.

### sortField

sortField: string

- Defined in ui/Base/QueryBuilder.ts :266

deprecated

### tab

tab: string

- Defined in ui/Base/QueryBuilder.ts :66

The tab value set from the Tab component.

### userActions

userActions: IUserActionsRequest

- Defined in ui/Base/QueryBuilder.ts :326

A request to retrieve user actions in the query response.

### Hierarchy

- QueryBuilder