This topic describes how to configure synonyms. After you complete the synonym configuration, you can upload the updated synonym dictionary file, apply the file to Alibaba Cloud Elasticsearch clusters, and use the new dictionary for searches.

Prerequisites

A synonym dictionary file is uploaded. If you have not uploaded a file, perform the operations described in Upload a synonym dictionary file first.

Configuration example 1

The following example uses a filter to configure synonyms. It also uses the aliyun_synonyms.txt file as the test file to configure begin, start.

  1. Log on to the Kibana console of your Elasticsearch cluster.
    For more information, see Log on to the Kibana console.
  2. In the left-side navigation pane, click Dev Tools.
  3. On the Console tab, run the following command to create an index:
    PUT /aliyun-index-test
    {
      "settings": {
        "index":{
          "analysis": {
              "analyzer": {
                "by_smart": {
                  "type": "custom",
                  "tokenizer": "ik_smart",
                  "filter": ["by_tfr","by_sfr"],
                  "char_filter": ["by_cfr"]
                },
                "by_max_word": {
                  "type": "custom",
                  "tokenizer": "ik_max_word",
                  "filter": ["by_tfr","by_sfr"],
                  "char_filter": ["by_cfr"]
                }
             },
             "filter": {
                "by_tfr": {
                  "type": "stop",
                  "stopwords": [" "]
                  },
               "by_sfr": {
                  "type": "synonym",
                  "synonyms_path": "analysis/aliyun_synonyms.txt"
                  }
              },
              "char_filter": {
                "by_cfr": {
                  "type": "mapping",
                  "mappings": ["| => |"]
                }
              }
          }
        }
      }
    }
  4. Configure the title synonym field.
    • Run the following command if your Elasticsearch version is earlier than V7.0:
      PUT /aliyun-index-test/_mapping/doc
      {
      "properties": {
       "title": {
         "type": "text",
         "analyzer": "by_max_word",
         "search_analyzer": "by_smart"
       }
      }
      }
    • Run the following command if your Elasticsearch version is V7.0 or later:
      PUT /aliyun-index-test/_mapping/
      {
      "properties": {
       "title": {
         "type": "text",
         "analyzer": "by_max_word",
         "search_analyzer": "by_smart"
       }
      }
      }
      Note In open-source Elasticsearch 7.0 and later, the type parameter is deprecated and its function is replaced by _doc. You do not need to specify the type when you configure the index mapping. If you specify the type, an error is returned.
  5. Run the following command to verify synonyms:
    GET /aliyun-index-test/_analyze
    {
    "analyzer": "by_smart",
    "text":"begin"
    }
    If the command is successfully executed, the following result is returned:
    {
    "tokens": [
     {
       "token": "begin",
       "start_offset": 0,
       "end_offset": 5,
       "type": "ENGLISH",
       "position": 0
     },
     {
       "token": "start",
       "start_offset": 0,
       "end_offset": 5,
       "type": "SYNONYM",
       "position": 0
     }
    ]
    }
  6. Add data for further testing.
    • Run the following command if your Elasticsearch version is earlier than V7.0:
      PUT /aliyun-index-test/doc/1
      {
      "title": "Shall I begin?"
      }
      PUT /aliyun-index-test/doc/2
      {
      "title": "I start work at nine."
      }
    • Run the following command if your Elasticsearch version is V7.0 or later:
      PUT /aliyun-index-test/_doc/1
      {
      "title": "Shall I begin?"
      }
      PUT /aliyun-index-test/_doc/2
      {
      "title": "I start work at nine."
      }
  7. Run the following command to perform a search test and verify synonyms:
    GET /aliyun-index-test/_search
    {
     "query" : { "match" : { "title" : "begin" }},
     "highlight" : {
         "pre_tags" : ["<red>", "<bule>"],
         "post_tags" : ["</red>", "</bule>"],
         "fields" : {
             "title" : {}
         }
     }
    }
    If the command is successfully executed, the following result is returned:
    {
    "took": 11,
    "timed_out": false,
    "_shards": {
     "total": 5,
     "successful": 5,
     "failed": 0
    },
    "hits": {
     "total": 2,
     "max_score": 0.41048482,
     "hits": [
       {
         "_index": "aliyun-index-test",
         "_type": "doc",
         "_id": "2",
         "_score": 0.41048482,
         "_source": {
           "title": "I start work at nine."
         },
         "highlight": {
           "title": [
             "I <red>start</red> work at nine."
           ]
         }
       },
       {
         "_index": "aliyun-index-test",
         "_type": "doc",
         "_id": "1",
         "_score": 0.39556286,
         "_source": {
           "title": "Shall I begin?"
         },
         "highlight": {
           "title": [
             "Shall I <red>begin</red>?"
           ]
         }
       }
     ]
    }
    }

Configuration example 2

The following example references synonyms and uses the IK dictionary for word splitting.

  1. Log on to the Kibana console of your Elasticsearch cluster.
    For more information, see Log on to the Kibana console.
  2. In the left-side navigation pane, click Dev Tools.
  3. On the Console tab, run the following command to create an index:
    PUT /my_index
    {
     "settings": {
         "analysis": {
             "analyzer": {
                 "my_synonyms": {
                     "filter": [
                         "lowercase",
                         "my_synonym_filter"
                     ],
                     "tokenizer": "ik_smart"
                 }
             },
             "filter": {
                 "my_synonym_filter": {
                     "synonyms": [
                         "begin,start"
                     ],
                     "type": "synonym"
                 }
             }
         }
     }
    }
    You can run this command to execute the following tasks:
    1. Configure the my_synonym_filter synonym filter and a synonym dictionary.
    2. Configure the my_synonyms analyzer and use the ik_smart IK analyzer to split words.
    3. The ik_smart IK analyzer splits words and then converts all letters into lowercase.
  4. Configure the title synonym field.
    • Run the following command if your Elasticsearch version is earlier than V7.0:
      PUT /my_index/_mapping/doc
      {
      "properties": {
       "title": {
         "type": "text",
         "analyzer": "my_synonyms"
       }
      }
      }
    • Run the following command if your Elasticsearch version is V7.0 or later:
      PUT /my_index/_mapping/
      {
      "properties": {
       "title": {
         "type": "text",
         "analyzer": "my_synonyms"
       }
      }
      }
      Note In open-source Elasticsearch 7.0 and later, the type parameter is deprecated and its function is replaced by _doc. You do not need to specify the type when you configure the index mapping. If you specify the type, an error is returned.
  5. Run the following command to verify synonyms:
    GET /my_index/_analyze
    {
     "analyzer":"my_synonyms",
     "text":"Shall I begin?"
    }
    If the command is successfully executed, the following result is returned:
    {
    "tokens": [
     {
       "token": "shall",
       "start_offset": 0,
       "end_offset": 5,
       "type": "ENGLISH",
       "position": 0
     },
     {
       "token": "i",
       "start_offset": 6,
       "end_offset": 7,
       "type": "ENGLISH",
       "position": 1
     },
     {
       "token": "begin",
       "start_offset": 8,
       "end_offset": 13,
       "type": "ENGLISH",
       "position": 2
     },
     {
       "token": "start",
       "start_offset": 8,
       "end_offset": 13,
       "type": "SYNONYM",
       "position": 2
     }
    ]
    }
  6. Add data for further testing.
    • Run the following command if your Elasticsearch version is earlier than V7.0:
      PUT /my_index/doc/1
      {
      "title": "Shall I begin?"
      }
      PUT /my_index/doc/2
      {
      "title": "I start work at nine."
      }
    • Run the following command if your Elasticsearch version is V7.0 or later:
      PUT /my_index/_doc/1
      {
      "title": "Shall I begin?"
      }
      PUT /my_index/_doc/2
      {
      "title": "I start work at nine."
      }
  7. Run the following command to perform a search test and verify synonyms:
    GET /my_index/_search
    {
    "query" : { "match" : { "title" : "begin" }},
    "highlight" : {
      "pre_tags" : ["<red>", "<bule>"],
      "post_tags" : ["</red>", "</bule>"],
      "fields" : {
          "title" : {}
      }
    }
    }
    If the command is successfully executed, the following result is returned:
    {
    "took": 11,
    "timed_out": false,
    "_shards": {
     "total": 5,
     "successful": 5,
     "failed": 0
    },
    "hits": {
     "total": 2,
     "max_score": 0.41913947,
     "hits": [
       {
         "_index": "my_index",
         "_type": "doc",
         "_id": "2",
         "_score": 0.41913947,
         "_source": {
           "title": "I start work at nine."
         },
         "highlight": {
           "title": [
             "I <red>start</red> work at nine."
           ]
         }
       },
       {
         "_index": "my_index",
         "_type": "doc",
         "_id": "1",
         "_score": 0.39556286,
         "_source": {
           "title": "Shall I begin?"
         },
         "highlight": {
           "title": [
             "Shall I <red>begin</red>?"
           ]
         }
       }
     ]
    }
    }