How to Use Fuzzy Query in Elasticsearch for Approximate Matching

Use the fuzzy query in Elasticsearch to find documents that match terms approximately, allowing for typos or small differences. Specify the field and the value with optional parameters like fuzziness to control how much variation is allowed.

Syntax

The fuzzy query syntax requires specifying the field to search and the value to match approximately. You can add parameters like fuzziness to control allowed edits, prefix_length to require exact matches for the first characters, and max_expansions to limit query complexity.

json

{
  "query": {
    "fuzzy": {
      "FIELD_NAME": {
        "value": "SEARCH_TERM",
        "fuzziness": "AUTO",
        "prefix_length": 1,
        "max_expansions": 50
      }
    }
  }
}

Example

This example searches the title field for terms similar to roam, allowing for small typos. It uses fuzziness set to AUTO to automatically choose the edit distance.

json

{
  "query": {
    "fuzzy": {
      "title": {
        "value": "roam",
        "fuzziness": "AUTO",
        "prefix_length": 1
      }
    }
  }
}

Output

{
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "hits": [
      {"_source": {"title": "roam"}},
      {"_source": {"title": "foam"}}
    ]
  }
}

Common Pitfalls

• Not setting fuzziness or using a fixed number can lead to too many or too few matches.
• Using fuzzy queries on very short terms can cause unexpected results; use prefix_length to require exact matches at the start.
• Fuzzy queries can be slower because they expand many terms; limit max_expansions to improve performance.

json

{
  "query": {
    "fuzzy": {
      "title": {
        "value": "ro",
        "fuzziness": 2
      }
    }
  }
}

// Better:
{
  "query": {
    "fuzzy": {
      "title": {
        "value": "ro",
        "fuzziness": 1,
        "prefix_length": 1
      }
    }
  }
}

Quick Reference

Parameter	Description	Example
value	The term to search approximately	"roam"
fuzziness	Allowed edit distance (AUTO, 0, 1, 2)	"AUTO"
prefix_length	Number of initial characters that must match exactly	1
max_expansions	Max number of terms to expand for fuzzy matching	50

Key Takeaways

Use the fuzzy query to find terms with small typos or variations.

Set fuzziness to AUTO for automatic edit distance or specify 1 or 2 for control.

Use prefix_length to avoid matching very short or irrelevant terms.

Limit max_expansions to keep query performance reasonable.

Fuzzy queries work best on text fields with analyzed terms.