Elasticsearch full-text queries explained, for humans 🤓

Alex Sharp
Hacker Notes 💻
Published in
3 min readJan 29, 2019


These are my high-level notes from implementing basic autocomplete functionality with ElasticSearch.

Elasticsearch has several different query types. A quick summary:

  • match - standard full text query
  • match_phrase - phrase matching. Like when you put a term in quotes on google.
  • match_phrase_prefix - poor man’s autocomplete.
  • multi_match - Multi-field match.
  • common (not covered here) - Takes stopwords (e.g. “the”) into account.
  • query_string (not covered here) - Expert mode. Can use AND|OR|NOT and multi-field search in a query string.
  • simple_query_string (not covered here) - Simpler “more robust” for exposing to end-users. (how is simple more robust? seems counter-intuitive. no one knows.)

ElasticSearch full-text query docs

match - standard full text query

By default does near-exact word equality matching.

When to use: If you’re doing full-text search on a large text field, such as the body of this post.

Good default for matching a word or phrase in a block of text, e.g. searching in a large text field, description field, etc, such as searching for a phrase in someone’s Twitter bio.

Not good for partial matches of a single word or phrase, such as a partial match of someone’s Twitter username (see fuzziness below).

Fuzzy matching Allows fuzzy matching (e.g. typo tolerance) by specifying a levenstein edit distance, number of one character changes needed to make one string match another string. Basically, it’s the number of typos you can make and still match the string.

Example: Your target match data is a field with the value “ajsharp”. With the fuzziness param set to 1, you can type “jjsharp” and it will match “ajsharp”. But if you type “jssharp” it won’t match, unless you increase fuzziness to 2.

match_phrase - for matching exact phrases

When to use: If you need to be specific about whole phrase searches, or want to enable this functionality for your users.

Let’s say we have two twitter profiles indexed. Document A has the phrase “co-founder” in the bio, and Document B just has the word “founder”.

If you search “founder” using match_phrase, both documents will match. If you search “co-founder” using match_phrase, only Document A will match. However, had you done this query using match, both Document A and Document B would match the query “co-founder”

match_phrase_prefix - poor man’s autocomplete

When to use: Only you need to match a single field. For many use-cases multi_match feels far more useful.

From the ES docs:

Consider the query string quick brown f. This query works by creating a phrase query out of quick and brown (i.e. the term quick must exist and must be followed by the term brown). Then it looks at the sorted term dictionary to find the first 50 terms that begin with f, and adds these terms to the phrase query.

multi_match - multi-field match 🎉🎉🎉

Allows you to search for the same string in multiple fields.

When to use: In many cases this is probably what you need if you’re doing anything auto-completey (note: there are probably many uses cases this is great for but my primary one when I wrote this post was autocomplete, so 🤷🏻‍♂️).

Multi match queries can have a type:

  • best_fields. Default. Match any field, but uses the _score from the best field. Docs
  • most_fields - Matches any field and combines the score
  • cross_fields - Treats fields with same analyzer as if one big field.
  • phrase - Uses match_phrase
  • 🎉🎉🎉 phrase_prefix - Uses match_phrase_prefix on each field and combines the _score. Allows multi-field autocomplete 💥💥💥

Field Boosting Fields can be boosted by using the ^ followed by number. Assume twitter profiles with screen_name and name fields. If you do a query like this, the screen_name will be three times as important as the name field in the ranking:

🚀🚀🚀 Thanks for reading my development journal, where I write about things I learn while building products.

The product I’m currently building is Follow Reset, which makes it easy to clean up your Twitter by helping you prune who you follow. Subscribe here to get notified when it launches, or head to the website to learn more. 🙏🙏🙏



Alex Sharp
Hacker Notes 💻

🛠 building https://followreset.com. https://sharesecret.co. platform @upfrontvc. prev consultant, founding team @zaarly. long ago: health care tech, economics.