Synonym Map Operations (Azure Cognitive Search REST API)

  • Article

A synonym map is a resource that associates terms, expanding queries to include mapped 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

  1. Add a synonym map using Create Synonym Map.

  2. Reference the synonym map on a searchable field of type Edm.String or Edm.Collection in the index definition. You can use Update Index to add this property to an existing field. A field property synonymMaps specifies the map (one per field). You can update the synonymMaps properties of existing fields at any time.

  3. Query as usual, using terms or phrases (enclosed in quotation marks). In Cognitive Search, two-part terms, such as "hot tub", must be expressed as a phrase, otherwise each term is evaluated independently. If you query for "hot tub", the search engine will scan for that phrase as well as any synonyms you have defined, such as jacuzzi.

Example

After you create a synonym map, you can assign it to specific fields in an index. The index definition below configures the 'name' field to use the synonym map 'mysynonymmap'.

POST /indexes?api-version=2020-06-30
{
    "name":"myindex",
    "fields":[
    ...
        {
            "name":"name",
            "type":"Edm.String",
            "searchable":true,
            "analyzer":"en.lucene",
            "synonymMaps": [
                "mysynonymmap"
            ]
        }
    ...
}

Operations on synonym maps

An admin API key is required for all synonym map operations.

See also