Grouping

A few things to remember when using Grouping: 1. Grouping does not support Curations. 2. Facets only show total results and not total number of groups. 3. Sorting and Paging require the experimental collapse flag to be set to true.


Grouped results based on shared fields.

The most relevant document will have a _group key.

The key includes all other documents that share an identical value within the grouped field.

Documents in the _group key will not appear anywhere else in the search response.

Grouping is available on text, number, and date fields.

field (required)
Field name to group results on.
size (optional)
Number of results to be included in the _group key of the returned document. Can be between 1 and 10. Defaults to 10.
sort (optional)
A JSON object containing the field name or _score as the key and the value as asc or desc. The default sort is by descending relevance.
collapse (optional)
Experimental. Provides Paging and Sorting support. The field you are grouping on must not have multiple values. Multiple values will cause an error.

Example - Searching for "california" and grouping on states.

curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "parks",
  "result_fields": {
    "title": {
      "raw": {}
    },
    "location": {
      "raw": {}
    },
    "states": {
      "raw": {}
    }
  },
  "group": {
    "field": "states"
  }
}'

Example Response

{
  "meta": {
      ## Truncated!
    },
    "request_id": "feff7cf2359a6f6da84586969ef0ca89"
  },
  "results": [
    {
      "states": {
        "raw": [
          "California"
        ]
      },
      "title": {
        "raw": "Redwood"
      },
      "location": {
        "raw": "41.3,-124"
      },
      "id": {
        "raw": "park_redwood"
      },
      "_meta": {
        "score": 3.6536791
      },
      "_group": [
        {
          "states": {
            "raw": [
              "California"
            ]
          },
          "title": {
            "raw": "Sequoia"
          },
          "location": {
            "raw": "36.43,-118.68"
          },
          "id": {
            "raw": "park_sequoia"
          },
          "_meta": {
            "score": 0.7559763
          }
        },
        {
          "states": {
            "raw": [
              "California"
            ]
          },
          "title": {
            "raw": "Lassen Volcanic"
          },
          "location": {
            "raw": "40.49,-121.51"
          },
          "id": {
            "raw": "park_lassen-volcanic"
          },
          "_meta": {
            "score": 0.65168744
          }
        },
        {
          "states": {
            "raw": [
              "California"
            ]
          },
          "title": {
            "raw": "Kings Canyon"
          },
          "location": {
            "raw": "36.8,-118.55"
          },
          "id": {
            "raw": "park_kings-canyon"
          },
          "_meta": {
            "score": 0.5489506
          }
        },
        {
          "states": {
            "raw": [
              "California"
            ]
          },
          "title": {
            "raw": "Pinnacles"
          },
          "location": {
            "raw": "36.48,-121.16"
          },
          "id": {
            "raw": "park_pinnacles"
          },
          "_meta": {
            "score": 0.49142775
          }
        },
        {
          "states": {
            "raw": [
              "California",
              "Nevada"
            ]
          },
          "title": {
            "raw": "Death Valley"
          },
          "location": {
            "raw": "36.24,-116.82"
          },
          "id": {
            "raw": "park_death-valley"
          },
          "_meta": {
            "score": 0.4451992
          }
        },
        {
          "states": {
            "raw": [
              "California"
            ]
          },
          "title": {
            "raw": "Channel Islands"
          },
          "location": {
            "raw": "34.01,-119.42"
          },
          "id": {
            "raw": "park_channel-islands"
          },
          "_meta": {
            "score": 0.12520474
          }
        },
        {
          "states": {
            "raw": [
              "California"
            ]
          },
          "title": {
            "raw": "Yosemite"
          },
          "location": {
            "raw": "37.83,-119.5"
          },
          "id": {
            "raw": "park_yosemite"
          },
          "_meta": {
            "score": 0.10190857
          }
        }
      ],
      "_group_key": "California"
    },
    ## Truncated!
  ]
}