Before we can understand edge n-grams specifically, we need to understand the more general idea they belong to: an n-gram. In text processing, an n-gram is simply a contiguous slice of a fixed length, “n,” taken from a longer piece of text. If you slice the word “search” into n-grams of length 3 (called trigrams), you get: “sea,” “ear,” “arc,” “rch” — every possible 3-character window, sliding one character at a time across the whole word. This is a general-purpose technique used across search engines, spell-checkers, and even DNA sequence analysis, wherever you need to find partial matches inside larger strings.

An edge n-gram is a deliberately narrowed, more useful special case of this general idea. Instead of generating every possible sliding window across a word, an edge n-gram generates only the windows that start from the beginning (the “edge”) of the word, growing one character at a time. Take the word “search” and generate edge n-grams with a minimum length of 2 and a maximum length of 6: you get “se,” “sea,” “sear,” “searc,” and “search” — five fragments, every one of them anchored to the start of the word, each one character longer than the last.

Why does this matter for search? Because when a user types into a search box character by character, what they’re producing, one keystroke at a time, is precisely a growing prefix of the word they’re aiming for. If Elasticsearch has already pre-computed and indexed every possible prefix of every word in your dataset — using edge n-grams at index time — then answering “what matches what the user has typed so far” becomes a simple, fast, exact-match lookup against that pre-computed set of prefixes, rather than an expensive pattern-matching operation performed fresh on every keystroke. This is the entire reason edge n-grams exist: they trade a modest amount of extra work and storage at index time for dramatically faster, more predictable query performance at search time — precisely the kind of trade-off that matters enormously for a feature that needs to feel instantaneous on every single keystroke a user makes.

It’s worth situating edge n-grams alongside the other prefix-matching tools we’ve encountered elsewhere in Elasticsearch, since beginners often reach for the wrong one. A prefix query or a leading-anchored wildcard query can answer “does this stored value start with what I typed?” at query time, without any special indexing — but, as covered in dedicated articles on those topics, this requires scanning the term dictionary at the moment of the query, which becomes measurably slower as data grows. Edge n-grams take the opposite approach: do the expensive slicing work once, at index time, and make every subsequent query a trivially fast, exact-match lookup. This is precisely why nearly every large-scale, snappy autocomplete experience you’ve ever used — whether searching a product catalog, a code repository, or a city name in a travel app — is built on some variation of the edge n-gram technique rather than on live prefix or wildcard queries.

The parameter that deserves the most careful attention is max_gram, because it directly controls how many fragments get generated — and therefore how large your index grows — per word. A word of 10 characters with min_gram: 2 and max_gram: 10 produces nine separate fragments (lengths 2 through 10). Multiply that by every word in every document across a large dataset, and you can see how a seemingly small configuration number has an outsized, multiplicative effect on total index size. This is why production teams almost always cap max_gram at a deliberately modest value — commonly somewhere between 10 and 20 — reasoning that once a user has typed that many characters, a live query-time match against the remaining full word is fast enough anyway, and pre-computing fragments beyond that point offers rapidly diminishing returns for a rapidly growing storage cost.

Choosing between the tokenizer form and the token filter form of edge n-gram is itself a small but meaningful design decision. Using the edge_ngram tokenizer directly means it’s the very first thing that touches your raw text, splitting on its own internal rules before any other processing happens — simple, but limiting if you need other normalization (like accent-folding or synonym expansion) to run beforehand. Using the edge_ngram token filter, layered after a standard tokenizer and any other filters in your analysis chain, is the more common and more flexible production choice, since it lets every other step of your text pipeline run first, with edge n-gram slicing applied last, right before tokens are written to the index — ensuring the fragments themselves are already lowercased, normalized, and otherwise consistent with however the rest of your search stack expects terms to look.

flowchart TD
    A["Raw word: 'search'"] --> B[edge_ngram tokenizer
min_gram: 2, max_gram: 5]
    B --> C1["'se'"]
    B --> C2["'sea'"]
    B --> C3["'sear'"]
    B --> C4["'searc'"]
    C1 & C2 & C3 & C4 --> D[Each fragment stored as its
own separate term in the inverted index]
        

Perhaps the single most important architectural decision, easy to overlook, is that a field using edge n-grams almost always needs two different analyzers — one used only when indexing documents, and a completely different one used only when running a search query against that field. We’ll unpack exactly why this asymmetry is necessary, and what goes wrong when it’s forgotten, in the next chapter.

To understand why edge n-grams require this unusual “two different analyzers” setup, we need to trace precisely what happens on both sides of a search: what happens when a document is indexed, and separately, what happens when a search query is executed against it.

At index time, when a document containing the word “search” is indexed into a field configured with an edge n-gram analyzer, Elasticsearch runs the field’s value through the full analysis chain — typically lowercasing it first, then applying the edge n-gram tokenizer, producing the full set of prefix fragments: “se,” “sea,” “sear,” “searc,” “search” (using our earlier example range). Every one of these fragments is written into the field’s inverted index as its own separate, independently searchable term, each pointing back to the same original document.

At search time, here’s the critical, easily-missed detail: you do not want to run the user’s typed query through the same edge n-gram analyzer. If you did, and a user typed “sea,” the search-time analyzer would itself generate edge n-grams of “sea” — namely “se” and “sea” — and Elasticsearch would then search for documents matching any of those query-side fragments. Since “se” is a very short, extremely common fragment likely to appear as a prefix-fragment inside thousands of unrelated words, this produces a flood of irrelevant matches and meaningfully hurts relevance quality. The correct, standard approach is to analyze the search-time query with an ordinary standard analyzer (or whichever plain-word analyzer fits your language), which simply lowercases and tokenizes “sea” into the single whole term “sea” — no slicing at all — and then searches for that one term against the field’s already-pre-sliced index.

Once the search-time term (“sea,” analyzed as a single whole term) is ready, matching it against the field’s pre-sliced index is functionally identical to any ordinary term-level lookup: Elasticsearch checks whether “sea” exists as an exact entry in that field’s term dictionary. Because “sea” was already written into that dictionary during indexing (as one of “search”‘s own pre-computed edge fragments), the match is found immediately — no scanning, no pattern automaton, none of the term-dictionary-walking cost we saw with wildcard queries in a related article. This is precisely the performance payoff edge n-grams are designed to deliver: all the genuinely expensive work happens once, at write time, amortized across every future search, rather than being repeated, unnecessarily, on every single keystroke a user ever types.

There’s a scoring subtlety worth understanding too. Because a longer word like “search” produces several fragments (“se,” “sea,” “sear,” “searc,” “search”), and each fragment is written as its own term, a document’s field technically now contains multiple terms where it originally held one word. This affects term-frequency-based relevance calculations in a way that’s usually harmless but occasionally surprising: a short query like “se” might match an enormous number of documents (since “se” is a prefix of thousands of unrelated words across a large dataset), while a longer, more specific query naturally narrows the candidate set simply because fewer stored words share that longer prefix. This is precisely why most production implementations pair edge n-gram matching with an additional relevance signal — exact-match boosting, popularity weighting, or field-length normalization — rather than relying on raw fragment-match scoring alone to produce a genuinely useful ranking of suggestions.

Let’s trace the complete, end-to-end journey of an edge-n-gram-powered autocomplete feature, from the moment a document is first indexed to the moment a user sees a live suggestion drop into a dropdown list.

This lifecycle also explains a subtlety that surprises engineers migrating an existing dataset onto edge n-grams for the first time: because the fragments are generated at index time, turning on edge n-gram matching for an already-populated index requires reindexing every existing document, exactly as discussed for dynamic template corrections in a related article — a field’s analyzer configuration cannot simply be edited in place on data that’s already been written. Teams typically create a new index with the corrected analyzer settings, reindex historical data into it, and switch traffic over via an alias, rather than attempting to modify a live field’s analysis behavior after the fact.

Worth noting too is what happens on the client side of steps 3 through 6, since the perceived speed of an autocomplete feature depends on more than just Elasticsearch’s own query latency. Network round-trip time, client-side rendering, and any debounce delay intentionally added before firing a request all stack on top of Elasticsearch’s near-instant lookup time. This is precisely why edge n-grams alone aren’t a complete autocomplete solution — they solve the server-side matching problem extremely well, but a genuinely snappy end-to-end experience still requires sensible client-side engineering around when requests are fired and how quickly results are rendered once they arrive, a pairing of concerns that shows up repeatedly across the production examples in Chapter 10.

It’s worth naming the underlying trade-off in more general engineering terms, because it recurs throughout Elasticsearch and throughout distributed systems generally: this is a classic instance of trading space for time. You accept a larger, more expensive-to-store index in exchange for a smaller, more predictable per-query cost. Whether that trade-off is worth making depends entirely on your actual traffic pattern — a field searched constantly, by many concurrent users, on every keystroke, is an excellent candidate for this trade, since the space cost is paid once while the time savings are collected on every single request thereafter. A field searched rarely, by a small number of internal operators, is a much weaker candidate, since the storage cost is paid continuously while the time savings are collected only occasionally — in that scenario, a live prefix or wildcard query, accepted as slightly slower per request, may genuinely be the more sensible overall choice.

Edge n-grams don’t introduce a classic access-control or data-exposure vulnerability in the way some features might — the security conversation here is really about resource consumption, both at index time (storage cost) and, in specific misconfigurations, at query time (relevance and load).

The most direct risk is simply an uncontrolled index size explosion. If max_gram is set too high — say, 30 or 40 — on a field containing long, free-form text (like full product descriptions rather than short names), the number of generated fragments per document can balloon dramatically, since fragment count grows linearly with word length up to the configured ceiling, multiplied across every word in every document. In severe misconfigurations, this can multiply an index’s on-disk size several-fold compared to the same data indexed without edge n-grams, directly increasing storage cost, memory pressure for caching, and the time required for routine operations like snapshots and reindexing. This is a genuine operational risk worth treating with the same seriousness as the mapping-explosion concern covered in the dynamic templates article — both are cases where a small, easy-to-overlook configuration choice compounds unpredictably at scale.

A second, more subtle concern involves the search-time misconfiguration discussed in Chapter 3 — accidentally applying the edge n-gram analyzer to user queries instead of a standard analyzer. Beyond the relevance degradation already covered, this misconfiguration also means every user query itself gets sliced into multiple sub-terms before matching, multiplying the number of term lookups performed per query. On a very large, high-traffic autocomplete endpoint, this avoidable extra work — repeated on every keystroke, for every concurrent user — can measurably increase cluster load compared to the correctly configured, single-term-per-query alternative, making the two-analyzer setup as much a resource-discipline practice as a relevance-quality one.

Because the cost of edge n-grams is largely invisible from the query side — a well-configured search feels instant regardless of how much storage it’s quietly consuming — production teams rely on a specific set of tools to keep the underlying cost visible and under control.

A practical habit worth adopting is running the Analyze API against representative sample text before deploying any change to an edge n-gram field’s configuration — exactly the same “test with a scratch index before touching production” discipline recommended for dynamic templates — since the visible symptom of a wrong min_gram/max_gram value (a search box that feels slightly “off,” matching too broadly or too narrowly) is often far more subtle and far slower to notice in production than the storage or relevance cost it’s quietly imposing the entire time it goes unfixed.

Proven Patterns

Anti-patterns to Avoid

Edge n-grams sit quietly behind some of the most familiar search experiences on the internet — precisely because so many products depend on a search box that feels instantly responsive as a core, expected part of their user experience.

An edge n-gram is a text analysis technique that slices words into every possible fragment anchored to their starting character — “s,” “se,” “sea,” “sear,” and so on — and stores each fragment as its own independently searchable term at index time. This turns the otherwise expensive problem of “match whatever the user has typed so far” into a fast, predictable, exact-term lookup at query time, which is precisely why edge n-grams sit behind so many of the instant, keystroke-responsive search experiences used across e-commerce, developer tools, travel platforms, and enterprise search alike. The technique’s real cost — increased index size, and the need for a carefully configured asymmetric pair of index-time and search-time analyzers — is well understood and manageable once you know exactly what to watch for.

None of this requires memorizing every internal detail of how Lucene stores its term dictionaries. What it requires is the mental model this article has built from the start: think of edge n-grams as pre-chopping every ingredient long before the dinner rush begins, so that when the order finally comes in — one keystroke at a time — the kitchen has nothing left to do but plate what’s already prepared. Configure the range deliberately, keep the search-time analyzer separate and simple, and scope the technique to the fields that genuinely need it, and an edge n-gram field becomes exactly what it should be: the quiet, unglamorous preparation work behind a search experience that feels effortless.

As with every technique covered across this series — dynamic templates for mapping control, wildcard queries for ad-hoc pattern matching, and now edge n-grams for prefix-driven autocomplete — the underlying lesson is consistent: Elasticsearch rewards engineers who think ahead about the actual shape of their data and their queries, rather than treating every feature as a drop-in default to be applied uniformly. Edge n-grams are a genuinely powerful tool exactly where they fit — short, high-traffic, keystroke-driven search fields — and a genuinely wasteful one where they don’t. Knowing the difference, and configuring accordingly, is what turns a feature like this from a clever trick into dependable, well-understood production infrastructure.