Multi-Fields in Elasticsearch: One Piece of Data, Many Ways to Search It
A complete, zero-prior-knowledge walkthrough of what multi-fields are, why Elasticsearch needs them, how they work under the hood, and how real companies use them to make search fast, flexible, and accurate.
Imagine you own a single photograph of yourself. One print is framed and hung on the wall for guests to admire — nice to look at, but you can’t fold it into your wallet. Another copy is a small wallet-sized print — convenient to carry, but too small to appreciate the detail. A third copy is a digital scan you use to search “photos of me” on your phone. It is the same moment in time, the same face, the same photograph — yet you keep it in different forms because each form serves a different purpose. Elasticsearch faces this exact dilemma with the text you store in it, and its answer to that dilemma is a feature called multi-fields. This guide explains, from the very first principle, what multi-fields are, why they exist, how Elasticsearch builds and uses them internally, and how to use them well in real production systems.
Before we can understand multi-fields, we need to agree on what a “field” is in Elasticsearch, and why one single way of storing text is never enough.
What is a field, really?
In Elasticsearch, every piece of information you store — a product name, a customer’s city, a blog post’s body — lives inside something called a document, and each individual piece of information inside that document is called a field. Think of a document as a single row in a spreadsheet, and a field as one column in that row. If you are storing a product, “name,” “price,” and “category” would each be a field.
But unlike a spreadsheet cell, an Elasticsearch field is not stored as one plain, untouched copy of your text. Behind the scenes, Elasticsearch decides how to break your text apart, normalize it, and organize it into something called an inverted index — a structure that lets it find, in milliseconds, every document that contains a particular word, even across billions of documents. The way Elasticsearch decides to break apart and organize a field is called its mapping, and the mapping is chosen based on a field type — the most common being text (meant for full sentences that should be searchable by individual words) and keyword (meant for exact values like a status code or an email address that should be matched as a whole, never broken into pieces).
Think about the word “New York.” As a text field, Elasticsearch would break it into two separate searchable pieces: “new” and “york,” so a search for just “york” would still find it — exactly like how a librarian who indexes a book by individual words would let you find a page by searching any single word on it. As a keyword field, “New York” is treated as one indivisible label, like a barcode: you either scan the whole barcode correctly, or you get no match at all. The problem is, sometimes you want the librarian’s behavior, and sometimes you want the barcode’s behavior — on the exact same value.
So what is a multi-field?
A multi-field is Elasticsearch’s solution to needing both behaviors at once, without storing the data twice as a human would. When you define a multi-field, you tell Elasticsearch: “Take this one field’s value, and in addition to indexing it your normal way, also index a second (or third, or fourth) version of it, using a different set of rules.” Each of these additional versions is called a sub-field, and it is accessed using dot notation, such as product_name.keyword or title.english.
Crucially, you are not duplicating the raw value in the document source that gets stored and returned to you — the original JSON document you sent to Elasticsearch is stored exactly once, untouched, inside something called the _source. What multi-fields duplicate is only the indexed, searchable representation of that value — the specialized structures Elasticsearch builds so it can answer queries quickly. This distinction matters enormously, and we will return to it in the chapter on internal working.
A multi-field is not a new field with a new name that you fill in separately. It is one field, with one value supplied by you, that Elasticsearch quietly indexes in more than one way so that different kinds of queries can each get the treatment they need.
Why does this problem even exist?
The need for multi-fields exists because “search” is not one single operation — it is a family of very different operations that happen to use the same word, “search,” in everyday conversation. When a shopper types “wireless mouse” into a search box, they want a broad, forgiving match: documents containing “wireless” or “mouse” or both, ranked by relevance, even if the product title says “Wireless Optical Mouse.” That is a text search. But when a dashboard needs to count how many products belong to the exact category “Electronics > Computer Accessories,” or when it needs to sort products alphabetically by their exact title, or build a dropdown filter listing every unique brand name, it needs exact, unbroken values grouped and compared character-for-character. That is a keyword operation, and it also powers aggregations (Elasticsearch’s term for statistics like counts, sums, and groupings) and sorting, both of which require an exact, non-tokenized value to compare against.
Before multi-fields existed as a first-class mapping feature, engineers had to manually send the same value twice under two different field names — once as title and once as title_raw, duplicating effort in every single application that wrote data. Multi-fields moved that responsibility into the mapping itself, so the duplication of indexing effort becomes automatic and consistent, no matter which application or pipeline is writing the data.
The “text” version
Breaks a sentence into individual words (tokens), lowercases them, and often removes filler words, so a partial or fuzzy phrase still matches.
The “keyword” version
Stores the entire value untouched (or lightly normalized) as one unit, ideal for filtering, sorting, and exact-value aggregations.
Let’s look at the pieces that make multi-fields work: the mapping definition, analyzers, the inverted index, and doc values.
The mapping: the blueprint for every field
Every Elasticsearch index has a mapping — a schema-like definition describing every field’s data type and indexing rules. Think of the mapping as the architectural blueprint of a building: it does not contain the furniture (your actual data), but it dictates exactly how each room (field) is built, what materials are used, and what purposes each room can serve. When a field is declared with sub-fields, that declaration lives entirely inside this blueprint; there is no separate “multi-field system” running elsewhere — it is simply a richer mapping definition for that one field.
Analyzers: the workers who process text
An analyzer is the component responsible for turning raw text into searchable tokens. It typically performs three jobs in sequence: a character filter (cleans up raw text, such as stripping HTML tags), a tokenizer (splits the text into individual words), and one or more token filters (transform each token, such as lowercasing, removing common words like “the” and “and,” or reducing words to their root form, called stemming, so “running” and “ran” both match “run”). Every sub-field in a multi-field can be assigned its own analyzer, which is precisely how the same value ends up indexed differently under each sub-field name.
Picture a fruit processing plant that receives one crate of oranges. One production line squeezes them into juice (this is like the text sub-field, breaking the fruit down into a different, more granular form). A second production line simply labels and boxes the whole oranges as-is for the produce aisle (this is like the keyword sub-field, keeping the item whole and exact). Both lines start from the very same crate — nothing was duplicated before the plant received it — but each line’s output serves a different customer need.
The inverted index and doc values: two different storage engines
Elasticsearch actually maintains two very different data structures depending on what kind of question you plan to ask:
- Inverted index: a structure that maps every unique token (word) to the list of documents containing it, similar to the index at the back of a textbook that lists a term and every page number it appears on. This is what powers full-text
textsearches. - Doc values: a column-oriented structure that, for every document, stores the field’s value in a format optimized for scanning down a single column quickly — similar to a spreadsheet column you can scroll straight down. This is what powers sorting, aggregations, and exact filtering, and is what
keywordsub-fields rely on by default.
A multi-field, in architectural terms, is really a way of telling Elasticsearch to build both of these structures for the same underlying value, under two different addressable names, rather than forcing you to pick only one structure for the whole field.
flowchart TB
A["Incoming Document Field
e.g. product_name = 'Wireless Optical Mouse'"] --> B["Mapping Definition
(the blueprint)"]
B --> C["Sub-field: product_name
type: text"]
B --> D["Sub-field: product_name.keyword
type: keyword"]
C --> E["Standard Analyzer
tokenize + lowercase"]
D --> F["No analysis
(kept whole)"]
E --> G["Inverted Index
wireless, optical, mouse"]
F --> H["Doc Values Column
'Wireless Optical Mouse'"]
G --> I["Powers: full-text search,
relevance ranking, fuzzy match"]
H --> J["Powers: sorting, aggregations,
exact filtering"]
“What is the architectural difference between an inverted index and doc values, and why does Elasticsearch need both?” — A strong answer explains that the inverted index is row-oriented per term (optimized for “which documents contain this word”), while doc values are column-oriented per field (optimized for “what is this field’s value across many documents, in order”), and that trying to sort or aggregate using only an inverted index would be prohibitively slow.
Let’s trace, step by step, exactly what Elasticsearch does the instant a document containing a multi-field arrives.
Document arrives and is parsed
Elasticsearch receives the JSON document and reads each field’s raw value against the index’s mapping to determine how it should be processed.
The multi-field declaration is detected
When the mapping shows that a field has one or more sub-fields defined under a “fields” section, Elasticsearch knows this single value must be processed more than once.
The original _source is stored once
The full, unmodified JSON document — exactly as it was sent — is compressed and stored once as the “_source.” This is what gets returned to you when you retrieve a document; it is never duplicated per sub-field.
Each sub-field runs its own analysis pipeline independently
The primary field and every declared sub-field each run through their own configured analyzer (or lack of one, for keyword fields), completely independently of one another.
Each resulting structure is written to its own segment data
The tokens from a text analysis go into that sub-field’s inverted index; the exact value for a keyword sub-field goes into that sub-field’s doc values structure. These are physically separate on disk, addressed by their distinct field names.
The document becomes searchable at the next refresh
On the next index “refresh” (by default roughly every second), the newly written data becomes visible to search queries against any of the sub-fields.
People often assume multi-fields double the size of your stored documents. They do not duplicate the _source. What they add is extra index structures (inverted index entries and/or doc values) for each additional sub-field, which does increase overall index size on disk, but by a far smaller amount than duplicating whole documents would.
Why sub-fields cannot be searched or updated independently of the parent value
Because a sub-field is not an independent field with its own input value — it is purely a different indexing strategy applied to the same input — you cannot supply a different value to title and title.keyword when writing a document. You provide the value once, under the parent field’s name, and Elasticsearch fans it out internally to every sub-field automatically. This is precisely why multi-fields are said to give you “many ways to search the same data” rather than “many separate pieces of data.”
Multi-fields do not only matter at write time — their presence shapes how a query travels through Elasticsearch at read time too.
The query-time journey
When your application sends a search request, it must choose which field name to query against — and that choice determines which underlying structure gets consulted. A request that targets the plain description field will be evaluated against the inverted index built by that field’s analyzer, matching individual tokens and computing a relevance score based on how well the query terms match. A request that targets description.keyword, on the other hand, is evaluated as an exact string comparison, with no analysis or partial matching involved at all.
This means the very same underlying data value can produce completely different search results depending purely on which sub-field name your query happens to reference — a detail that trips up many newcomers to Elasticsearch, and one worth internalizing deeply.
A Concrete Walk-Through
Suppose a document has brand: "Acme Corp". A query against brand for the single word “acme” will match, because the analyzer tokenized the value into “acme” and “corp.” A query against brand.keyword for “acme” will not match, because the doc-values copy holds the full, untouched string “Acme Corp,” and only an exact match of that entire string (case-sensitive, by default) will succeed. Both queries are legitimate — they simply answer different questions.
Lifecycle across reindexing and mapping changes
Multi-field sub-fields are defined once, at mapping creation time, and in most cases cannot be added retroactively to already-indexed data without a reindex — the process of reading every existing document and writing it into a new index that has the updated mapping. This is because the sub-field’s index structures need to be built from the analyzer’s output, and Elasticsearch cannot manufacture that output for documents that were indexed before the sub-field existed. Planning your multi-fields at index-design time, rather than retrofitting them under production load, is therefore one of the most valuable habits an Elasticsearch practitioner can build.
raw _source
one per sub-field
without a reindex
Like every engineering decision, multi-fields trade one resource for another. Understanding the trade honestly is what separates a competent design from a wasteful one.
Advantages
- One write path serves both full-text search and exact filtering/sorting/aggregation needs.
- No application-level duplication logic — the mapping guarantees consistency automatically.
- Different sub-fields can use different analyzers, enabling multilingual search (e.g., an English-stemmed sub-field alongside a raw sub-field) from the same source value.
- Keeps the original document (_source) clean and singular — no redundant sibling fields cluttering your schema.
- Query flexibility scales with your needs: add more sub-fields for more use cases without touching how the data is written.
Disadvantages & Trade-offs
- Extra disk usage: every sub-field builds its own index structures, growing overall index size.
- Extra indexing-time CPU cost: each sub-field’s analyzer (or lack of one) still has to run on every document write.
- Mapping complexity grows with every sub-field added, making schemas harder for new engineers to read at a glance.
- Cannot be added to already-indexed historical data without a full reindex.
- Overuse (adding sub-fields “just in case”) wastes resources for query patterns that never materialize.
The keyword-length trade-off
A particularly important, often-overlooked trade-off concerns keyword sub-fields and very long text. By default, a keyword type has an ignore_above consideration: exceptionally long strings are simply not indexed into the keyword structure at all (though they remain in _source), specifically to avoid the doc-values structure ballooning in size from pathologically long outlier values, such as an entire paragraph accidentally landing in a field meant for short labels. Designing sensible limits here is part of using multi-fields responsibly at scale.
Multi-fields themselves are not a security feature, but the way they expose data does have quiet security implications worth understanding.
Field-level access control still applies per sub-field
Elasticsearch’s field-level security (available in security-enabled deployments) can restrict which fields a given role is allowed to see. Because a sub-field like ssn.keyword is addressed by its own distinct name, it must be explicitly included in any field-level security pattern if you intend to hide it — a rule written only against ssn will not automatically also cover ssn.keyword unless your pattern is broad enough (such as a wildcard) to capture it. Teams that forget this can end up in a situation where the “safe” analyzed field is hidden from a role, but the raw, exact keyword sub-field of the very same sensitive value remains fully queryable and aggregatable by that same role.
An aggregation on a keyword sub-field can leak exact values through bucket names, even if free-text search on the parent field feels “safe” because it only returns relevance-ranked, tokenized hits. Always audit both the analyzed field and every one of its sub-fields when reviewing what a role can see or infer.
Data minimization at mapping-design time
Because every sub-field increases the surface area of what is indexed and therefore potentially discoverable through search or aggregation, sensitive fields (personally identifiable information, financial data, credentials) should only receive the sub-fields that are strictly required by a legitimate use case, rather than being given a broad set of sub-fields defensively “for flexibility.”
Once multi-fields are in production, how do you know they are healthy, correctly used, and not silently wasting resources?
What to watch
- Index size growth per field: tools that break down disk usage by field can reveal that a rarely-queried sub-field is consuming disproportionate space, signaling it may be a candidate for removal.
- Field usage statistics: Elasticsearch can report which fields are actually being touched by queries and aggregations over a recent time window, which is the most reliable way to discover “dead” sub-fields nobody queries anymore.
- Mapping explosion: a rapidly growing total field count (including sub-fields) across an index is a warning sign of uncontrolled schema growth, sometimes from dynamic mapping combined with multi-fields being applied indiscriminately.
- Indexing latency and throughput: a sudden slowdown after adding new sub-fields to a heavily-written index is a signal that the added analysis work has meaningfully increased per-document indexing cost.
Practical Habit
Periodically reviewing field usage statistics against your mapping is the single most effective way to catch multi-field sprawl before it becomes an expensive cluster-wide habit, especially in organizations where many teams add fields to a shared index over time.
Certain multi-field patterns show up again and again across well-run Elasticsearch deployments — and so do certain mistakes.
Established patterns
text + keyword
The most universal pattern: a full-text analyzed field alongside an exact keyword sub-field, covering both free-text search and sorting/aggregation/filtering.
Multi-language sub-fields
A base field plus per-language sub-fields (e.g., title.en, title.fr), each using a language-specific analyzer for stemming and stop-words.
Search-as-you-type sub-field
An additional sub-field analyzed with edge n-grams (partial word prefixes) to power autocomplete-style suggestions alongside normal full-text search.
Phonetic sub-field
A sub-field indexed with a phonetic analyzer so misspelled or phonetically similar names (e.g., “Smith” vs “Smyth”) can still be found.
Anti-patterns to avoid
Speculative Sub-Fields
Adding a keyword, an analyzed, a search-as-you-type, and a phonetic sub-field to every text field “just in case a future feature needs it,” without a concrete query pattern driving the decision.
Why It Hurts
Each unused sub-field still costs disk space and indexing CPU on every single document write, forever, with zero query-time benefit until (if ever) the speculative use case materializes.
Aggregating on an Analyzed Field
Attempting to run a terms aggregation directly on a plain text field instead of its .keyword sub-field.
Why It Hurts
A text field is not designed to support this efficiently by default and the resulting buckets are usually meaningless individual word fragments rather than the whole values you actually wanted grouped.
A short, practical checklist distilled from how mature Elasticsearch users design their mappings.
| Best Practice | Why It Matters |
|---|---|
Add a .keyword sub-field only to fields you will actually sort, filter, or aggregate on exactly. | Avoids paying indexing and storage cost for structures nobody queries. |
| Set a reasonable length limit on keyword sub-fields for free-text-heavy fields. | Prevents outlier long values from bloating the doc-values structure unnecessarily. |
| Choose analyzers deliberately per sub-field rather than accepting defaults everywhere. | Default analyzers are general-purpose; your domain (product names, medical terms, legal text) often benefits from tailored tokenization. |
| Design your full multi-field set before heavy production writes begin. | Adding sub-fields later usually requires a full reindex of historical data. |
| Periodically audit field usage statistics. | Surfaces unused sub-fields that can be safely retired. |
Forgetting that dynamic mapping (Elasticsearch automatically guessing a field’s type from the first document it sees) often creates a text field with an automatic .keyword sub-field by default. Relying on this default without reviewing it can silently produce sub-fields you never intended, or miss ones you actually need with custom analyzers.
Multi-fields are not an academic curiosity — they sit quietly behind search experiences used by millions of people every day.
E-Commerce Product Catalogs (Netflix-scale retail platforms)
A large online retailer typically needs shoppers to type loose, misspelled, partial product names into a search bar (full-text search), while simultaneously needing the exact same product-name value available for building “Brand: Sony (1,204)” style faceted filters in the sidebar, and for sorting a category page alphabetically by product title. A single text + keyword multi-field on the product name field cleanly satisfies both needs from one written value.
Log & Observability Platforms (Uber-scale infrastructure teams)
Engineering teams ingesting massive volumes of application logs commonly store a message field as analyzed text so engineers can free-text search “connection timeout” across billions of log lines, while also keeping fields like host.name or service.name as keyword-heavy multi-fields so dashboards can aggregate error counts per exact host or service without ambiguity from partial word matches.
Global Streaming Content Search (large media platforms)
A media platform offering content in multiple languages commonly uses multi-language sub-fields on a title field — one sub-field stemmed and stopword-filtered per supported language — so that a search for a show title returns strong, relevant matches regardless of a viewer’s language settings, all derived from the same single title value stored once per document.
Key Takeaways
- A multi-field lets one stored value be indexed in several different ways — most commonly as analyzed
textfor full-text search and as exactkeywordfor filtering, sorting, and aggregations. - The raw document is stored only once in
_source; multi-fields duplicate only the specialized search structures, not your original data. - Text search and exact matching rely on fundamentally different internal structures — the inverted index for tokenized text, and doc values for exact, sortable, aggregatable values.
- Sub-fields cannot be given separate values — they are always derived automatically from the one value you supply for the parent field.
- Adding sub-fields to already-indexed data usually requires a reindex, so multi-field design is best done up front, based on real query patterns.
- Every sub-field has a cost in disk space and indexing CPU, so the best practice is to add only the sub-fields a concrete use case genuinely needs, and to monitor field usage over time to retire ones that don’t.
- Field-level security must account for sub-fields explicitly, since hiding a parent field does not automatically hide its sub-fields.