Match phrase query in Elasticsearch - Step-by-Step Execution

Concept Flow - Match phrase query

Receive query phrase

↓

Analyze phrase into tokens

↓

Search documents

↓

Check token order and proximity

↓

Return matching documents

The match phrase query takes a phrase, breaks it into words, then finds documents where these words appear in the same order and close together.

Execution Sample

Elasticsearch

{
  "query": {
    "match_phrase": {
      "message": "quick brown fox"
    }
  }
}

This query finds documents where the field 'message' contains the exact phrase 'quick brown fox' in order.

Execution Table

Step	Action	Input/Condition	Result/Output
1	Receive query	Phrase: 'quick brown fox'	Start processing
2	Analyze phrase	Split into tokens: ['quick', 'brown', 'fox']	Tokens ready for search
3	Search documents	Look for documents with tokens in order	Candidate documents identified
4	Check token order	Tokens must appear in sequence	Documents with 'quick' followed by 'brown' then 'fox' selected
5	Check proximity	Tokens must be adjacent (default slop=0)	Only exact phrase matches kept
6	Return results	Documents matching phrase	Final matching documents returned
7	End	No more steps	Query complete

💡 Query ends after returning documents that contain the exact phrase in order with no extra words between.

Variable Tracker

Variable	Start	After Step 2	After Step 4	Final
query_phrase	null	'quick brown fox'	'quick brown fox'	'quick brown fox'
tokens	[]	['quick', 'brown', 'fox']	['quick', 'brown', 'fox']	['quick', 'brown', 'fox']
candidate_docs	[]	[]	[docs with tokens in order]	[docs with exact phrase]

Key Moments - 2 Insights

Why does the query only return documents with the exact phrase and not documents with the words scattered?

Because the match phrase query checks that tokens appear in the exact order and adjacency (step 5 in execution_table), so scattered words do not match.

What happens if the phrase has extra spaces or punctuation?

The phrase is analyzed into tokens (step 2), so punctuation is removed and spaces separate tokens, ensuring the search matches the word sequence.

Visual Quiz - 3 Questions

Look at the execution table, what tokens are created after analyzing the phrase?

A ['quick brown fox']

B ['fox', 'brown', 'quick']

C ['quick', 'brown', 'fox']

D ['quick', 'fox']

💡 Hint

Check Step 2 in the execution_table where phrase is split into tokens.

At which step does the query ensure tokens appear in the correct order?

A Step 3

B Step 4

C Step 5

D Step 6

💡 Hint

Look at Step 4 in execution_table where token order is checked.

If the slop parameter was increased, how would the execution_table change?

A Step 5 would allow tokens to be farther apart

B Step 2 would create more tokens

C Step 4 would ignore token order

D Step 6 would return no documents

💡 Hint

Slop affects proximity check in Step 5.

Concept Snapshot

Match phrase query syntax:
{
  "query": {
    "match_phrase": { "field": "phrase" }
  }
}

Behavior: Finds documents where words appear in exact order and adjacency.
Key rule: Tokens must be in sequence with no extra words between (default slop=0).

Full Transcript

The match phrase query in Elasticsearch takes a phrase and searches documents where the phrase appears exactly as given. First, the phrase is split into tokens (words). Then Elasticsearch searches for documents containing these tokens in the same order and next to each other. This ensures only documents with the exact phrase match are returned. The process ends after returning these matching documents. Key points include tokenizing the phrase and checking token order and proximity. Increasing slop allows some words between tokens but by default, the phrase must be exact.