Groups

A group searches several lists at once, merging the matches into one ranked set — products, articles and FAQs, each with its own fields, behind a single search box.

• A list made up of other lists.
• Every result carries a list_name, so your page knows what kind of result it is and how to display it.

Create a group and add lists

1. Groups → Create Group. Name it and pick the subscription that hosts 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 move it forward.
3. Add as many lists as you need. Members must share the group’s subscription and embedding model; the picker only offers lists that fit, and an empty group takes both from the first list you add.

Swapping lists in and out

Replace Lists sets the whole membership at once, instead of adding and removing one list at a time.

• Use it whenever you swap one list for another. Remove-then-add leaves the group searching a half-finished set in between, and moves the group on a version for each step.
• The dialog shows the members you have now. Change a list, change a pin, drop a row, add a row — then save. Everything applies together and the group moves on one version.
• Over the API the body is the membership you want, not a list of changes: members you leave out are removed. Sending the membership already in place changes nothing.

How merging works

• The search runs against every list in the group at the same time.
• Results are merged into one ranked set; relevance scores compare across lists, so the best matches rise to the top whichever list they came from.
• A group is read-only: records are always written to the lists inside it, never to the group.

The same record in two lists

A group often holds two lists over the same catalogue — one you maintain by hand, one synced from a feed. When both hold the same record, the result is returned once.

• The copy that survives is from the list with no feed connected. The one a person maintains beats the one a sync replaces.
• Two unconnected lists tie, and the first list in the group wins.
• Both lists must have an id column. Records are matched on the value of that column, so the two lists may name it differently (sku in one, product_id in the other) — only the values have to agree. A list keyed by record name states no identity, and is never collapsed: a shared name is not evidence of a shared record. Set the id column when you import.
• total_count is the number of matches before this happens, so it can read higher than the results you get. Counting the collapsed total means walking every match, which a page of results does not do.
• Filter counts are also pre-collapse, for the same reason.

Version pins, and updating on your schedule

• A list can be edited, re-indexed and moved to a new version without touching the group’s results: it carries on searching the pinned version.
• The group’s row reads Latest until a list has a newer version, then shows an amber Update available badge.
• Update to Latest moves the group on to its next version, when you are ready. Group versions can be restored, so you can go back.
• Pinning in full: Versioning.

Querying a group

Same shape as a list’s address, with the group’s membership version in the path (all search options are on the Searching page):

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

Put latest in the { version } segment to always query the group’s current members: the address then survives every membership change, a list swap included. Works on search, suggest, ask and facet values. A number pins that membership version instead.

(For suggestions, the typed text goes at the end of the address; 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", "as_of": "2026-07-19T14:32:00Z", "fields": { "title": "The Matrix", "year": 1999 } },
    { "name": "keanu-reeves", "list_name": "actors", "fields": { "known_for": "The Matrix" } }
  ],
  "count": 2,
  "total_count": 2
}

• Show a different layout for each list_name. The autocomplete component does this through its template function.
• Group search takes exactly the same options as a list search, listed in the API reference under Search and Suggest.

Filter menus over a group

A group filters on facet names, the same way select and filter do — so one menu can cover every list in it:

https://api.searchstack.dev/facet/group/{ account }/{ group }/{ version }/{ facet }

• Values from every member, merged as a set. NN1 in two lists is one entry.
• A member without a facet of that name is skipped, not an error — members whose fields differ is the normal case.
• lists says how many members actually carry it. Read it: a menu drawn from one member of four filters away most of the group.
• truncated means some member held values back. Narrow with ?prefix= rather than asking for a bigger page.

When to use a group

• One search box over different kinds of data (products + articles + FAQs).
• Combining regional lists into one global search.