Java

Synonyms

Overview

Synonyms tell the engine about sets of words and expressions that should be considered equal with regard to textual relevance.

All synonym records have a type attribute. The two most used types are:

  • (Regular) Synonyms - synonym: Regular synonyms are the most common, all words or expressions are considered equals

    {
       "objectID": "NAME",
       "type": "synonym",
       "synonyms":[
          "tv",
          "television",
          "tv set"
       ]
    }
    
  • One-way Synonym - oneWaySynonym: When the input is searched all words or expressions in synonyms are considered equals to the input

    {
       "objectID": "NAME",
       "type": "oneWaySynonym",
       "input": "tablet",
       "synonyms":[
          "ipad",
          "galaxy note"
       ]
    }
    

If you’re looking for other types of synonyms or want more details you can have a look at our synonyms guide

Save synonym - saveSynonym

This method saves a single synonym record into the index.

In this example, we specify true to forward the creation to replica indices. By default the behavior is to save only on the specified index.

index.saveSynonym("a-unique-identifier", new Synonym()
           .setSynonyms(Arrays.asList("car", "vehicle", "auto")), true);

Batch synonyms - batchSynonyms

Use the batch method to create a large number of synonyms at once, forward them to replica indices if desired, and optionally replace all existing synonyms on the index with the content of the batch using the replaceExistingSynonyms parameter.

You should always use replaceExistingSynonyms to atomically replace all synonyms on a production index. This is the only way to ensure the index always has a full list of synonyms to use during the indexing of the new list.

// Batch synonyms, with replica forwarding and atomic replacement of existing synonyms
index.batchSynonyms(Arrays.asList(
      new Synonym()
           .setObjectID("a-unique-identifier")
           .setSynonyms(Arrays.asList("car", "vehicle", "auto")),
      new Synonym()
           .setObjectID("another-unique-identifier")
           .setSynonyms(Arrays.asList("street", "st"))
), true);

Editing Synonyms

Updating the value of a specific synonym record is the same as creating one. Make sure you specify the same objectID used to create the record and the synonyms will be updated. When updating multiple synonyms in a batch call (but not all synonyms), make sure you set replaceExistingSynonyms to false (or leave it out, false is the default value). Otherwise, the entire synonym list will be replaced only partially with the records in the batch update.

Delete synonym - deleteSynonym

Use the normal index delete method to delete synonyms, specifying the objectID of the synonym record you want to delete. Forward the deletion to replica indices by setting the forwardToReplicas parameter to true.

// Delete and forward to replicas
index.deleteSynonym("a-unique-identifier", true);

Clear all synonyms - clearSynonyms

This is a convenience method to delete all synonyms at once. It should not be used on a production index to then push a new list of synonyms: there would be a short period of time during which the index would have no synonyms at all.

To atomically replace all synonyms of an index, use the batch method with the replaceExistingSynonyms parameter set to true.

// Clear synonyms and forward to replicas
index.clearSynonyms(true);

Get synonym - getSynonym

Search for synonym records by their objectID or by the text they contain. Both methods are covered here.

Optional<AbstractSynonym> synonym = index.getSynonym("a-unique-identifier");

Search synonyms - searchSynonyms

Search for synonym records similar to how you’d search normally.

Accepted search parameters:

  • query: the actual search query to find synonyms. Use an empty query to browse all the synonyms of an index.
  • type: restrict the search to a specific type of synonym. Use an empty string to search all types (default behavior). Multiple types can be specified using a comma-separated list or an array.
  • page: the page to fetch when browsing through several pages of results. This value is zero-based. hitsPerPage: the number of synonyms to return for each call. The default value is 100.
// Searching for "street" in synonyms and one-way synonyms; fetch the second page with 10 hits per page
SearchSynonymResult results = index.searchSynonyms(new SynonymQuery("street").setTypes(Arrays.asList("synonym", "one_way")).setPage(1).setHitsPerPage(10));