How to Use Completion Suggester in Elasticsearch for Fast Autocomplete

Use the completion suggester in Elasticsearch by defining a completion field in your index mapping and then querying it with a _search request using the suggest section. This enables fast prefix-based autocomplete suggestions for user input.

Syntax

The completion suggester requires a special completion field type in your index mapping. When querying, you use the suggest section in your search request with a name for the suggestion, the prefix to match, and the completion field to search.

Key parts:

• Mapping: Define a field with type: completion.
• Query: Use suggest with a name, prefix, and completion field.
• Size: Limits number of suggestions returned.

json

{
  "mappings": {
    "properties": {
      "title_suggest": {
        "type": "completion"
      }
    }
  }
}


{
  "suggest": {
    "song-suggest": {
      "prefix": "nir",
      "completion": {
        "field": "title_suggest",
        "size": 5
      }
    }
  }
}

Example

This example shows how to create an index with a completion field, add documents with suggest data, and query for autocomplete suggestions starting with "nir".

json

PUT /music
{
  "mappings": {
    "properties": {
      "title": { "type": "text" },
      "title_suggest": { "type": "completion" }
    }
  }
}

POST /music/_doc/1
{
  "title": "Nirvana - Smells Like Teen Spirit",
  "title_suggest": {
    "input": ["Nirvana"]
  }
}

POST /music/_doc/2
{
  "title": "Nirvana - Come As You Are",
  "title_suggest": {
    "input": ["Nirvana"]
  }
}

POST /music/_doc/3
{
  "title": "Nickelback - How You Remind Me",
  "title_suggest": {
    "input": ["Nickelback"]
  }
}

GET /music/_search
{
  "suggest": {
    "song-suggest": {
      "prefix": "nir",
      "completion": {
        "field": "title_suggest",
        "size": 3
      }
    }
  }
}

Output

{
  "suggest": {
    "song-suggest": [
      {
        "text": "nir",
        "offset": 0,
        "length": 3,
        "options": [
          {
            "text": "Nirvana",
            "_index": "music",
            "_id": "1",
            "_score": 1.0
          },
          {
            "text": "Nirvana",
            "_index": "music",
            "_id": "2",
            "_score": 1.0
          }
        ]
      }
    ]
  }
}

Common Pitfalls

• Missing completion field in mapping: The suggester only works if the field is mapped as completion.
• Not indexing suggest data: You must provide the suggest input data when indexing documents.
• Using analyzed text fields: Completion suggester requires keyword or completion type, not analyzed text.
• Ignoring prefix length: Very short prefixes may return too many results or none if not indexed properly.

json

{
  "mappings": {
    "properties": {
      "title_suggest": { "type": "text" }  
    }
  }
}

// Wrong: Using text type instead of completion

{
  "suggest": {
    "song-suggest": {
      "prefix": "nir",
      "completion": {
        "field": "title_suggest"
      }
    }
  }
}

// Right: Use completion type in mapping
{
  "mappings": {
    "properties": {
      "title_suggest": { "type": "completion" }
    }
  }
}

Quick Reference

Step	Description	Example
1	Define completion field in mapping	"title_suggest": { "type": "completion" }
2	Index documents with suggest data	"title_suggest": { "input": ["Nirvana"] }
3	Query with suggest and prefix	{"suggest": {"song-suggest": {"prefix": "nir", "completion": {"field": "title_suggest"}}}}
4	Set size to limit suggestions	"size": 5

Key Takeaways

Define a field with type completion in your index mapping to enable autocomplete.

Index documents with suggest input data in the completion field.

Use the suggest section in your search query with prefix and completion field to get suggestions.

Avoid using analyzed text fields for completion suggester; use completion type instead.

Set the size parameter to control how many suggestions are returned.