A file that still answers for a company that has moved on
Somewhere in your search stack there is a synonym file. It may be a text file referenced by an Elasticsearch analyzer, a set of query rules in SharePoint, or a term set in the managed metadata service. It was written when the organization looked different: different product names, different team names, different acronyms. Nobody has opened it in years. It still fires on every query.
This is not a search-tuning problem. It is a governance problem with a search-shaped symptom. A synonym set is a vocabulary snapshot. It records what the organization called things at the moment someone authored the rules. Nothing in the search stack forces it to notice a rename, a merger, a product retirement, or a reorganization. The file keeps answering queries for an organization that no longer exists, and it does so confidently, which is worse than failing.
The fix is not a reindex. It is a small, reversible audit anchored to two artifacts you can export today: the synonym file itself and the query log. This article explains the mechanism, why staleness is invisible, and how to run the audit without breaking relevance.
What a synonym rule actually does
A synonym token filter rewrites the token stream during text analysis. When a document or a query passes through the analyzer, the filter matches configured terms and injects their equivalents as additional tokens, usually at the same position as the original. The inverted index, or the query, then carries both the original word and its synonyms. That description comes from a practitioner guide to Elasticsearch and OpenSearch synonyms, which is the most concrete retrieved source on the mechanism; Elastic’s own documentation page did not retrieve, so the mechanism claims here rest on that secondary source and should be verified against your platform’s current documentation before you change production settings.
There are two rule shapes, and confusing them is the most common synonym bug:
- Equivalent rules list interchangeable terms separated by commas:
laptop, notebook, computer. Every term expands to all the others. A query for any one matches documents containing any of the rest. - Explicit rules use the
=>operator to map one direction only:i-pod, i pod => ipod. The left-hand terms are replaced by the right-hand terms and do not match each other.
That arrow matters more than people expect. If a team is renamed and the synonym file still maps the old team name to the new one with an explicit rule, searches for the old name return current documents. That looks correct. Then someone searches for the new name, and because the arrow points one way, the reverse lookup never fires. The rule was written to help people who remembered the old name. It now quietly penalizes people who use the current one.
Why stale synonyms are invisible
Query-time synonyms leave the index untouched and expand the query instead. Updating a rule is a settings change, not a reindex. That is the property that makes stale rules so durable: because no document changes when a rule is edited, no document changes when a rule is wrong. There is no document-level trace that a mapping has outlived its vocabulary. The rule sits in analyzer settings or query-rule configuration, firing on every matching query, and nothing in the content store records that it is obsolete.
Index-time synonyms behave differently. They bake the expanded tokens into the inverted index, so every synonym change requires reindexing the affected documents, and the index grows. That makes stale index-time synonyms stickier: the cost of correction is high enough that teams defer it, and the deferral compounds. The retrieved source also notes that query-time expansion is not free of trade-offs. Because the synonyms were never indexed, term statistics used for scoring see only the original terms, and rarer synonyms can score unexpectedly. Query-time synonyms are the easier fix and the easier thing to forget; they are not risk-free for ranking.
One hard constraint from the same source: a synonym set managed through the Synonyms API or a synonym file with updateable: true can only be used in a search analyzer, never an index analyzer. The hot-reload machinery is query-time only. If your organization relies on hot reload to keep synonyms current, your synonyms are query-time by construction, and your audit should target the search analyzer configuration.
Scope inheritance is a hidden multiplier
In SharePoint, query rules let an administrator specify conditions and correlated actions, and a rule can be made active only during a particular time period. Rules can be scoped at tenant, site collection, or site level, and sites inherit rules created at higher levels. A rule created at tenant level applies to all site collections; a rule created at site collection level applies to all sites in that collection.
That inheritance is efficient and it is also a multiplier for staleness. A single obsolete mapping authored at tenant level can misdirect searches across many sites, and no site owner authored it or knows it exists. When you audit, start at the highest scope and work down. A stale tenant-level rule is worth more attention than a stale site-level rule because its blast radius is larger.
SharePoint also deprecated query rules with promoted results for organization-scoped queries in December 2021, in favor of Bookmark and Q&A answers in modern search experiences. That deprecation is a reminder that the configuration surface itself moves. A synonym or query-rule artifact written for one search experience may be partially inert in another, which makes the audit more urgent, not less: an inert rule is not harmless if it still fires in the classic experience some users still rely on.
The audit is a join, not a crawl
The cheapest way to find stale synonyms is to join the synonym file against the query log. You do not need to crawl content or reindex. You need two exports and a spreadsheet or a short script.
- Export the synonym file or query-rule inventory. For Elasticsearch or OpenSearch, that is the synonym file or the synonym set definition. For SharePoint, it is the query-rule list at each scope, which you can review from the Manage Query Rules page at tenant, site collection, and site level. Record each rule’s left-hand terms, right-hand terms, rule shape (equivalent or explicit), scope, and active period if one is set.
- Export the query log. Match the left-hand terms against queries actually issued. Rank rules by traffic.
- Flag rules whose right-hand terms point at retired names. These are the priority. A rule that still receives traffic but maps to a product, team, or acronym the organization no longer uses is actively misdirecting people.
- Flag rules with no query traffic. These are retirement candidates. A rule nobody triggers is not helping anyone, and it is one more thing to maintain.
This is original reasoning, not a documented procedure: the join is a recommendation, and the ranking thresholds are yours to set. The point is that the evidence is exportable and inspectable. You are not guessing whether a rule is stale; you are looking at whether people still search for the old vocabulary and whether the rule sends them somewhere that still exists.
Multi-word rules and filter order are part of the audit
Two hazards deserve a place in the audit because they make a rule look present while it is effectively dead.
First, multi-word synonyms. The legacy synonym filter cannot cleanly represent multi-word synonyms such as ny to new york, so it corrupts token positions and breaks phrase and proximity queries. The synonym_graph filter handles multi-word synonyms correctly by producing a token graph that preserves positions across terms of different lengths, which is why it is recommended over the older synonym filter for any set containing multi-word rules. If your file contains multi-word mappings and your analyzer uses the legacy filter, those rules may be producing wrong results rather than no results, which is harder to notice.
Second, filter order relative to stemming. If your search analyzer stems before it applies synonyms, running becomes run and a running => jogging rule never fires. Order the filters so synonyms see the words your rules were written against, and keep stemming consistent across the index and search analyzers. A rule that never fires is indistinguishable from a rule that does not exist, except that it still occupies a line in the file and a slot in someone’s mental model of how search works.
Equivalent rules also chain transitively. If jaguar links to cat and cat links to feline, a search for the car brand can pull in zoology. Broad equivalence groups written for one organizational vocabulary can produce surprising results when the vocabulary shifts around them. When you audit, look for equivalence chains that cross domains, and prefer explicit one-directional rules where intent is directional.
What the standards say, and what they do not
SKOS, the W3C Simple Knowledge Organization System, provides a data model in which concepts are identified by URIs and labeled with lexical strings in one or more natural languages, linked to other concepts and organized into hierarchies, and mapped to concepts in other schemes. The specification describes SKOS as providing a standard, low-cost migration path for porting existing knowledge organization systems to the Semantic Web. The relevant property for this discussion is skos:altLabel, the alternate label: the standard’s way of recording that a concept has more than one name.
What SKOS gives you is a model for treating synonyms as labels on concepts rather than as free-floating string pairs. That matters because a concept has an identity (a URI) that survives a rename, while a string pair does not. If your synonym file is a flat list of old => new mappings, it has no concept identity, so it cannot tell you that the old name is retired rather than merely alternate. A SKOS-shaped vocabulary can. The trade-off is that adopting SKOS is a real modeling effort, not a configuration change, and it is not a prerequisite for the audit described here. You can run the join against a flat file today and decide later whether the vocabulary deserves a concept scheme.
ISO 25964, the thesaurus standard, did not retrieve, so this article makes no claim about its specific provisions. If your organization maintains a formal thesaurus, check the standard directly before asserting that a synonym file complies with it.
Records disposition is a separate question. NARA’s General Records Schedules provide disposition authority for common federal records, and their use is mandatory unless an agency justifies an agency-specific schedule. Whether a search configuration artifact is itself a record subject to a schedule is a question for your records officer, not for this article; the retrieved GRS page establishes the schedules’ authority and mandatory use, not their application to synonym files. The practical point is narrower: if your synonym file is versioned and owned, it becomes an inspectable artifact that a records officer can evaluate. If it lives only in a running cluster’s settings, it cannot be scheduled, audited, or retired on purpose.
A lightweight, reversible fix
The fix is not to rewrite the synonym set. It is to make the set visible, versioned, and owned, then retire rules on evidence.
- Export and version the synonym set. Store it in a repository with a change history. The export is the artifact; the running configuration is a deployment of it.
- Run the join against query logs. Rank rules by traffic to retired targets. Fix or retire the top of the list first.
- Prefer query-time rules where the platform allows it. Query-time synonyms are a settings change plus analyzer reload rather than a reindex, which makes correction cheap and reversible. Accept the scoring nuance and measure relevance before and after rather than assuming the change is neutral.
- Name an owner and a review trigger. Tie the review to the events that invalidate vocabulary: product renames, team reorganizations, mergers, acronym retirements. A calendar cadence alone will not catch a rename that happens between reviews.
- Retire rules with no traffic. A rule nobody triggers is maintenance debt. Removing it is reversible if you keep the version history.
Treat the synonym set as governed data, not config. Version it, review changes, and give a business owner the edit path. That recommendation comes from the practitioner guide, and it is the difference between a file that tracks the organization and a file that outlives it.
Why this is worth doing now
The 2016 synonym file is a useful name for a pattern, not a verified artifact. No retrieved source establishes that a specific file from 2016 exists, who wrote it, or what it contains, and this article does not claim otherwise. The pattern is what matters: a vocabulary snapshot that was correct when authored, that no process forces to notice change, and that keeps answering queries with confidence.
The audit is small. It needs two exports, a join, and a named owner. It does not need a reindex, a platform migration, or a new taxonomy. It needs someone to look at the file and the query log together and ask which rules are still answering for an organization that has moved on. That question is answerable with artifacts you can export today, and the answer is reversible.
Questions readers ask
Is a synonym file a record?
That depends on your jurisdiction and your records officer. NARA’s General Records Schedules provide disposition authority for common federal records and their use is mandatory unless an agency justifies an agency-specific schedule, but the retrieved page does not address search configuration artifacts specifically. Versioning the file makes the question answerable; leaving it in cluster settings makes it unanswerable.
Do I need to reindex to fix stale synonyms?
If the synonyms are query-time, no. Updating a rule is a settings change plus analyzer reload. If they are index-time, yes: every synonym change requires reindexing the affected documents. That is one reason to prefer query-time rules for vocabulary that changes.
Can I just delete the old rules?
You can, and version history makes deletion reversible. But check the query log first. A rule that still receives traffic may be the only thing connecting a long-tenured user’s vocabulary to current content. Retire it on evidence, not on age.
Does SKOS solve this?
SKOS gives you a model for treating synonyms as alternate labels on concepts with stable identities, which is a better foundation than flat string pairs. It is a modeling effort, not a configuration change, and it is not required for the audit. The audit works on a flat file today.
