coveo-search-ui
Version:
Coveo JavaScript Search Framework
1,493 lines (1,456 loc) • 795 kB
TypeScript
/// <reference path="Externals.d.ts" />
declare module Coveo {
function shim(): void;
}
declare module Coveo {
function customEventPolyfill(): void;
}
declare module Coveo {
var version: {
lib: string;
product: string;
supportedApiVersion: number;
};
}
declare module Coveo {
/**
* A JSON which contains type T.
*
* eg :
* ```
* IStringMap<boolean> -> {'foo' : true, 'bar' : false};
* IStringMap<number> -> {'foo' : 1 , 'bar' : 123}
* ```
*
*/
interface IStringMap<T> {
[paramName: string]: T;
}
}
declare module Coveo {
class Logger {
static TRACE: number;
static DEBUG: number;
static INFO: number;
static WARN: number;
static ERROR: number;
static NOTHING: number;
static level: number;
static executionTime: boolean;
constructor(owner: any);
trace(...stuff: any[]): void;
debug(...stuff: any[]): void;
info(...stuff: any[]): void;
warn(...stuff: any[]): void;
error(...stuff: any[]): void;
static enable(): void;
static disable(): void;
}
}
declare module Coveo {
/**
* A highlight structure, as returned by the index.
* This structure can be used to do the actual highlighting job.
*/
interface IHighlight {
/**
* The 0 based offset inside the string where the highlight should start.
*/
offset: number;
/**
* The length of the offset.
*/
length: number;
/**
* The group number for the highlight. A single string can have the same term highlighted multiple times.
* This allows to regroup the different highlights.
*/
dataHighlightGroup?: number;
/**
* The string that represent the highlight. A single string can have the same term highlighted multiple times.
* This allows to regroup the different highlights.
*/
dataHighlightGroupTerm?: string;
}
/**
* The data about a single term to highlight.
*/
interface IHighlightTerm {
/**
* The term that needs to be highlighted, as well as the list of stemming expansions.
*/
[originalTerm: string]: string[];
}
/**
* The data about a single phrase to highlight.
*/
interface IHighlightPhrase {
/**
* The phrase that needs to be highlighted, with the different terms associated.
*/
[phrase: string]: IHighlightTerm;
}
}
declare module Coveo {
function buildHistoryStore(): any;
function buildNullHistoryStore(): any;
}
declare module Coveo {
interface IEndpointError extends Error {
message: string;
type: string;
name: string;
}
}
declare module Coveo {
/**
* Describe a query function that can be executed against the index<br/>
* See: [Query Functions](https://docs.coveo.com/en/1451/)
*/
interface IQueryFunction {
/**
* Function to execute, as a string
*/
function: string;
/**
* The field name on which to store the query function result when the query returns
*/
fieldName: string;
}
}
declare module Coveo {
/**
* Describe a ranking function that can be executed against the index.<br/>
* See: [Ranking Functions](https://docs.coveo.com/en/1448/)
*/
interface IRankingFunction {
/**
* The mathematical expression that calculates the ranking value to add to the result score.
*/
expression: string;
/**
* Whether to normalize the value using the standard index scale or not. If you don't want to completely override the index ranking and use the qrf as a boost, you should turn this on.
*/
normalizeWeight: boolean;
}
}
declare module Coveo {
/**
* Describe a computed field request<br/>
* See: [Computed Fields](https://docs.coveo.com/en/1467/)
*/
interface IComputedFieldRequest {
/**
* This specifies the field on which the aggregate operation will be performed. This field is typically a numerical value.
*/
field: string;
/**
* This specifies the operation to execute on the field value.<br/>
* Possible operations:
* -- sum: Computes the sum of all values.
* -- average: Computes the average of all values.
* --minimum: Retrieves the smallest of all values.
* --maximum: Retrieves the largest of all values.
*/
operation: string;
}
}
declare module Coveo {
enum RangeEndScope {
Inclusive,
Exclusive,
}
type RangeType = string | number | Date;
/**
* Describes a single range value in a [group by request]{@link IGroupByRequest} or [facet request]{@link IFacetRequest}.
*/
interface IRangeValue {
/**
* The value to start the range at.
*
* **Examples:**
* > - `0`
* > - `2018-01-01T00:00:00.000Z`
*/
start?: RangeType;
/**
* The value to end the range at.
*
* **Examples:**
* > - `500`
* > - `2018-12-31T23:59:59.999Z`
*/
end?: RangeType;
/**
* The label to associate with the range value.
*
* **Examples:**
* > - `0 - 500`
* > - `In 2018`
*/
label?: string;
/**
* Whether to include the [`end`]{@link IRangeValue.end} value in the range.
*/
endInclusive?: boolean;
}
}
declare module Coveo {
/**
* The possible values for the [allowedValuesPatternType]{@link IGroupByRequest.allowedValuesPatternType} property of the `IGroupByRequest` interface.
*/
enum AllowedValuesPatternType {
/**
* Only supports trailing wildcards in the pattern.
*/
Legacy,
/**
* Fully supports wildcards.
*/
Wildcards,
/**
* Supports regular expression as the pattern.
*/
Regex,
/**
*Applies the Edit Distance algorithm to match values that are close to the specified pattern.
*/
EditDistance,
/**
*Applies a phonetic algorithm to match values that are phonetically similar to the specified pattern.
*/
Phonetic,
}
}
declare module Coveo {
/**
* The `IGroupByRequest` interface describes a Group By operation to perform against the index.
*
* See [Group By Operations](https://docs.coveo.com/en/1453/).
*/
interface IGroupByRequest {
/**
* Specifies the field on which to perform the Group By request. The Group By request returns a Group By value for
* each distinct value of this field within the result set.
*/
field: string;
lookupField?: string;
/**
* Specifies how the indexer should sort the Group By values.
*
* The possible values are:
* - `score`: Sort by score. Score is computed from the number of occurrences of a field value, as well as from the
* position where results having this field value appear in the ranked result set. When using this sort criterion, a
* field value with 100 occurrences might appear after one with only 10 occurrences, if the occurrences of the latter
* tend to appear sooner in the ranked result set.
* - `occurrences`: Sort by number of occurrences, with values having the highest number of occurrences appearing
* first.
* - `alphaascending` / `alphadescending`: Sort alphabetically on the field values.
* - `computedfieldascending` / `computedfielddescending`: Sort on the values of the first computed field for each
* Group By value (see [Computed Fields](https://docs.coveo.com/en/1467/)).
* - `chisquare`: Sort based on the relative frequency of values in the result set compared to the frequency in the
* entire index. This means that a value that does not appear often in the index but does appear often in the result
* set will tend to appear first.
* - `nosort`: Do not sort the Group By values. When using this sort criterion, the index returns the Group By values
* in a random order.
*
* Default value is `score`.
*/
sortCriteria?: string;
/**
* Specifies the maximum number of values that the Group By operation can return.
*
* Default value is `10`. Minimum value is `0`.
*/
maximumNumberOfValues?: number;
/**
* Specifies how deep the index should scan the results to identify missing Group By values.
*
* When executing a Group By operation, the index uses various heuristics to try to list all of the field values that
* appear in the result set. In some corner cases, certain values might be omitted (it is a classical example of a
* trade-off between precision and performance). Using `injectionDepth` forces the index to explicitly scan the field
* values of the top n results of the query, and ensure that the field values present in those results are included.
*
* Consequently, specifying a high value for this parameter may negatively impact query performance.
*
* Default value is `1000`. Minimum value is `1000`.
*
* @examples 1500
*/
injectionDepth?: number;
/**
* Specifies a different query expression on which to compute the Group By operation.
*
* This feature is typically used for performance reasons to retrieve Group By values on separate expressions while
* executing a normal query in a single operation.
*
* By default, the query expression being executed is used.
*/
queryOverride?: string;
advancedQueryOverride?: string;
/**
* Specifies a constant query expression on which to compute the Group By operation.
*
* This feature is similar to the [`queryOverride`]{@link IGroupByRequest.queryOverride} feature, except that in this
* case, the index keeps the constant query expression in cache for faster queries. You should avoid specifying a
* dynamic query expression for this parameter, for doing so will negatively impact performance.
*
* By default, the constant part of the query expression being executed is used.
*/
constantQueryOverride?: string;
/**
* Explicitly specifies a list of values for which to generate Group By values.
*
* You can use trailing wildcards to include ranges of values.
*
* **Example:**
* > The array `["foo", "bar*"]` would return Group By values for `foo` and any value starting with `bar`.
*/
allowedValues?: string[];
/**
* The pattern type to use for the {@link IGroupByRequest.allowedValues} property (see {@link AllowedValuesPatternType}).
*
* This option is empty by default, which makes it behave as [`legacy`]{@link AllowedValuesPatternType.Legacy}.
*/
allowedValuesPatternType?: AllowedValuesPatternType;
/**
* Specifies an array of computed fields that should be evaluated for each Group By value that is returned.
*
* Computed fields are used to perform aggregate operations on other fields for all the matching items having a
* specific value in the Group By field in the results. See
* [Computed Fields](https://docs.coveo.com/en/1467/).
*/
computedFields?: IComputedFieldRequest[];
/**
* Explicitly specifies a list of range values for which Group By values should be generated.
*/
rangeValues?: IRangeValue[];
/**
* Specifies whether to let the index calculate the ranges.
*
* Default value is `false`.
*/
generateAutomaticRanges?: boolean;
completeFacetWithStandardValues?: boolean;
}
}
declare module Coveo {
/**
* A context, as returned by {@link SearchInterface.getQueryContext} or {@link PipelineContext.getContext}
*/
type Context = IStringMap<string | string[]>;
interface IPipelineContextProvider {
getContext: () => Context;
}
}
declare module Coveo {
interface ICategoryFacetRequest {
field: string;
path?: string[];
maximumNumberOfValues?: number;
injectionDepth?: number;
delimitingCharacter?: string;
}
}
declare module Coveo {
/**
* The allowed states of a facet value in a Search API facet
* [request]{@link IFacetRequestValue.state} or
* [response]{@link IFacetResponseValue.state}.
*/
enum FacetValueState {
/**
* The facet value is not currently selected or excluded in the search
* interface.
*/
idle,
/**
* The facet value is currently selected in the search interface.
*/
selected,
}
}
declare module Coveo {
/**
* The allowed sort criteria for a Search API
* [facet request]{@link IFacetRequest}.
*/
enum FacetSortCriteria {
/**
* Sort facet values in descending score order.
*
* Facet value scores are based on number of occurrences and position in the
* ranked query result set.
*
* The Coveo Machine Learning dynamic navigation experience feature only
* works with this sort criterion.
*/
score,
/**
* Sort facet values in ascending alphanumeric order.
*/
alphanumeric,
/**
* Sort facet values in descending number of occurrences.
*/
occurrences,
}
function isFacetSortCriteria(sortCriteria: string): boolean;
}
declare module Coveo {
enum FacetRangeSortOrder {
/**
* Sort facet values in ascending order.
*/
ascending,
/**
* Sort facet values in ascending order.
*/
descending,
}
function isFacetRangeSortOrder(sortOrder: string): boolean;
}
declare module Coveo {
/**
* The allowed values for the [`facetType`]{@link IFacetRequest.facetType} property of a [facet request]{@link IFacetRequest}.
*/
enum FacetType {
/**
* Request facet values representing specific values.
*/
specific,
/**
* Request facet values representing ranges of numbers.
*/
numericalRange,
/**
* Request facet values representing ranges of dates.
*/
dateRange,
/**
* Request facet values representing a hierarchy.
*/
hierarchical,
}
/**
* A [`currentValues`]{@link IFacetRequest.currentValues} item in a Search API
* [facet request]{@link IFacetRequest}.
*/
interface IFacetRequestValue extends IRangeValue {
/**
* The current facet value state in the search interface.
*
* **Default (Search API):** `idle`
*/
state: FacetValueState;
/**
* **Required (Search API).** The facet value name.
*/
value?: string;
/**
* Whether to prevent Coveo ML from automatically selecting the facet value.
*
* **Default:** `false`
*/
preventAutoSelect?: boolean;
/**
* Whether to retrieve the children of this category facet value. Can only be used on leaf values in the request (i.e., values with no current children).
*
* **Default:** `false`
*/
retrieveChildren?: boolean;
/**
* If [retrieveChildren]{@link IFacetRequestValue.retrieveChildren} is true, the maximum number of children to retrieve for this leaf value.
*
* **Default (Search API):** `0`
*/
retrieveCount?: number;
/**
* The children of this category facet value.
* Each child is a full-fledged category facet value that may in turn have its own children and so forth,
* up to a maximum depth of 50 levels
*/
children?: IFacetRequestValue[];
}
/**
* A Search API facet request.
*/
interface IFacetRequest {
/**
* The unique identifier of the facet in the search interface.
*
* **Note:** Must match `^[A-Za-z0-9-_]{1,60}$`.
*
* **Example:** `author-1`
*/
facetId: string;
/**
* **Required (Search API).** The name of the field on which to base the
* facet request.
*
* **Note:** Must reference an index field whose **Facet** option is enabled.
*
* **Example:** `author`
*/
field: string;
/**
* The kind of values to request for the facet.
*
* **Default (Search API):** [`Specific`]{@link FacetType.Specific}
*/
type?: FacetType;
/**
* The sort criterion to apply to the returned facet values.
*
* **Default behaviour when [`type`]{@link IFacetRequest.type} is set to [`specific`]{@link FaceType.Specific}
* or [`hierarchical`]{@link FaceType.Hierarchical} (Search API):**
* - When [`isFieldExpanded`]{@link IFacetRequest.isFieldExpanded} is `false`
* in the facet request, and
* [`moreValuesAvailable`]{@link IFacetResponse.moreValuesAvailable} is
* `true` in the corresponding [facet response]{@link IFacetResponse}, use
* `score`.
* - Otherwise, use `alphanumeric`.
*
* **Default (Search API) when [`type`]{@link IFacetRequest.type} is set to [`dateRange`]{@link FaceType.dateRange}
* or [`numericalRange`]{@link FacetType.numericalRange} (Search API)::** `ascending`
* Other possible value: `descending`
*/
sortCriteria?: FacetSortCriteria | FacetRangeSortOrder;
/**
* The maximum number of facet values to fetch.
*
* **Note:** If
* [`freezeCurrentValues`]{@link IFacetRequest.freezeCurrentValues} is
* `true`, `numberOfValues` must be equal to the
* [`currentValues`]{@link IFacetRequest.currentValues} array length.
*
* **Default (Search API):** `8`
*/
numberOfValues?: number;
/**
* The maximum number of items to scan for facet values.
*
* **Note:** A high `injectionDepth` may negatively impact the facet request
* performance.
*
* **Default (Search API):** `1000`
*/
injectionDepth?: number;
/**
* Whether to include the facet request's
* [`currentValues`]{@link IFacetRequest.currentValues} in the corresponding
* [facet response]{@link IFacetResponse}'s
* [`values`]{@link IFacetResponse.values} array.
*
* **Note:** Setting this to `true` is useful to ensure that the facet does
* not move around while the end-user is interacting with it in the search
* interface.
*
* **Default (Search API):** `false`
*/
freezeCurrentValues?: boolean;
/**
* The values displayed by the facet in the search interface at the moment of
* the request.
*
* See [IFacetRequestValue]{@link IFacetRequestValue}.
*
* **Default (Search API):** `[]`
*/
currentValues?: IFacetRequestValue[];
/**
* Whether the facet is expanded in the search interface at the moment of the
* request.
*
* **Default (Search API):** `false`
*/
isFieldExpanded?: boolean;
/**
* Whether to automatically generate range values for the facet.
*
* **Notes:**
* - Setting this to `true` is only effective when [`type`]{@link IFacetRequest.type} is set to [`dateRange`]{@link FaceType.dateRange}
* or [`numericalRange`]{@link FacetType.numericalRange}, and the referenced [`field`]{@link IFacetRequest.field} is of a corresponding type (i.e., date or numeric).
* - Automatic range generation will fail if the referenced `field` is dynamically generated by a query function.
* - Enabling the **Use cache for numeric queries** option on the referenced `field` will speed up automatic range generation (see [Add or Edit Fields](https://docs.coveo.com/en/1982/)).
*
* **Default (Search API):** `false`
*/
generateAutomaticRanges?: boolean;
/**
* The character to use to split field values into a hierarchical sequence.
*
* **Example:**
* For a multi-value field containing the following values: `c; c>folder2; c>folder2>folder3;`
* The delimiting character is `>`.
*
* **Default (Search API):** `;`
*/
delimitingCharacter?: string;
/**
* Whether to exclude folded result parents when estimating result counts for facet values.
*
* **Default (Search API):** `true`
*/
filterFacetCount?: boolean;
/**
* The base path shared by all values for a given hierarchical facet.
*
* **Default (Search API):** `[]`
*/
basePath?: string[];
/**
* Whether to use the [`basePath`]{@link FacetRequest.basePath} as a filter for the results.
*
* **Note:** This parameter is ignored unless the facet [`type`]{@link FacetRequest.type} is `hierarchical`.
*
* **Default (Search API):** `true`
*/
filterByBasePath?: boolean;
/**
* Whether to prevent Coveo ML from automatically selecting values from that facet.
*
* **Default:** `false`
*/
preventAutoSelect?: boolean;
}
}
declare module Coveo {
/**
* The format of a successful response.
*/
type ResponseFormat = 'json' | 'opensearch-atom' | 'opensearch-rss' | 'xlsx';
/**
* The available global configuration options when requesting facets through the [facets]{IQuery.facets} array.
*/
interface IFacetOptions {
/**
* Whether the facet values should be returned in their current order.
*/
freezeFacetOrder?: Boolean;
}
/**
* The information about the user we'd like to check and its actions.
*/
interface IUserActionsRequest {
/**
* The id of the user for which we should check the document views.
*/
tagViewsOfUser: string;
}
/**
* A Search API commerce request.
*/
interface ICommerceRequest {
/**
* The unique identifier of the catalog to query.
*
* **Example:** `46bc4275-e613-4dd5-b1ea-3e5aca1bcd9d`
*/
catalogId?: string;
/**
* A mandatory query expression to apply if the commerce request affects the query.
* **Example:** `@storeid==1001`
*/
filter?: string;
/**
* The way the commerce request should affect query results.
* **Example:** `selectCatalogObjects`
*/
operation?: 'selectCatalogObjects' | 'excludeCatalogObjects';
}
/**
* The IQuery interface describes a query that can be performed on the Coveo REST Search API.
*
* For basic usage, see the {@link IQuery.q} and {@link IQuery.aq} properties.
*
* In a normal scenario, a query is built by the {@link QueryBuilder} class.
*/
interface IQuery {
/**
* The basic query expression. <br/>
* This is typically the query expression entered by the user in a query box.<br/>
* Since this part of the query is expected to come from user input, it is processed by the Did You Mean feature.
*/
q: string;
/**
* The advanced query expression.<br/>
* This is the part of the query expression generated by code based on various rules.<br/>
* eg: Selecting a facet value will cause an expression to be added to the advanced query expression.
*/
aq?: string;
/**
* The constant query expression.<br/>
* 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.<br/>
* The results of evaluating those expressions are kept in a special index cache, to avoid re-evaluating them on each query.<br/>
* 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.<br/>
* 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.
*/
cq?: string;
/**
* The contextual text.<br/>
* 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.
*/
lq?: string;
/**
* The disjunction query expression.<br/>
* This is the disjunctive part of the query expression that is merged with the other expression parts using an OR boolean operator.<br/>
* When specified, the final expression evaluated by the index ends up being (q aq cq) OR (dq).
*/
dq?: string;
/**
* The hub value set from the {@link Analytics} component.<br/>
* Used for analytics reporting in the Coveo platform
*/
searchHub?: string;
/**
* The tab value set from the {@link Tab} component.
*/
tab?: string;
locale?: string;
/**
* Name of the query pipeline to use.<br/>
* 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.
*/
pipeline?: string;
/**
* The maximum age for cached query results, in milliseconds.<br/>
* 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.<br/>
* Otherwise, the query will be sent to the index.
*/
maximumAge?: number;
/**
* Whether to enable wildcards on the basic expression keywords.<br/>
* 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.<br/>
* See [Using Wildcards in Queries](https://docs.coveo.com/en/1580/).<br/>
* If not specified, this parameter defaults to false.
*/
wildcards?: boolean;
/**
* Whether to enable question marks with wildcards.<br/>
* This enables using the question mark ? character within wildcard expressions.
*/
questionMark?: boolean;
/**
* Whether to enable the support for operator in lowercase (AND OR -> and or)
*/
lowercaseOperators?: boolean;
/**
* Whether to enable partial matching of the basic expression keywords.<br/>
* By activating this, when the basic expression contains at least {@link IQuery.partialMatchKeywords}, items containing only the number of keywords specified by {@link IQuery.partialMatchThreshold} will also match the query.<br/>
* Without this option, items are required to contain all the keywords in order to match the query.<br/>
* If not specified, this parameter defaults to false.
*/
partialMatch?: boolean;
/**
* The minimum number of keywords needed to activate partial match.<br/>
* Specifies the minimum number of keywords needed for the partial match feature to activate.<br/>
* If the basic expression contains less than this number of keywords, no transformation is applied on the query.<br/>
* If not specified, this parameter defaults to 5.
*/
partialMatchKeywords?: number;
/**
* The threshold to use for matching items when partial match is enabled.<br/>
* 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.<br/>
* If not specified, this parameter defaults to 50%.
*/
partialMatchThreshold?: string;
/**
* This is the 0-based index of the first result to return.<br/>
* If not specified, this parameter defaults to 0.
*/
firstResult?: number;
/**
* This is the number of results to return, starting from {@link IQuery.firstResult}.<br/>
* If not specified, this parameter defaults to 10.
*/
numberOfResults?: number;
/**
* Specifies the sort criterion(s) to use to sort results. If not specified, this parameter defaults to Relevancy.<br/>
* Possible values are : <br/>
* -- relevancy : This uses all the configured ranking weights as well as any specified ranking expressions to rank results.<br/>
* -- dateascending / datedescending : Sort using the value of the @date field, which is typically the last modification date of an item in the index.<br/>
* -- 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.<br/>
* -- nosort : Do not sort the results. The order in which items are returned is essentially random.<br/>
* -- @field ascending / @field descending : Sort using the value of a custom field.
*/
sortCriteria?: string;
sortField?: string;
/**
* Specifies a field on which {@link Folding} should be performed.<br/>
* 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.<br/>
* 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.
*/
filterField?: string;
/**
* Number of results that should be folded, using the {@link IQuery.filterField}
*/
filterFieldRange?: number;
/**
* Specifies an array of fields that should be returned for each result.<br/>
* eg: ['@foo','@bar']
*
*/
fieldsToInclude?: string[];
/**
* Specifies an array of fields that should be excluded from the query results.<br/>
* eg: ['@foo','@bar']
*
*/
fieldsToExclude?: string[];
/**
* Specifies the length (in number of characters) of the excerpts generated by the indexer based on the keywords present in the query.<br/>
* The index includes the top most interesting sentences (in the order they appear in the item) that fit in the specified number of characters.<br/>
* When not specified, the default value is 200.
*/
excerptLength?: number;
/**
* Specifies whether the first sentences of the item should be included in the results.<br/>
* 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.
*/
retrieveFirstSentences?: boolean;
/**
* This enables the query correction feature of the index.<br/>
* By activating this, the index returns an array of {link IQueryCorrection} with suggested word corrections.
*/
enableDidYouMean?: boolean;
/**
* Specifies an array of Query Function operation that will be executed on the results.
*/
queryFunctions?: IQueryFunction[];
/**
* Specifies an array of Ranking Function operations that will be executed on the result
*/
rankingFunctions?: IRankingFunction[];
/**
* Specifies an array of Group By operations that can be performed on the query results to extract facets
*/
groupBy?: IGroupByRequest[];
/**
* Specifies an array of request to retrieve facet values for the CategoryFacet component
*/
categoryFacets?: ICategoryFacetRequest[];
/**
* 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.
*/
debug?: boolean;
timezone?: string;
/**
* 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
*/
enableQuerySyntax?: boolean;
enableDuplicateFiltering?: boolean;
/**
* Whether the index should take collaborative rating in account when ranking result. See: {@link ResultRating}
*/
enableCollaborativeRating?: boolean;
/**
* Specifies the childField when doing parent-child loading (See: {@link Folding})
*/
childField?: string;
/**
* Specifies the parentField when doing parent-child loading (See: {@link Folding})
*/
parentField?: string;
/**
* The context is a map of key_value that can be used in the Query pipeline in the Coveo platform.<br/>
*/
context?: Context;
/**
* 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)
*/
actionsHistory?: string;
/**
* This is the id of the recommendation interface that generated the query.
*/
recommendation?: string;
/**
* 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 {@link IQuery.q} or {@link IQuery.lq} part of the query.
*
* This parameter is normally controlled by {@link SearchInterface.options.allowEmptyQuery} option.
*/
allowQueriesWithoutKeywords?: boolean;
/**
* Specifies an array of request to retrieve facet values for the DynamicFacet component.
*/
facets?: IFacetRequest[];
/**
* The global configuration options to apply to the requests in the [facets]{@link IQuery.facets} array.
*/
facetOptions?: IFacetOptions;
/**
* The user ID or visitor ID whose item views should be tagged in the query results
* (see the [isUserActionView]{@link IQueryResult.isUserActionView} property of the [IQueryResult]{@link IQueryResult} interface).
*
* **Examples:**
* - asmith@example.com
* - 6318b0c6-9397-4d70-b393-cf4770fd1bab
*/
userActions?: IUserActionsRequest;
/**
* The commerce request to execute.
*/
commerce?: ICommerceRequest;
/**
* The format of a successful response.
* If not specified, this parameter defaults to 'json'.
*/
format?: ResponseFormat;
}
}
declare module Coveo {
/**
* Describe the identity of a user on the Coveo platform
*/
interface IUserIdentity {
/**
* The name of the identity
*/
name: string;
/**
* The provider of the identity in the Coveo platform
*/
provider: string;
type: string;
}
}
declare module Coveo {
/**
* Describe a ranking expression performed against the index (qre)
*/
interface IRankingExpression {
/**
* The expression that was executed in the ranking expression
*/
expression: string;
/**
* The relevance modifier that was applied
*/
modifier: string;
}
}
declare module Coveo {
/**
* Describe an exception that was triggered by the index when performing the query.
*/
interface IQueryException {
/**
* The exception code
*/
code: string;
context: string;
}
}
declare module Coveo {
/**
* Describe a field value returned by index
*/
interface IIndexFieldValue {
/**
* The value
*/
value: string;
/**
* The optional lookupValue, if requested in the {@link IGroupByRequest}
*/
lookupValue?: string;
/**
* The number of results in the index which have this value
*/
numberOfResults: number;
/**
* The optional computedFieldResults, if requested in the {@link IGroupByRequest}
*/
computedFieldResults?: number[];
}
}
declare module Coveo {
/**
* Describe a single group by value, returned by a {@link IGroupByResult}
*/
interface IGroupByValue extends IIndexFieldValue {
/**
* The string value. Think : Facet label.
*/
value: string;
/**
* The lookup value if it was specified.
*/
lookupValue?: string;
/**
* The number of results that match this value in the index for this particular group by request
*/
numberOfResults: number;
/**
* The relevance score.
*/
score: number;
/**
* If there was ny computed field request, the results will be available here.
*/
computedFieldResults?: number[];
}
}
declare module Coveo {
/**
* A result for a {@link IGroupByRequest}.
*
* This is typically what the {@link Facet} component will use to render themselves.
*/
interface IGroupByResult {
/**
* The field on which the group by was performed.
*/
field: string;
/**
* The differents values for this result
*/
values: IGroupByValue[];
/**
* Available if there was any computed field request.
*/
globalComputedFieldResults?: number[];
}
}
declare module Coveo {
/**
* Describe correction for a query
*/
interface IQueryCorrection {
/**
* The query once corrected
*/
correctedQuery: string;
/**
* Array of correction for each word in the query
*/
wordCorrections: IWordCorrection[];
}
interface IWordCorrection {
/**
* Offset, from the beginning of the query
*/
offset: number;
/**
* Length of the correction
*/
length: number;
/**
* The original word that was corrected
*/
originalWord: string;
/**
* The new corrected word
*/
correctedWord: string;
}
}
declare module Coveo {
/**
* A trigger is an action that the interface will perform (show a message, execute a function, redirect users) depending on the query that was performed.<br/>
* A trigger that can be configured in the Coveo Query Pipeline.
*/
interface ITrigger<T> {
type: string;
content: T;
}
/**
* Notify (show a message) to a user
*/
interface ITriggerNotify extends ITrigger<string> {
}
/**
* Redirect the user to another url
*/
interface ITriggerRedirect extends ITrigger<string> {
}
/**
* Perform a new query with a different query expression
*/
interface ITriggerQuery extends ITrigger<string> {
}
/**
* Execute a javascript function present in the page.
*/
interface ITriggerExecute extends ITrigger<{
name: string;
params: any[];
}> {
}
}
declare module Coveo {
interface ICategoryFacetValue {
value: string;
numberOfResults: number;
}
}
declare module Coveo {
interface ICategoryFacetResult {
notImplemented?: boolean;
field: string;
values: ICategoryFacetValue[];
parentValues: ICategoryFacetValue[];
}
}
declare module Coveo {
/**
* A [values]{@link IFacetRequest.values} item in a Search API [facet response]{@link IFacetRequest}.
*/
interface IFacetResponseValue extends IRangeValue {
/**
* The facet value name.
*/
value?: string;
/**
* The facet value state to display in the search interface.
*/
state: FacetValueState;
/**
* The number of query result items matching the facet value.
*/
numberOfResults: number;
/**
* Whether additional values are available for the facet.
*/
moreValuesAvailable?: boolean;
/**
* The children of this hierarchical facet value.
*/
children?: IFacetResponseValue[];
/**
* When the hierarchical value has no children, this property is `true`.
*/
isLeafValue?: boolean;
}
/**
* An item in the response of a Search API [facet request]{@link IFacetRequest}.
*/
interface IFacetResponse {
/**
* The unique facet identifier in the search interface.
*/
facetId: string;
/**
* The name of the field on which the facet is based.
*/
field: string;
/**
* Whether additional values are available for the facet.
*/
moreValuesAvailable: boolean;
/**
* The returned facet values.
*
* See [IFacetResponseValue]{@link IFacetResponseValue}
*/
values: IFacetResponseValue[];
}
}
declare module Coveo {
interface IQuestionAnswerMeta {
documentId: {
contentIdKey: string;
contentIdValue: string;
};
score: number;
}
interface IRelatedQuestionAnswerResponse extends IQuestionAnswerMeta {
question: string;
answerSnippet: string;
}
interface IQuestionAnswerResponse extends IQuestionAnswerMeta {
question?: string;
answerSnippet?: string;
relatedQuestions: IRelatedQuestionAnswerResponse[];
}
}
declare module Coveo {
/**
* Describe a set a results returned by the Search API
*/
interface IQueryResults {
/**
* When an error occurs, and the errorsAsSuccess flag is passed, the error will be returned in the body of the response
*/
error?: {
/**
* The error message
*/
message: string;
/**
* The type of error
*/
type: string;
/**
* A detailed execution report sent by the Search API
*/
executionReport: any;
};
/**
* A detailed execution report sent by the Search API.<br/>
* Only sent if {@link IQuery.debug} is true
*/
executionReport?: any;
/**
* The basic expression that was executed.<br/>
* Only sent if {@link IQuery.debug} is true
*/
basicExpression?: string;
/**
* The advanced expression that was executed.<br/>
* Only sent if {@link IQuery.debug} is true
*/
advancedExpression?: string;
/**
* The constant expression that was executed.<br/>
* Only sent if {@link IQuery.debug} is true
*/
constantExpression?: string;
/**
* A list of user identities that were used to perform this query.<br/>
* Only sent if {@link IQuery.debug} is true
*/
userIdentities?: IUserIdentity[];
/**
* A list of ranking expression that were used to tweak the relevance.<br/>
* Only sent if {@link IQuery.debug} is true
*/
rankingExpressions?: IRankingExpression[];
/**
* The total number of results that matched the query in the index.
*/
totalCount: number;
/**
* The total number of results that matched the query in the index, but with the duplicate filtered.
*/
totalCountFiltered: number;
/**
* The total query duration, which is the sum of the `indexDuration` and `searchAPIDuration`, including any latency incurred through the necessary network hops.
*/
duration: number;
/**
* The part of the total query `duration` that was spent in the index.
*/
indexDuration: number;
/**
* The part of the total query `duration` that was spent in the Coveo Search API.
*/
searchAPIDuration: number;
/**
* The duration of the query on the proxy (not always applicable, can be optional)
*
* @deprecated Use duration, indexDuration and searchAPIDuration instead.
*/
proxyDuration?: number;
/**
* The duration of the query for the client.
*
* @deprecated Use searchAPIDuration instead.
*/
clientDuration: number;
/**
* A unique identifier for this query, used mainly for the {@link Analytics} service.
*/
searchUid?: string;
/**
* The pipeline that was used for this query.
*/
pipeline?: string;
/**
* The search api version that was used for this query.
*/
apiVersion?: number;
/**
* The split test run that was used for this query. (A/B tests feature of the Coveo Query Pipeline)
*/
splitTestRun?: string;
/**
* The exception that can be returned by the index if the query triggered an error
*/
exception?: IQueryException;
/**
* The results of the query
*/
results: IQueryResult[];
/**
* The group by results of the query
*/
groupByResults: IGroupByResult[];
/**
* Category facet results of the query
*/
categoryFacets: ICategoryFacetResult[];
/**
* Possible query corrections (eg : {@link DidYouMean})
*/
queryCorrections: IQueryCorrection[];
/**
* Terms to highlight (with stemming) in the results
*/
termsToHighlight: {
[originalTerm: string]: string[];
};
/**
* Phrases to highlight (with stemming) in the results
*/
phrasesToHighlight: {
[originalTerm: string]: string[];
};
/**
* The Coveo Query Pipeline triggers, if any were configured.
*/
triggers: ITrigger<any>[];
/**
* The keywords selected by Coveo Machine Learning Refined Query feature
*/
refinedKeywords?: string[];
_folded: boolean;
_reusedSearchUid?: boolean;
/**
* Facet results of the query
*/
facets?: IFacetResponse[];
questionAnswer?: IQuestionAnswerResponse;
}
}
declare module Coveo {
class JQueryUtils {
static getJQuery(): any;
static isInstanceOfJQuery(obj: Object): boolean;
static isInstanceOfJqueryEvent(obj: Object): boolean;
}
}
declare module Coveo {
type ValidResponsiveMode = 'auto' | 'small' | 'medium' | 'large';
/**
* This class serves as a way to get and set the different screen size breakpoints for the interface.
*
* By setting those, you can impact, amongst others, the {@link Facet}'s, {@link Tab}'s or the {@link ResultList}'s behaviour.
*
* For example, the {@link Facet} components of your interface will switch to a dropdown menu when the screen size reaches 800px or less.
*
* You could modify this value using `this` calls
*
* Normally, you would interact with this class using the instance bound to {@link SearchInterface.responsiveComponents}
*/
class ResponsiveComponents {
windoh: Window;
constructor(windoh?: Window);
/**
* Set the breakpoint for small screen size.
* @param width
*/
setSmallScreenWidth(width: number): void;
/**
* Set the breakpoint for medium screen size
* @param width
*/
setMediumScreenWidth(width: number): void;
setResponsiveMode(responsiveMode: ValidResponsiveMode): void;
/**
* Get the current breakpoint for small screen size.
*
* If it was not explicitly set by {@link ResponsiveComponents.setSmallScreenWidth}, the default value is `480`.
* @returns {number}
*/
getSmallScreenWidth(): number;
/**
* Get the current breakpoint for medium screen size.
*
* If it was not explicitly set by {@link ResponsiveComponents.setMediumScreenWidth}, the default value is `800`.
* @returns {number}
*/
getMediumScreenWidth(): number;
/** Return the current responsive mode.
* @returns {ValidResponsiveMode}
*/
getResponsiveMode(): ValidResponsiveMode;
/**
* Return true if the current screen size is smaller than the current breakpoint set for small screen width.
* @returns {boolean}
*/
isSmallScreenWidth(): boolean;
/**
* Return true if the current screen size is smaller than the current breakpoint set for medium screen width.
* @returns {boolean}
*/
isMediumScreenWidth(): boolean;
/**
* Return true if the current screen size is larger than the current breakpoint set for medium and small.
* @returns {boolean}
*/
isLargeScreenWidth(): boolean;
}
}
declare module Coveo {
class DeviceUtils {
static getDeviceName(userAgent?: string): string;
static isAndroid(): boolean;
static isIos(): boolean;
static isMobileDevice(): boolean;
/**
* @deprecated
*
* Use ResponsiveComponents.isSmallScreenWidth() instead
*/
static isSmallScreenWidth(): boolean;
}
}
declare module Coveo {
interface IOffset {
left: number;
top: number;
}
/**
* This is essentially a helper class for dom manipulation.<br/>
* This is intended to provide some basic functionality normally offered by jQuery.<br/>
* To minimize the multiple jQuery conflict we have while integrating in various system, we implemented the very small subset that the framework needs.<br/>
* See {@link $$}, which is a function that wraps this class constructor, for less verbose code.
*/
class Dom {
/**
* Whether to always register, remove, and trigger events using standard JavaScript rather than attempting to use jQuery first.
* @type boolean
*/
static useNativeJavaScriptEvents: boolean;
el: HTMLElement;
/**
* Create a new Dom object with the given HTMLElement
* @param el The HTMLElement to wrap in a Dom object
*/
constructor(el: HTMLElement);
/**
* Helper function to quickly create an HTMLElement
* @param type The type of the element (e.g. div, span)
* @param props The props (id, className, attributes) of the element<br/>
* Can be either specified in dashed-case strings ('my-attribute') or camelCased keys (myAttribute),
* the latter of which will automatically get replaced to dash-case.
* @param innerHTML The contents of the new HTMLElement, either in string form or as another HTMLElement
*/
static createElement(type: string, props?: Object, ...children: Array<string | HTMLElement | Dom>): HTMLElement;
/**
* Adds the element to the children of the current element
* @param element The element to append
* @returns {string}
*/
append(element: HTMLElement): void;
/**
* Get the css value of the specified property.<br/>
* @param property The property
* @returns {string}
*/
css(property: string): s