Groups

A group searches several lists at once. One query fans out to every member list, and the matches come back merged into a single ranked set — so you can put products, articles and FAQs, each in its own list with its own fields, behind one search box. Think of it as a virtual list stitched together from real ones: you never add records to a group, only to the lists inside it.

The classic example is a movie site that keeps movies, actors and directors in separate lists but wants one search box to return all three. A group does exactly that, and every result carries a list_name so your page knows which template to draw.

Auto-plays · use Back / Next to step through at your own pace.

Create a group and add lists

1. Go to Groups → Create Group. Name it, and pick the subscription that will host it and (optionally) the embedding model it searches under.
2. Open the group’s menu and choose Add List. Pick a list and pin a version — the group searches exactly that version until you decide to move it forward.
3. Add as many lists as you need. A group’s members must share its subscription and embedding model; the picker only offers lists that fit, and an empty group adopts the first list you add.

How merging works

• The query runs against every member list in parallel.
• Results are merged into one ranked set — relevance is comparable across lists, so the best matches rise to the top regardless of which list they came from.
• Each member is pinned to a specific list version, chosen when you add it.
• A group is read-only: records are always written to the underlying lists, never to the group.

Version pins, and updating on your schedule

Pinning a version is what makes a group predictable. A member list can be edited, re-indexed and version-bumped without touching your group’s results — the group keeps searching the pinned version. When a member has a newer version, the group’s row shows an amber Update available badge; until then it reads Latest. You click Update to Latest when you are ready, which bumps the group’s own version — and because group versions are themselves restorable, you can roll back if an update regresses. The Versioning page covers the full pin-and-migrate story.

Querying a group

A group is queried exactly like a list — the URL mirrors a list’s, with the group’s membership version in the path (the full set of search options is on the Searching page):

https://api.searchstack.dev/search/group/{ account }/{ group }/{ version }
https://api.searchstack.dev/suggest/group/{ account }/{ group }/{ version }/{ query }

(Suggestions carry the typed text as a final path segment; search takes its query as an option.)

A search for matrix against a movies-and-cast group returns records from both lists, told apart by list_name:

{
  "results": [
    { "name": "the-matrix",   "list_name": "movies", "fields": { "title": "The Matrix", "year": 1999 } },
    { "name": "keanu-reeves", "list_name": "actors", "fields": { "known_for": "The Matrix" } }
  ],
  "count": 2,
  "total_count": 2
}

Render a different template per list_name — the autocomplete component supports this out of the box through its template function.

When to use a group

• One search box over different kinds of data (products + articles + FAQs).
• Combining regional lists into one global search.
• Any place a single query should reach records that live in more than one list.

A worked example

A store keeps products, guides and faqs as three lists, each with fields that suit it. You create a store-search group on your subscription, add all three, and pin each to its current version. Your one search box now queries the group: a shopper typing “waterproof jacket” gets matching products, a how-to guide and a returns FAQ in one ranked list, each rendered with its own card because your front-end switches on list_name. Later you re-import the product catalogue — the group keeps serving the pinned version, showing Update available until you click to move it forward. One search box, three schemas, no surprises.