Skip to main content
Azure
  • 2 min read

Azure Search – Announcing the general availability of synonyms

Today we are announcing the general availability of synonyms. Synonyms allows Azure Search to associate equivalent terms that implicitly expand the scope of a query, without the user having to…

Today we are announcing the general availability of synonyms. Synonyms allow Azure Search to associate equivalent terms that implicitly expand the scope of a query, without the user having to provide the alternate terms.

A good example of this capability was demonstrated at the recent Microsoft Build conference, where we showed how NBA.com searches their vast photo library of players, owners, and celebrities. In this application Azure Search synonyms are used to enable nicknames of Lebron James such as “The King” or “King James” to be returned regardless of which of the three terms are used in the query.

In Azure Search, synonym support is based on synonym maps that you define and upload to your search service. These maps constitute an independent resource, such as indexes or data sources, and can be used by any searchable field in any index in your search service. Synonym maps use the Apache Solr format as outlined in the example synonym map below:

POST https://[servicename].search.windows.net/synonymmaps?api-version=2017-11-11	
api-key: [admin key]	
{	
   "name":"mysynonymmap",	
   "format":"solr",	
   "synonyms": "	
	USA, United States, United States of American	
	Washington, Wash., WA => WAn"	
}

In the above example, you can see there are two types of synonyms that are used. The first example is a set of synonyms which indicate that a user could search using any of the three terms (“USA”, “United States”, or “United States of America”) in their query and any document that contains either of these terms will become viable search results.

The second example is an explicit mapping and is denoted by an arrow “=>” that states that a search query that matches the left hand side of “=>” will be replaced with the alternatives on the right hand side. Given the rule below, search queries “Washington”, “Wash.”, or “WA” will all be rewritten to “WA”. Explicit mapping only applies in the direction specified and does not rewrite the query “WA” to “Washington” in this case.

The first option is useful in situations where you have multiple ways of referring to the same thing in the index. The second is good when the data is normalized to single value in the index, but people would refer to the same thing by multiple terms in a query. 

TIP: Azure Search Traffic Analytics is a great way to identify queries with low recall that can be candidates to be used as synonyms.

Once the synonym map has been created, you can then associate it with any fields within your indexes. Afterwards, the synonym map can be updated with new synonyms that will instantly be incorporated into subsequent searches. For example, if you were using the REST API to create your Azure Search index, you could apply it to a field called “description” as follows:

POST https://[servicename].search.windows.net/indexes?api-version=2017-11-11	
api-key: [admin key]	
{	
    "name":"myindex",	
    "fields":[	
    {	
        "name":"id",	
        "type":"Edm.String",	
        "key":true	
    },	
    {	
        "name":"description",	
        "type":"Edm.String",	
        "searchable":true,	
        "synonymMaps":[	
            "mysynonymmap"	
        ]	
    }	
    ]	
}	

Learn more about synonyms in Azure Search.