Loading...
searchstack.dev
Sign In

Synonyms

A synonym teaches a list that two words mean the same thing. Your customers say “lorry”; your catalogue says “truck”. Without a synonym that search finds nothing at all — the records are right there, and the word is simply not one they contain.

Synonyms are applied to the search, not to your records. A change takes effect on the very next search, and nothing is rebuilt or reindexed.

Where they live

Open a list, then Options → Synonyms. They used to sit on the Settings dialog; they do not any more, because a synonym set is a set of rules you author rather than a dial you set, and rules need a table.

The two kinds of rule
  • Mean the same thing — every word finds the same results as every other, in both directions. Use it when the words are interchangeable: sofa, couch, settee.
  • Search one word as another — searching the first word finds the second, one way only. Use it when one word is what customers say and the other is what your data says: lorry → truck.

The direction is the thing people most often get wrong, and it is why they are two separate choices rather than one box with an arrow in it. “Mean the same thing” is symmetric: adding tee and t-shirt means a search for either finds records containing either. “Search one word as another” is not: lorry → truck makes lorry behave like truck, but a search for truck is unaffected.

You do not write rule syntax

Each rule is a row: a kind, and one or two boxes of words. Type a word and press enter, or pick one from the list — the boxes offer the terms your own customers have been searching for, split into two groups:

  • Found nothing — searches that came back empty. These are your missing synonyms, written by your customers, and they belong on the left of a rewrite.
  • People search for — searches that worked. These are the words your catalogue answers to, and they belong on the right: rewriting to a word your data does not contain turns one empty search into a different empty search.

A word can be a phrase — t shirt works, and is matched across both words. It cannot contain a comma, an arrow, a # or a backslash, because those mean something to the rules themselves, so each word goes in its own box.

Let us work them out

The Suggest synonyms button reads the searches on this list that came back empty, alongside the ones that worked, and proposes rules that would have found something. Each suggestion arrives with the evidence for it — “14 people searched for lorry and found nothing, and truck is a word your catalogue answers to” — so you can judge it rather than take it on trust.

Suggestions are candidates. They land in the table as ordinary editable rows, and nothing is saved until you press Save. Add them one at a time, add them all, or discard them.

If nothing on your list has been coming back empty there is nothing to work from, and the button says so rather than guessing. “No synonyms needed” is a common and correct answer.

This runs on Search Stack’s own AI allowance, so it needs no model credentials of your own. If the weekly allowance runs out the panel says so and the table carries on working by hand.

Which engines honour them

Synonyms are applied at query time on the Search Stack engine, which is what makes them a per-list setting: the rules travel with each search rather than being baked into an index, so two lists sharing one index can hold entirely different rules.

A list on a bring-your-own Azure AI Search, Elasticsearch, OpenSearch or PostgreSQL service ignores synonyms, because those engines bind synonyms into index or server configuration — where they could not be scoped to one list, or even to one account.

Synonyms are not spelling correction

A misspelling is handled by typo tolerance, on the list’s Settings dialog, and it needs no rules at all. Reach for a synonym only when the two words are genuinely different words.

Over the API

Synonyms have their own endpoint rather than riding on a list update, and it takes structured rules rather than rule text — the syntax is not something a caller should have to get right either, and a malformed rule does not error, it silently stops working.

PUT /list/synonyms/{account-name}/{list-name}

{
  "rules": [
    { "kind": "equivalent", "terms": ["tee", "t-shirt", "tshirt"] },
    { "kind": "rewrite", "terms": ["lorry"], "replace_with": ["truck"] }
  ]
}

The call replaces every rule on the list, so send the ones you want to keep. An empty rules array removes them all. A list reads its rules back as synonym_rules.

Both client packages carry it (Lists.SetSynonymsAsync, lists.setSynonyms), and agents reach it through the list_set_synonyms MCP tool.

Notes
  • Rules are read on every search of the list, including searches through a group the list belongs to.
  • Nothing about a synonym is retroactive and nothing is rewritten: a rule changes how a search is read, never what your records say.
  • Removing a rule takes effect on the next search. Searches already answered are not revisited.
  • Synonyms are copied when you clone a list.
Top