Regexp query

Use the regexp query to search for terms that match a regular expression. For more information about writing regular expressions, see Regular expression syntax.

The following query searches for any term that starts with any uppercase or lowercase letter followed by amlet:

GET shakespeare/_search
{
  "query": {
    "regexp": {
      "play_name": "[a-zA-Z]amlet"
    }
  }
}

Note the following important considerations:

• Regular expressions are applied to the terms (that is, tokens) in the field—not to the entire field.
• By default, the maximum length of a regular expression is 1,000 characters. To change the maximum length, update the index.max_regex_length setting.
• Regular expressions use the Lucene syntax, which differs from more standardized implementations. Test thoroughly to ensure that you receive the results you expect. To learn more, see the Lucene documentation.
• To improve regexp query performance, avoid wildcard patterns without a prefix or suffix, such as .* or .*?+.
• regexp queries can be expensive operations and require the search.allow_expensive_queries setting to be set to true. Before making frequent regexp queries, test their impact on cluster performance and examine alternative queries that may achieve similar results.
• The wildcard field type builds an index that is specially designed to be very efficient for wildcard and regular expression queries.

Matching terms instead of field values

A regexp query is not analyzed, but the field it searches might be. When a text field is indexed, the standard analyzer splits its value into lowercase terms, and the regular expression must match one of those terms. As a result, a pattern containing uppercase letters or spaces returns no results for a text field.

To try this, index a document into an index that uses dynamic mapping. The title field is mapped as text and has a title.keyword subfield:

PUT my-index/_doc/1?refresh=true
{
  "title": "Henry IV"
}

The title field contains the terms henry and iv, so the following query returns no results:

GET my-index/_search
{
  "query": {
    "regexp": {
      "title": "Henry.*"
    }
  }
}

To match the original field value, including its capitalization and spaces, search the keyword subfield:

GET my-index/_search
{
  "query": {
    "regexp": {
      "title.keyword": "Henry I.*"
    }
  }
}

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.0,
    "hits": [
      {
        "_index": "my-index",
        "_id": "1",
        "_score": 1.0,
        "_source": {
          "title": "Henry IV"
        }
      }
    ]
  }
}

If a regexp query returns no results, also check the following:

• The pattern must match the entire term. For example, hen does not match the term henry, but hen.* does.
• The ^ and $ anchors are not supported. For example, ^Henry.* does not match Henry IV in a keyword field. For more information, see Unsupported features.
• Matching is case sensitive by default. To match terms regardless of case, set case_insensitive to true. For example, henry iv matches Henry IV in the title.keyword field when case_insensitive is true.

Parameters

The query accepts the name of the field (<field>) as a top-level parameter:

GET _search
{
  "query": {
    "regexp": {
      "<field>": {
        "value": "[Ss]ample",
        ...
      }
    }
  }
}

The <field> accepts the following parameters. All parameters except value are optional.

If search.allow_expensive_queries is set to false, then regexp queries are not executed.