Loading...
searchstack.dev
Sign In

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.
1

A group searches several lists at once

One query fans out to every member list and comes back as a single ranked result set — the way to put products, articles and FAQs behind one search box. Start under Groups → Create Group: name it, and pick the subscription and (optionally) the embedding model the group searches under.

The Create Group dialog with name, subscription and embedding-model fields
2

Add member lists, pinned to a version

For each member you pick a List and pin a version — the group searches exactly that version until you choose to update it, so a list changing underneath never surprises your search. A group is read-only: records are always added to the underlying lists, never to the group.

Adding a member list to a group and pinning its version
3

Search them all — update on your schedule

The group shows its members as version-pinned badges (QA-smoke-live v1) and a Latest tag when every member is on its newest version — it turns amber to Update available when one falls behind. Query the group over the API like a single list; each result carries a list_name so your page renders the right template per source.

A group showing its member lists as version-pinned badges
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.
The Create Group dialog showing Group Name, Subscription and Model The Add List to Group dialog showing a List selector and a pinned Version selector
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.
The Groups table: one group with its subscription, model, reranker, created date, version with a Latest badge, and a chip naming each member list and the version it is pinned to
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 }

(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.
Top