Coveo Search RestGroupBy

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/coveo/main/json-schema/coveo-search-restgroupby-schema.json",
  "title": "Coveo Search RestGroupBy",
  "required": [
    "field"
  ],
  "type": "object",
  "properties": {
    "field": {
      "type": "string",
      "description": "The name of the field on which to perform the Group By operation. The operation returns a Group By value for each distinct value of this field found in the query result items.\n\n**Note:** You must ensure that the **Facet** option is enabled for this field in your index (see [Manage fields](https://docs.coveo.com/en/1833/)).",
      "example": "@author"
    },
    "allowedValues": {
      "type": "array",
      "description": "The field values allowed in the Group By operation results. You can use trailing wildcards (`*`) to include ranges of values.\n\nSee also the `completeFacetWithStandardValues` Group By operation parameter.\n\nIf you do not explicitly specify an array of `allowedValues`, or if you specify an empty array, all field values are allowed.\n\n**Example:**\n```\n[\n  \"Anonymous\",\n  \"Bob Jones\",\n  \"Carrie Green\",\n  \"David Allen\"\n]\n```",
      "example": [
        "Anonymous",
        "Bob Jones",
        "Carrie Green",
        "David Allen"
      ],
      "items": {
        "type": "string"
      }
    },
    "allowedValuesPatternType": {
      "type": "string",
      "description": "The type of pattern being used in the allowed field values.\n\nSee also the `allowedValues` Group By operation parameter.\n\nIf you do not explicitly specify a pattern type, the legacy pattern is used by default, which only support trailing wildcards.",
      "example": "wildcards",
      "enum": [
        "legacy",
        "wildcards",
        "regex",
        "editdistance",
        "phonetic"
      ]
    },
    "maximumNumberOfValues": {
      "type": "integer",
      "description": "The maximum number of values the Group By operation should return.\n\n**Default:** `10`",
      "format": "int32",
      "example": 5,
      "default": 10,
      "minimum": 0
    },
    "completeFacetWithStandardValues": {
      "type": "boolean",
      "description": "Whether to complete the Group By operation result set with standard values.\n\nIf you set this parameter to `true` and the number of specified `allowedValues` is lower than the `maximumNumberOfValues`, the Group By operation also attempts to returns standard values until the result set contains the `maximumNumberOfValues`.\n\n**Default:** `false`",
      "example": true,
      "default": false
    },
    "injectionDepth": {
      "type": "integer",
      "description": "The maximum number of query result items to scan for Group By values.\n\n**Note:** Specifying a high `injectionDepth` value can negatively impact query performance.\n\n**Default:** `1000`",
      "format": "int32",
      "example": 1500,
      "default": 1000
    },
    "rangeValues": {
      "type": "array",
      "description": "The ranges for which to generate Group By values.\n\n**Notes:**\n\n- Specifying `rangeValues` only makes sense when the Group By `field` references a numeric or date field in the index.\n- You can set the `generateAutomaticRanges` Group By parameter to `true` rather than explicitly specifying `rangeValues` (unless the Group By `field` was generated by a query function).",
      "example": [],
      "items": {
        "required": [
          "end",
          "start"
        ],
        "type": "object",
        "properties": {
          "start": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "integer"
              }
            ]
          },
          "end": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "integer"
              }
            ]
          },
          "label": {
            "type": "string",
            "description": "The label to associate with the range.\n\n**Note:** Not currently leveraged.\n\n**Examples:**\n- `0 - 100`\n- `In 2019`",
            "example": "0 - 100"
          },
          "endInclusive": {
            "type": "boolean",
            "description": "Whether to include the `end` value in the range.\n\n**Default:** `false`",
            "example": true,
            "default": false
          }
        }
      }
    },
    "generateAutomaticRanges": {
      "type": "boolean",
      "description": "Whether the index should automatically create range values.\n\n**Tip:** If you set this parameter to `true`, you should ensure that the **Use cache for numeric queries** option is enabled for the Group By `field` in your index in order to speed up automatic range evaluation (see [Manage fields](https://docs.coveo.com/en/1833/)).\n\n**Notes:**\n\n- Setting `generateAutomaticRanges` to `true` only makes sense when the Group By `field` references a numeric or date field in the index.\n- The index cannot automatically generate range values of a field generated by a query function. In such cases, you must rather use the `rangeValues` Group By parameter.\n- Automatic range generation will fail if the referenced `field` is dynamically generated by a query function.\n\n**Default:** `false`",
      "example": false,
      "default": false
    },
    "sortCriteria": {
      "type": "string",
      "description": "The criterion to use when sorting the Group By operation results.\n\n**Allowed values:**\n\n- `score`: sort using the score value which is computed from the number of occurrences of a field value, and also from the position where query result items with this field value appear in the ranked query 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 field value tend to appear higher in the ranked query result set.\n- `occurrences`: sort by number of occurrences, with field values having the highest number of occurrences appearing first.\n- `alphaAscending`/`alphaDescending`: sort field values alphabetically.\n- `alphaAscendingNatural`/`alphaDescendingNatural`: sort field values alphabetically using [natural sorting](https://en.wikipedia.org/wiki/Natural_sort_order).\n- `computedFieldAscending`/`computedFieldDescending`: sort on the value of the first computed field for each Group By operation result (see the `ComputedFields` Group By parameter).\n- `chiSquare`: sort based on the relative frequency of field values in the query result set compared to their frequency in the entire index. This means that a field value that does not appear often in the index, but does appear often in the query result set will tend to appear higher.\n- `noSort`: do not sort the results of the Group By operation. The field values will be appear in a random order.\n\n**Default:** `score`",
      "example": "ComputedFieldDescending",
      "default": "score"
    },
    "computedFields": {
      "type": "array",
      "description": "The computed fields to evaluate for each Group By value.\n\nA computed field stores the result of an aggregate operation performed on the values of a specific numerical field for all the query result items that share the same Group By `field` value.",
      "items": {
        "required": [
          "field",
          "operation"
        ],
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "The name of the numeric field on which to perform the aggregate operation.\n\n**Tip:** You should ensure that the **Use cache for computed fields** option is enabled for that field in your index in order to speed up evaluation (see [Manage fields](https://docs.coveo.com/en/1833/)).",
            "example": "@wordcount"
          },
          "operation": {
            "type": "string",
            "description": "The aggregate operation to perform on the `field` values.\n\n**Allowed values:**\n\n- `sum`: get the sum of all values.\n- `average`: get the average of all values.\n- `minimum`: get the smallest value.\n- `maximum`: get the largest value.",
            "example": "average",
            "enum": [
              "sum",
              "average",
              "minimum",
              "maximum"
            ]
          }
        }
      }
    },
    "queryOverride": {
      "type": "string",
      "description": "The query expression that should override the basic query expression on which the Group By operation is being performed (see the `q` query parameter).\n\n**Note:** If _any_ query override parameter (e.g., `queryOverride`, `advancedQueryOverride`, etc.) is set in a Group By operation, **all** original parts of the query expression (i.e., `q`, `aq`, `cq`, and `dq`) will be ignored.",
      "example": "Coveo Cloud V2 platform"
    },
    "advancedQueryOverride": {
      "type": "string",
      "description": "The query expression that should override the advanced query expression on which the Group By operation is being performed (see the `aq` query parameter).\n\n**Note:** If _any_ query override parameter (e.g., `queryOverride`, `advancedQueryOverride`, etc.) is set in a Group By operation, **all** original parts of the query expression (i.e., `q`, `aq`, `cq`, and `dq`) will be ignored.",
      "example": "@year==2017"
    },
    "constantQueryOverride": {
      "type": "string",
      "description": "The query expression that should override the constant query expression on which the Group By operation is being performed (see the `cq` query parameter).\n\n**Note:** If _any_ query override parameter (e.g., `queryOverride`, `advancedQueryOverride`, etc.) is set in a Group By operation, **all** original parts of the query expression (i.e., `q`, `aq`, `cq`, and `dq`) will be ignored.",
      "example": "@filetype==forumpost"
    },
    "disjunctionQueryOverride": {
      "type": "string",
      "description": "The query expression that should override the disjuntion query expression on which the Group By operation is being performed (see the `dq` query parameter).\n\n**Note:** If _any_ query override parameter (e.g., `queryOverride`, `advancedQueryOverride`, etc.) is set in a Group By operation, **all** original parts of the query expression (i.e., `q`, `aq`, `cq`, and `dq`) will be ignored.",
      "example": "@date=2016-12-01..2016-12-31"
    },
    "lookupField": {
      "type": "string",
      "description": "This property is exposed for backward compatibility reasons. The issues this property was used as a workaround for do not exist in the Coveo Cloud V2 platform.\n\nThe name of an additional field whose value must be retrieved.",
      "deprecated": true
    },
    "thoroughLookup": {
      "type": "boolean",
      "description": "This parameter is exposed for backward compatibility reasons. The issues this parameter was used as a workaround for do not exist in the Coveo Cloud V2 platform.\n\nWhether to scan for lookup values.",
      "default": false,
      "deprecated": true
    },
    "filterFacetCount": {
      "type": "boolean",
      "description": "Whether to exclude folded result parents when estimating the result count for each facet value.\n\n**Note:** The target folding field must be a facet field with the **Use cache for nested queries** options enabled (see [Manage fields](https://docs.coveo.com/en/1833/)).\n\n**Default:** `true`",
      "default": true
    }
  }
}