Specify an analyzer

Specify an analyzer

Elasticsearch offers a variety of ways to specify built-in or custom analyzers:

Keep it simple

The flexibility to specify analyzers at different levels and for different times is great…​ but only when it’s needed.

In most cases, a simple approach works best: Specify an analyzer for each text field, as outlined in Specify the analyzer for a field.

This approach works well with Elasticsearch’s default behavior, letting you use the same analyzer for indexing and search. It also lets you quickly see which analyzer applies to which field using the get mapping API.

If you don’t typically create mappings for your indices, you can use index templates to achieve a similar effect.

How Elasticsearch determines the index analyzer

Elasticsearch determines which index analyzer to use by checking the following parameters in order:

  1. The analyzer mapping parameter for the field. See Specify the analyzer for a field.
  2. The analysis.analyzer.default index setting. See Specify the default analyzer for an index.

If none of these parameters are specified, the standard analyzer is used.

Specify the analyzer for a field

When mapping an index, you can use the analyzer mapping parameter to specify an analyzer for each text field.

The following create index API request sets the whitespace analyzer as the analyzer for the title field.

  1. resp = client.indices.create(
  2.     index="my-index-000001",
  3.     mappings={
  4.         "properties": {
  5.             "title": {
  6.                 "type": "text",
  7.                 "analyzer": "whitespace"
  8.             }
  9.         }
  10.     },
  11. )
  12. print(resp)
  1. response = client.indices.create(
  2.   index: 'my-index-000001',
  3.   body: {
  4.     mappings: {
  5.       properties: {
  6.         title: {
  7.           type: 'text',
  8.           analyzer: 'whitespace'
  9.         }
  10.       }
  11.     }
  12.   }
  13. )
  14. puts response
  1. const response = await client.indices.create({
  2.   index: "my-index-000001",
  3.   mappings: {
  4.     properties: {
  5.       title: {
  6.         type: "text",
  7.         analyzer: "whitespace",
  8.       },
  9.     },
  10.   },
  11. });
  12. console.log(response);
  1. PUT my-index-000001
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "title": {
  6.         "type": "text",
  7.         "analyzer": "whitespace"
  8.       }
  9.     }
  10.   }
  11. }

Specify the default analyzer for an index

In addition to a field-level analyzer, you can set a fallback analyzer for using the analysis.analyzer.default setting.

The following create index API request sets the simple analyzer as the fallback analyzer for my-index-000001.

  1. resp = client.indices.create(
  2.     index="my-index-000001",
  3.     settings={
  4.         "analysis": {
  5.             "analyzer": {
  6.                 "default": {
  7.                     "type": "simple"
  8.                 }
  9.             }
  10.         }
  11.     },
  12. )
  13. print(resp)
  1. response = client.indices.create(
  2.   index: 'my-index-000001',
  3.   body: {
  4.     settings: {
  5.       analysis: {
  6.         analyzer: {
  7.           default: {
  8.             type: 'simple'
  9.           }
  10.         }
  11.       }
  12.     }
  13.   }
  14. )
  15. puts response
  1. const response = await client.indices.create({
  2.   index: "my-index-000001",
  3.   settings: {
  4.     analysis: {
  5.       analyzer: {
  6.         default: {
  7.           type: "simple",
  8.         },
  9.       },
  10.     },
  11.   },
  12. });
  13. console.log(response);
  1. PUT my-index-000001
  2. {
  3.   "settings": {
  4.     "analysis": {
  5.       "analyzer": {
  6.         "default": {
  7.           "type": "simple"
  8.         }
  9.       }
  10.     }
  11.   }
  12. }

How Elasticsearch determines the search analyzer

In most cases, specifying a different search analyzer is unnecessary. Doing so could negatively impact relevancy and result in unexpected search results.

If you choose to specify a separate search analyzer, we recommend you thoroughly test your analysis configuration before deploying in production.

At search time, Elasticsearch determines which analyzer to use by checking the following parameters in order:

  1. The analyzer parameter in the search query. See Specify the search analyzer for a query.
  2. The search_analyzer mapping parameter for the field. See Specify the search analyzer for a field.
  3. The analysis.analyzer.default_search index setting. See Specify the default search analyzer for an index.
  4. The analyzer mapping parameter for the field. See Specify the analyzer for a field.

If none of these parameters are specified, the standard analyzer is used.

Specify the search analyzer for a query

When writing a full-text query, you can use the analyzer parameter to specify a search analyzer. If provided, this overrides any other search analyzers.

The following search API request sets the stop analyzer as the search analyzer for a match query.

  1. resp = client.search(
  2.     index="my-index-000001",
  3.     query={
  4.         "match": {
  5.             "message": {
  6.                 "query": "Quick foxes",
  7.                 "analyzer": "stop"
  8.             }
  9.         }
  10.     },
  11. )
  12. print(resp)
  1. response = client.search(
  2.   index: 'my-index-000001',
  3.   body: {
  4.     query: {
  5.       match: {
  6.         message: {
  7.           query: 'Quick foxes',
  8.           analyzer: 'stop'
  9.         }
  10.       }
  11.     }
  12.   }
  13. )
  14. puts response
  1. const response = await client.search({
  2.   index: "my-index-000001",
  3.   query: {
  4.     match: {
  5.       message: {
  6.         query: "Quick foxes",
  7.         analyzer: "stop",
  8.       },
  9.     },
  10.   },
  11. });
  12. console.log(response);
  1. GET my-index-000001/_search
  2. {
  3.   "query": {
  4.     "match": {
  5.       "message": {
  6.         "query": "Quick foxes",
  7.         "analyzer": "stop"
  8.       }
  9.     }
  10.   }
  11. }

Specify the search analyzer for a field

When mapping an index, you can use the search_analyzer mapping parameter to specify a search analyzer for each text field.

If a search analyzer is provided, the index analyzer must also be specified using the analyzer parameter.

The following create index API request sets the simple analyzer as the search analyzer for the title field.

  1. resp = client.indices.create(
  2.     index="my-index-000001",
  3.     mappings={
  4.         "properties": {
  5.             "title": {
  6.                 "type": "text",
  7.                 "analyzer": "whitespace",
  8.                 "search_analyzer": "simple"
  9.             }
  10.         }
  11.     },
  12. )
  13. print(resp)
  1. response = client.indices.create(
  2.   index: 'my-index-000001',
  3.   body: {
  4.     mappings: {
  5.       properties: {
  6.         title: {
  7.           type: 'text',
  8.           analyzer: 'whitespace',
  9.           search_analyzer: 'simple'
  10.         }
  11.       }
  12.     }
  13.   }
  14. )
  15. puts response
  1. const response = await client.indices.create({
  2.   index: "my-index-000001",
  3.   mappings: {
  4.     properties: {
  5.       title: {
  6.         type: "text",
  7.         analyzer: "whitespace",
  8.         search_analyzer: "simple",
  9.       },
  10.     },
  11.   },
  12. });
  13. console.log(response);
  1. PUT my-index-000001
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "title": {
  6.         "type": "text",
  7.         "analyzer": "whitespace",
  8.         "search_analyzer": "simple"
  9.       }
  10.     }
  11.   }
  12. }

Specify the default search analyzer for an index

When creating an index, you can set a default search analyzer using the analysis.analyzer.default_search setting.

If a search analyzer is provided, a default index analyzer must also be specified using the analysis.analyzer.default setting.

The following create index API request sets the whitespace analyzer as the default search analyzer for the my-index-000001 index.

  1. resp = client.indices.create(
  2.     index="my-index-000001",
  3.     settings={
  4.         "analysis": {
  5.             "analyzer": {
  6.                 "default": {
  7.                     "type": "simple"
  8.                 },
  9.                 "default_search": {
  10.                     "type": "whitespace"
  11.                 }
  12.             }
  13.         }
  14.     },
  15. )
  16. print(resp)
  1. response = client.indices.create(
  2.   index: 'my-index-000001',
  3.   body: {
  4.     settings: {
  5.       analysis: {
  6.         analyzer: {
  7.           default: {
  8.             type: 'simple'
  9.           },
  10.           default_search: {
  11.             type: 'whitespace'
  12.           }
  13.         }
  14.       }
  15.     }
  16.   }
  17. )
  18. puts response
  1. const response = await client.indices.create({
  2.   index: "my-index-000001",
  3.   settings: {
  4.     analysis: {
  5.       analyzer: {
  6.         default: {
  7.           type: "simple",
  8.         },
  9.         default_search: {
  10.           type: "whitespace",
  11.         },
  12.       },
  13.     },
  14.   },
  15. });
  16. console.log(response);
  1. PUT my-index-000001
  2. {
  3.   "settings": {
  4.     "analysis": {
  5.       "analyzer": {
  6.         "default": {
  7.           "type": "simple"
  8.         },
  9.         "default_search": {
  10.           "type": "whitespace"
  11.         }
  12.       }
  13.     }
  14.   }
  15. }