Synonym Map Operations (Azure Search Service REST API)

In Azure Search, developers can define custom rules to expand or rewrite a search query with equivalent terms. For example, in your application, the words "whirlpool", "jacuzzi" and "hot tub" may be equivalent and you want to have a rule that automatically expands the search when only one is searched for. The resource that contains the rules is called a synonym map. Synonym maps are service level resources and maintained independently from search indexes. Once a synonym map is uploaded, you can point any searchable field to the synonym map (one per field).

Workflow

Setting up synonyms in your search application is a two-step process:

  1. Add a synonym map to your search service. You can use the search service REST API to create and manage synonym maps. Please see the section below titled "Operations on synonym maps" for the supported operations and Create Synonym Map for the request body.

  2. Configure a searchable field to use the synonym map in the index definition. A new field property synonymMaps specifies a synonym map to use for the field.

For example, the index definition below configures the 'name' field to use the synonym map 'mysynonymmap'.

	POST https://[service name].search.windows.net/indexes?api-version=2019-05-06
	api-key: [admin key]

	{
	   "name":"myindex",
	   "fields":[
	      {
	         "name":"id",
	         "type":"Edm.String",
	         "key":true
	      },
	      {
	         "name":"name",
	         "type":"Edm.String",
	         "searchable":true,
	         "analyzer":"en.lucene",
	         "synonymMaps":[
	            "mysynonymmap"
	         ]
	      }
	   ]
	}

You can update the synonymMaps properties of existing fields at any time.

Operations on synonym maps

The REST API for synonym maps includes the operations shown in the following table.

Create Synonym Map

POST https://[service name].search.windows.net/synonymmaps?api-version=[api-version]  
Content-Type: application/json  
api-key: [admin key]  
PUT https://[service name].search.windows.net/synonymmaps/[synonymmap name]?api-version=[api-version]  
Content-Type: application/json  
api-key: [admin key]  

Update Synonym Map

PUT https://[service name].search.windows.net/synonymmaps/[synonymmap name]?api-version=[api-version]  
Content-Type: application/json  
api-key: [admin key]  

List Synonym Maps

GET https://[service name].search.windows.net/synonymmaps?api-version=[api-version]  
api-key: [admin key]  

Get Synonym Map

GET https://[service name].search.windows.net/synonymmaps/[synonymmap name]?api-version=[api-version]  
api-key: [admin key]  

Delete Synonym Map

DELETE https://[service name].search.windows.net/synonymmaps/[synonymmap name]?api-version=[api-version]  
api-key: [admin key]  

See also

Azure Search Service REST
Language support (Azure Search Service REST API) Custom Analyzers in Azure Search (Azure Search Service REST API)