search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso

Grouping

Results can be grouped based on a field if they share the exact same field. The most relevant document will have a key of _group which includes an array of other documents that share an identical value within the grouped field. Documents that share a location, version, rating, and so on, will become one result. The most relevant result will be the parent.

Documents in a _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.
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!
  ]
}

Example - Searching for "california" and grouping on states.
import com.swiftype.appsearch.Client;
import com.swiftype.appsearch.ClientException;
import java.util.*;

Client client = new Client("host-2376rb", "search-soaewu2ye6uc45dr8mcd54v8");

String engineName = "national-parks-demo"; String query = "parks";

Map<String, Object> make = new HashMap<>(); title.put("raw", Collections.emptyMap()); Map<String, Object> model = new HashMap<>(); location.put("raw", Collections.emptyMap()); Map<String, Object> year = new HashMap<>(); states.put("raw", Collections.emptyMap());

Map<String, Object> resultFields = new HashMap<>(); resultFields.put("title", title); resultFields.put("location", location); resultFields.put("states", states);

Map<String, Object> group = new HashMap<>(); group.put("field", "states");

Map<String, Object> options = new HashMap<>(); options.put("result_fields", resultFields); options.put("group", group);

try { Map<String, Object> response = client.search(engineName, query, options); System.out.println(response); } catch (ClientException e) { System.out.println(e); }

Example Response
Map<String, Object>: {
  "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!
  ]
}

Example - Searching for "california" and grouping on states.
const SwiftypeAppSearchClient = require('swiftype-app-search-node')

const client = new SwiftypeAppSearchClient('host-2376rb', 'search-soaewu2ye6uc45dr8mcd54v8')

const engineName = 'national-parks-demo' const query = 'parks'

const options = { result_fields: { states: { raw: {} }, states: { raw: {} }, states: { raw: {} } }, group: { field: 'states' } }

client .search(engineName, query, options) .then(response => console.log(response)) .catch(error => console.log(error))

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!
  ]
}

Example - Searching for "california" and grouping on states.
host_identifier = 'host-2376rb'
api_key = 'search-soaewu2ye6uc45dr8mcd54v8'
client = SwiftypeAppSearch::Client.new(host_identifier: host_identifier, api_key: api_key)

engine_name = 'national-parks-demo' query = 'parks'

options = { result_fields: { title: { raw: {} }, location: { raw: {} }, states: { raw: {} } }, group: { field: 'states' } }

begin puts client.search(engine_name, query, options) rescue SwiftypeAppSearch::ClientException => e puts e end

Example Response
{
  "meta" => {
    "warnings" => [], "page" => {
      "current" => 1, "total_pages" => 3, "total_results" => 25, "size" => 10
    }, "request_id" => "719bbf02bcf72aa66241e046ddd3a28b"
  }, "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!
}]

Example - Searching for "california" and grouping on states.
from swiftype_app_search import Client
from swiftype_app_search.exceptions import SwiftypeAppSearchError

host_identifier = 'host-2376rb' api_key = 'search-soaewu2ye6uc45dr8mcd54v8' client = Client(host_identifier, api_key)

engine_name = 'national-parks-demo' query = 'parks'

options = { 'result_fields': { 'title': { 'raw': {} }, 'location': { 'raw': {} }, 'states': { 'raw': {} } }, 'group': { 'field': 'states' } }

try: print(client.search(engine_name, query, options)) except SwiftypeAppSearchError as e: print(e)

Example Response
{
    'meta': {
        ## Truncated!
    },
    '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': '33.79,-115.9'
                    },
                    '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': '33.79,-115.9'
                    },
                    'id': {
                        'raw': 'park_pinnacles'
                    },
                    '_meta': {
                        'score': 5.2469006
                    }
                },
                {
                    'states': {
                        'raw': [
                          'California'
                        ]
                    },
                    'title': {
                        'raw': 'Redwood'
                    },
                    'location': {
                        'raw': '41.3,-124'
                    },
                    'id': {
                        'raw': 'park_redwood'
                    },
                    '_meta': {
                        'score': 5.2469006
                    }
                },
                {
                    'states': {
                        'raw': [
                          'California'
                        ]
                    },
                    'title': {
                        'raw': 'Sequoia'
                    },
                    'location': {
                        'raw': '36.43,-118.68'
                    },
                    'id': {
                        'raw': 'park_sequoia'
                    },
                    '_meta': {
                        'score': 5.2469006
                    }
                },
                {
                    'states': {
                        'raw': [
                          'California'
                        ]
                    },
                    'title': {
                        'raw': 'Yosemite'
                    },
                    'location': {
                        'raw': '37.83,-119.5'
                    },
                    'id': {
                        'raw': 'park_yosemite'
                    },
                    '_meta': {
                        'score': 5.2469006
                    }
                },
                {
                    'states': {
                        'raw': [
                          'California'
                        ]
                    },
                    'title': {
                        'raw': 'Death Valley'
                    },
                    'location': {
                        'raw': '36.24,-116.82'
                    },
                    'id': {
                        'raw': 'park_death-valley
                    },
                    '_meta': {
                        'score': 5.2469006
                    }
                }
            ],
            "_group_key": "California"
        },
        ## Truncated!
    ]
}

Example - Searching for "california" and grouping on states.
const client = SwiftypeAppSearch.createClient({
  hostIdentifier: 'host-2376rb',
  searchKey: 'search-soaewu2ye6uc45dr8mcd54v8',
  engineName: 'national-parks-demo'
})

const query = 'parks'

const options = { result_fields: { title: { raw: {} }, location: { raw: {} }, states: { raw: {} } }, group: { field: 'states' } }

client .search(query, options) .then(function(response){ console.log(response) }) .catch(function(error){ console.log(error) })

Example Response
ResultList {
  "rawResults": [
    {
      ## Truncated! Same as ResultItem.data.
    },
    {
      ## Truncated! Same as ResultItem.data.
    }
  ],
  "rawInfo": {
    "meta": {
      ## Truncated!
    }
  },
  "results": [
    ResultItem {
      "data": {
        "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"
      }
    },
    ResultItem {
      "data": {
        "states": {
          "raw": [
            "California",
            "Nevada"
          ]
        },
        "title": {
          "raw": "Death Valley"
        },
        "location": {
          "raw": "36.24,-116.82"
        },
        "id": {
          "raw": "park_death-valley"
        },
        "_meta": {
          "score": 3.3266773
        },
        "_group": []
      }
    }
  ],
  "info": {
    "meta": {
      ## Truncated!
    }
  }
}


Stuck? Looking for help? Contact support or check out the App Search forum!