Merge 649cc82 into 346cca1

src/rest/GroupByRequest.ts

@@ -2,67 +2,113 @@ import { IComputedFieldRequest } from './ComputedFieldRequest';
 import { IRangeValue } from './RangeValue';
 
 /**
- * Describe a group by request to perform against the index.<br/>
- * See : https://developers.coveo.com/display/SearchREST/Group+By+Parameters
+ * The `IGroupByRequest` interface describes a Group By operation to perform against the index.
+ *
+ * See [Group By Parameters](https://developers.coveo.com/x/jQEv).
  */
 export interface IGroupByRequest {
+
   /**
-   * This specifies the field on which the Group By operation is performed. The Group By will return a Group By value for each distinct value of this field within the result set.
+   * 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;
+
   /**
-   * This specifies how the Group By values should be sorted by the indexer. If not specified, the default value is Score.<br/>
-   * Possible values are :<br/>
-   * -- score : the score is computed from the number of occurrences as well as from the position in the result set where the items having this value are appearing. Using this criterion, an item with 100 occurrences might appear after one with only 10 occurrences if those occurrences tend to appear sooner in the ranked result set.<br/>
-   * -- occurrences : Sort by number of occurrences, with values having the highest number appearing first. <br/>
-   * -- alphaascending / alphadescending : Sort alphabetically on the field values. <br/>
-   * -- computedfieldascending / computedfielddescending : Sort on the values of the first computed field for each Group By value. <br/>
-   * -- chisquare : Sort based on the relative frequency of values in the result set compared to the frequency in the whole index. This means that a value that doesn't appear often in the index but does appear often in the result set will tend to appear higher in the list.<br/>
-   * -- nosort : Do not sort the Group By values. The values will be returned in a random order.
+   * 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 Field Parameters](https://developers.coveo.com/x/jwEv)).
+   * - `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;
+
   /**
-   * This specifies the maximum number of values that the Group By operation will return.<br/>
-   * If not specified, the default value is 10.
+   * Specifies the maximum number of values that the Group By operation can return.
+   *
+   * Default value is `10`. Minimum value is `0`.
    */
   maximumNumberOfValues?: number;
+
   /**
-   * This specifies how deep the index will scan the results to identify missing Group By values.<br/>
-   * If not specified, the default value is 1000.<br/>
-   * When executing a Group By operation, the index uses various heuristics to list all the values that are appearing in the result set. In some corner cases, some values might be omitted (it's a classical trade-off of precision vs performance). Using injection means that the index will explicitly scan the field values of the top n results of the query, and ensure that the values present in those results are included. Using higher values for this parameter may impact query performance.
-   */
+   * 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 `0`.
+   * */
   injectionDepth?: number;
+
   /**
-   * This specifies a different query expression on which to compute the Group By operation.<br/>
-   * By default, the query expression being executed is used.<br/>
-   * 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.
+   * 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;
+
   /**
-   * This specifies a constant query expression on which to compute the Group By operation.<br/>
-   * By default, the constant part of the query expression being executed is used.<br/>
-   * This feature is much like the normal queryOverride except that the index will keep the query expression in cache for faster queries. Do no put dynamic query expression in this parameter, as it will negatively impact the performance.
+   * 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;
+
   /**
-   * This explicitly specifies a list of values for which Group By values should be generated.<br/>
-   * Trailing wildcards can be used to include ranges of values.<br/>
-   * eg : The array ["foo", "bar*"] would return Group By values for foo and any value starting with bar.
+   * 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[];
+
   /**
-   * This specifies an array of computed fields that should be computed for each Group By value that is returned.<br/>
-   * 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
+   * 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 Field Parameters](https://developers.coveo.com/x/jwEv).
    */
   computedFields?: IComputedFieldRequest[];
+
   /**
-   * This explicitly specifies a list of range values for which Group By values should be generated.
+   * Explicitly specifies a list of range values for which Group By values should be generated.
    */
   rangeValues?: IRangeValue[];
+
   /**
-   * By setting the parameter generateAutomaticRanges to true, the ranges will be calculated by the Coveo index.
+   * Specifies whether to let the index calculate the ranges.
+   *
+   * Default value is `false`.
    */
   generateAutomaticRanges?: boolean;
   completeFacetWithStandardValues?: boolean;