Today, we are happy to announce public preview support for synonyms in Azure Search, one of our most requested features on UserVoice. Synonyms functionality allows for Azure Search to not only return results which match the query terms that were typed into the search box, but also return results which match synonyms of the query terms. As a search-as-a-service solution, Azure Search is used in a wide variety of applications which span many languages, industries, and scenarios. Since terminology and definitions vary from case to case, Azure Search’s Synonyms API allows customers to define their own synonym mappings.
Synonyms aim to increase recall without sacrificing relevance
Synonyms functionality in Azure Search allows a user to get more results for a given query without sacrificing how relevant those results are to the query terms. In a real estate website, for example, a user may be searching for ‘jacuzzi.’ If some of the listings only have the term ‘hot tub’ or ‘whirlpool bath,’ then the user will not see those results. When ‘jacuzzi’ and ‘hot tub’ are mapped to one another in a synonym map, Azure Search does not have to do any guess-work in understanding that these terms are relevant even though the terms bear no resemblance in spelling.
Multi-word synonyms
In many full text search engines, support for synonyms is limited to single words. Our team has engineered a solution that allows Azure Search to support multi-word synonyms. This allows for phrase queries (“”) to function properly while using synonyms. If someone has mapped ‘hot tub’ to ‘whirlpool bath’ and they then search for “large hot tub,” Azure Search will return matches which contain both “large hot tub” and “large whirlpool bath.”
Support for Solr SynonymFilterFactory format
Azure Search’s synonyms feature supports the same format used by Apache Solr’s SynonymFilterFactory. As a widely-used open source standard, many existing synonym maps can be found for various languages and specific domains that can be used out-of-the box with Azure Search.
Creating or updating a synonym map
Enabling synonyms functionality does not require any re-indexing of your content in Azure Search or any interruption of your service and you can add new synonyms at any time. Currently, the Synonyms API is in Public Preview and only available in the Service REST API (api-version=2016-09-01-Preview) and .NET SDK.
When defining synonyms for Azure Search, you add a named resource to your search service called a synonymMap. You can enable synonyms for fields in your index by referring to the name of a synonymMap in the new synonymMaps property of the field definition.
Like an index definition, a synonym map is managed as an atomic resource that you read, update, or delete in a single operation. That means that if you want to make incremental changes to a synonym map, you will need to read, modify, and update the entire synonym map.
Below, there are some example operations using an example scenario of a real estate listings data set using the REST API. For examples using the .NET SDK, please visit the documentation.
POST
You can create a new synonym map in the REST API using HTTP POST:
POST https://[servicename].search.windows.net/synonymmaps?api-version=2016-09-01-Preview
api-key: [admin key]
{
"name":"addressmap",
"format":"solr",
"synonyms": "
Washington, Wash., WA => WAn
USA, United States, United States of America"
}
PUT
You can create a new synonym map or update an existing synonym map using HTTP PUT.
When using PUT, you must specify the synonym map name on the URI. If the synonym map does not exist, it will be created.
PUT https://[servicename].search.windows.net/synonymmaps/addressmap?api-version=2016-09-01-Preview
api-key: [admin key]
{
"name":"addressmap",
"format":"solr",
"synonyms": "
Washington, Wash., WA => WAn
USA, United States, United States of American"
}
Types of synonym mappings
With the Synonyms API, it is possible to define synonyms in two ways: one-way mappings and equivalence-class mappings.
One-way mappings
With one-way mappings, Azure Search will treat multiple terms as if they all are a specific term. For example, the state where a property is located may only be stored as the two-letter abbreviation in the index for real estate listings. However, users may type in the full name of the state or other abbreviations.
{
"name":"addressmap",
"format":"solr",
"synonyms": "
Washington, Wash., WA => WA"
}
Equivalence-class mappings
In many domains, there are terms which all have the same or similar meaning. The Synonyms API makes it simple to map all like terms to one another so that the search term is expanded at query-time to include all synonyms. The above example of the multiple ways to describe ‘jacuzzi’ is demonstrated below.
{
"name":"descriptionmap",
"format":"solr",
"synonyms": "hot tub, jacuzzi, whirlpool bath, sauna"
}
Setting the synonym map in the index definition
When defining a searchable field in your index, you can use the new property synonymMaps to specify a synonym map to use for the field. Multiple indexes in the same search service can refer to the same synonym map.
NOTE: Currently only one synonym map per field is supported.
POST https://[servicename].search.windows.net/indexes?api-version= 2016-09-01-Preview
api-key: [admin key]
{
"name":"realestateindex",
"fields":[
{
"name":"id",
"type":"Edm.String",
"key":true
},
{
"name":"address",
"type":"Edm.String",
"searchable":true,
"analyzer":"en.lucene",
"synonymMaps":[
"addressmap"
]
},
{
"name":"description",
"type":"Edm.String",
"searchable":true,
"analyzer":"en.lucene",
"synonymMaps":[
"descriptionmap"
]
}
]
}
Synonyms + Search Traffic Analytics
Coupled with Search Traffic Analytics (STA), synonyms can be powerful in improving the quality of the search results that end users see. STA in Azure Search reveals the most common queries with zero results. By adding relevant synonyms to these terms, these zero-result queries can be mitigated. STA also shows the most common query terms for your Azure Search service, so you do not need to guess when determining proper terms for your synonym map.
Learn more
You follow these links for the detailed documentation around synonyms using the REST API and .NET SDK. Read more about Azure Search and its capabilities and visit our documentation. Please visit our pricing page to learn about the various tiers of service to fit your needs.