Interface IGroupByRequest

The IGroupByRequest interface describes a Group By operation to perform against the index.

See Group By Operations.



Optional allowedValues

allowedValues: string[]

Explicitly specifies a list of values for which to generate Group By values.

You can use trailing wildcards to include ranges of values.


The array ["foo", "bar*"] would return Group By values for foo and any value starting with bar.

Optional allowedValuesPatternType

allowedValuesPatternType: AllowedValuesPatternType

The pattern type to use for the IGroupByRequest.allowedValues property (see AllowedValuesPatternType).

This option is empty by default, which makes it behave as legacy.

Optional computedFields

computedFields: IComputedFieldRequest[]

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.

Optional constantQueryOverride

constantQueryOverride: string

Specifies a constant query expression on which to compute the Group By operation.

This feature is similar to the 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.


field: string

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.

Optional generateAutomaticRanges

generateAutomaticRanges: boolean

Specifies whether to let the index calculate the ranges.

Default value is false.

Optional injectionDepth

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

Optional maximumNumberOfValues

maximumNumberOfValues: number

Specifies the maximum number of values that the Group By operation can return.

Default value is 10. Minimum value is 0.

Optional queryOverride

queryOverride: string

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.

Optional rangeValues

rangeValues: IRangeValue[]

Explicitly specifies a list of range values for which Group By values should be generated.

Optional sortCriteria

sortCriteria: 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).
  • 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.


  • IGroupByRequest