Synonyms and pins

Synonyms and pins are query-time settings — they apply to the next query with no rebuild, and are the first place to look when a query returns the wrong thing, or nothing at all.

Synonyms

A synonym rule tells suo that two or more terms should match the same content, on top of typo tolerance.

Two-way: either term finds the same results.

{ "id": "s1", "kind": "two-way", "terms": ["signup", "sign up"] }

One-way: the input finds results for the synonyms, but not the reverse — useful for a specific term expanding to a broader one without the broader term also surfacing the specific one.

{ "id": "s2", "kind": "one-way", "input": "docs", "synonyms": ["documentation", "guide"] }

Set them from the dashboard's Relevance tab, or directly:

PUT /1/indexes/docs/settings
{ "queryTime": { "synonyms": [{ "id": "s1", "kind": "two-way", "terms": ["signup", "sign up"] }] } }

Synonym expansion runs after exact and typo-corrected candidates, so it only widens the result set when the literal query alone was not enough.

Pins

A pin forces one exact record to a fixed position for one exact query — the top result for a specific search term that should never depend on ranking.

{ "id": "p1", "query": "pricing", "objectID": "page-pricing", "position": 0 }

Pins sit above every other ranking tier — see The ranking cascade. Use them sparingly: a handful of pins for queries where you know exactly what the answer should be, not as a general ranking tool.

Hides

A hide removes one record from the results for one exact query, without deleting the record itself — useful when a page is technically a match but should never be the answer to a specific search.

{ "id": "h1", "query": "old feature", "objectID": "page-deprecated" }

Finding what needs a rule

The Analytics tab's zero-result and low-click-through queries are the best source of new synonym and pin candidates — see Reading analytics. The playground's zero-result state links directly into adding a synonym or pin for the query you just tried.