Diagnosing Algolia Synonyms That Do Not Appear in Search Results

The Problem and the Takeaway

You have uploaded synonyms to Algolia, but a search for one term does not return records that contain only the mapped synonym. For example, a query for sweater should surface products labeled jumper, yet only exact sweater matches appear. The useful takeaway is that in most cases the synonym data is valid, but the query request, client configuration, or propagation timing prevents the engine from applying it.

Recognizable Condition

The symptom is a one-sided result set: the base term returns hits, but the alternative term returns nothing, or vice versa. The behavior may be consistent across all queries, intermittent, or limited to recently added synonyms. In some cases the Algolia dashboard preview shows expanded results while the production API does not, which points to a request-level difference rather than a data problem.

Cause and Diagnostic Table

Ordered Checks

1. Confirm the synonym exists and is well-formed. Run the following request in the Algolia dashboard API explorer or via curl. You need an Admin API key; a search-only key will return a permission error.

   curl -X GET \
     -H "X-Algolia-Application-Id: <your-app-id>" \
     -H "X-Algolia-API-Key: <your-admin-api-key>" \
     "https://<your-app-id>-dsn.algolia.net/1/indexes/<your-index>/synonyms"

   The response should be a JSON array of synonym objects. Each object must include an objectID and a type field. A missing or incorrect type causes the engine to reject the entry.
2. Inspect the search request for the synonyms parameter. Algolia applies synonyms by default, but custom code, framework integrations, or proxy layers often disable them explicitly. Enable client debug mode or log the outgoing payload and look for "synonyms": false. If present, the engine will skip expansion for that query.
3. Verify index-level configuration and client defaults. Some wrappers inject default search parameters at the application or index level. Confirm that no configuration file or middleware is forcing synonyms=false. Also review normalization settings such as ignorePlurals or removeStopWords, because they change how tokens are matched before synonym expansion is evaluated.
4. Confirm propagation has completed. Synonym updates are asynchronous. After a batch save, the API returns a taskID. Use GET /1/indexes/<your-index>/task/<taskID> or the waitTask helper to verify the task status is published before testing. Testing against a cache snapshot that predates the update will produce false negatives.
5. Audit for duplicates and conflicts. Duplicate objectID values overwrite each other silently. Conflicting one-way mappings that share the same input but map to different outputs can create ambiguous expansion. Ensure every synonym has a unique objectID and that overlapping mappings are intentional.
6. Test the typo-tolerance boundary. Algolia applies synonyms before typo tolerance. If a user query contains a typo that is corrected to a different word, the synonym mapping may not trigger. Run the same test with the correctly spelled term to isolate this interaction.

Fixes Tied to Findings

If the format is wrong

Correct the JSON structure. A bidirectional synonym uses type: "synonym" with a synonyms array. A directional synonym uses type: "oneWaySynonym" with separate input and synonyms fields. For example:

{
  "objectID": "sweater-jumper",
  "type": "synonym",
  "synonyms": ["sweater", "jumper", "knitwear"]
}

{
  "objectID": "sweater-to-jumper",
  "type": "oneWaySynonym",
  "input": "sweater",
  "synonyms": ["jumper", "knitwear"]
}

Use oneWaySynonym when expansion should be directional, and synonym when the terms are equivalent.

If the query disables synonyms

Remove the override or set the parameter explicitly in your search call:

index.search('sweater', {
  synonyms: true
});

In raw query parameters, this is synonyms=true. If a framework injects defaults, configure the client to pass the correct value rather than relying on engine defaults.

If propagation is incomplete

Wait for the task to finish. Do not re-test until the task status is published. If you are scripting updates, chain the verification step so tests run only after confirmation.

If duplicates or conflicts exist

Delete the offending entries and re-push them with unique objectID values. Use a batch operation with deleteSynonym actions for cleanup, then save the corrected set. Keep a backup of the previous synonym list before deleting, because this operation changes index state.

If typo tolerance interferes

Accept the boundary or adjust typo tolerance settings only if the misspelling is common enough to justify the trade-off. Changing typo tolerance is a broader relevance decision and should be tested separately.

Limitations and Performance Notes

Synonyms are applied before typo tolerance, so a misspelled query that corrects to an unrelated word will not trigger the synonym. Excessive synonym lists can also increase query latency. Monitor processingTimeMS in search responses after adding large sets, and prune unused or redundant mappings.

Escalation Criteria

• All checks pass and synonyms still fail to apply.
• processingTimeMS rises significantly after synonym updates without a corresponding increase in result complexity.
• Dashboard preview and API responses diverge in ways not explained by query parameters or client defaults.
• You suspect an engine-level defect or an account-specific limit.

Practical Verification

After applying a fix, run a search for the base term and confirm that records containing only the synonym term appear in the hits. Inspect the request payload to ensure synonyms is not false. For recent changes, verify the task status is published before drawing conclusions.