Loading

Specify an analyzer

Elastic Stack Serverless

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.

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.

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.

 PUT my-index-000001 {
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "analyzer": "whitespace"
      }
    }
  }
}

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.

 PUT my-index-000001 {
  "settings": {
    "analysis": {
      "analyzer": {
        "default": {
          "type": "simple"
        }
      }
    }
  }
}
Warning

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.

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.

 GET my-index-000001/_search {
  "query": {
    "match": {
      "message": {
        "query": "Quick foxes",
        "analyzer": "stop"
      }
    }
  }
}

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.

 PUT my-index-000001 {
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "analyzer": "whitespace",
        "search_analyzer": "simple"
      }
    }
  }
}

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.

 PUT my-index-000001 {
  "settings": {
    "analysis": {
      "analyzer": {
        "default": {
          "type": "simple"
        },
        "default_search": {
          "type": "whitespace"
        }
      }
    }
  }
}

Serverless Unavailable

You can only define new analyzers on closed indices. To add an analyzer, you must close the index, define the analyzer, and reopen the index.

For example, the following commands add the content analyzer to the my-index-000001 index:

 POST /my-index-000001/_close 
 PUT /my-index-000001/_settings {
  "analysis" : {
    "analyzer":{
      "content":{
        "type":"custom",
        "tokenizer":"whitespace"
      }
    }
  }
}

 POST /my-index-000001/_open
Warning

You cannot close the write index of a data stream. To update the analyzer for a data stream's write index and future backing indices, update the analyzer in the index template used by the stream. Then roll over the data stream to apply the new analyzer to the stream's write index and future backing indices. This affects searches and any new data added to the stream after the rollover. However, it does not affect the data stream's backing indices or their existing data.

To change the analyzer for existing backing indices, you must create a new data stream and reindex your data into it. See Use reindex to change mappings or settings.