Match phrase query

Use the match_phrase query to match documents that contain an exact phrase in a specified order. You can add flexibility to phrase matching by providing the slop parameter.

The match_phrase query creates a phrase query that matches a sequence of terms.

The following example shows a basic match_phrase query:

GET _search
{
  "query": {
    "match_phrase": {
      "title": "the wind"
    }
  }
}

copy

To pass additional parameters, you can use the expanded syntax:

GET _search
{
  "query": {
    "match_phrase": {
      "title": {
        "query": "the wind",
        "analyzer": "stop"
      }
    }
  }
}

copy

Example

For example, consider an index with the following documents:

PUT testindex/_doc/1
{
  "title": "The wind rises"
}

copy

PUT testindex/_doc/2
{
  "title": "Gone with the wind"
}

copy

The following match_phrase query searches for the phrase wind rises, where the word wind is followed by the word rises:

GET testindex/_search
{
  "query": {
    "match_phrase": {
      "title": "wind rises"
    }
  }
}

copy

The response contains the matching document:

Response

{
  "took": 30,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.92980814,
    "hits": [
      {
        "_index": "testindex",
        "_id": "1",
        "_score": 0.92980814,
        "_source": {
          "title": "The wind rises"
        }
      }
    ]
  }
}

Analyzer

By default, when you run a query on a text field, the search text is analyzed using the index analyzer associated with the field. You can specify a different search analyzer in the analyzer parameter. For example, the following query uses the english analyzer:

GET testindex/_search
{
  "query": {
    "match_phrase": {
      "title": {
        "query": "the winds",
        "analyzer": "english"
      }
    }
  }
}

copy

The english analyzer removes the stopword the and performs stemming, producing the token wind. Both documents match this token and are returned in the results:

Response

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 0.19363807,
    "hits": [
      {
        "_index": "testindex",
        "_id": "1",
        "_score": 0.19363807,
        "_source": {
          "title": "The wind rises"
        }
      },
      {
        "_index": "testindex",
        "_id": "2",
        "_score": 0.17225474,
        "_source": {
          "title": "Gone with the wind"
        }
      }
    ]
  }
}

Slop

If you provide a slop parameter, the query tolerates reorderings of the search terms. Slop specifies the number of other words permitted between words in a query phrase. For example, in the following query, the search text is reordered compared to the document text:

GET _search
{
  "query": {
    "match_phrase": {
      "title": {
        "query": "wind rises the",
        "slop": 3
      }
    }
  }
}

The query still returns the matching document:

Response

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.44026947,
    "hits": [
      {
        "_index": "testindex",
        "_id": "1",
        "_score": 0.44026947,
        "_source": {
          "title": "The wind rises"
        }
      }
    ]
  }
}

Empty query

For information about a possible empty query, see the corresponding match query section.

Parameters

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

GET _search
{
  "query": {
    "match_phrase": {
      "<field>": {
        "query": "text to search for",
        ... 
      }
    }
  }
}

copy

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