What Is a Field in Elasticsearch?
Every document is made of fields — and how you define each one quietly decides how fast, how flexible, and how accurate your entire search system will be.
If a document in Elasticsearch is like an index card describing one “thing” — a product, a log line, a customer — then a field is one line written on that card. It’s the smallest labeled piece of information you can store, search, filter, or sort by. Get fields right, and Elasticsearch feels instant and magical. Get them wrong — the wrong type, the wrong settings, too many of them — and the same system can feel slow, inaccurate, or even refuse to accept new data. This article breaks down exactly what a field is, how Elasticsearch treats it internally, and how to design fields the way production teams do.
1Core Concepts
A field is a single named piece of data inside a document — a key and its value, exactly like one property in a JSON object. If a document represents a book, then “title”, “author”, “price”, and “publish_date” are each individual fields. Every field has a name, a value, and — critically — a data type that tells Elasticsearch how to store and search that value.
Picture a printed form at a doctor’s office: “Name,” “Date of Birth,” “Blood Pressure,” “Allergies” are each a labeled box you fill in. The whole filled-out form is the document. Each individual labeled box — “Date of Birth” together with what you wrote in it — is a field. The form design itself, which decides that “Date of Birth” must be a date and “Blood Pressure” must be a number, is the mapping.
What it is: a named, typed piece of data — the atomic unit that Elasticsearch actually indexes, searches, filters, sorts, and aggregates on.
Why it exists: without breaking a document into individually typed fields, Elasticsearch couldn’t build efficient search structures for each piece of data, nor could it tell the difference between text meant for full-text search and a number meant for range filtering.
Where it’s used: everywhere — every query condition (“price > 50”, “title contains dragon”, “status = shipped”) targets a specific field, and every aggregation (“average price by category”) groups and calculates using field values.
A field is the Elasticsearch equivalent of a column in a relational database — except each document can have its own subset of fields, and a single field name can even map to different physical data structures depending on its declared type.
Field Name vs. Field Value vs. Field Type
It helps to separate three ideas that are easy to blur together. The field name is the label, like “price”. The field value is the actual data in one document, like 29.99. The field type is the rule that governs every value ever stored under that name across the entire index, like “this must always be a floating-point number.” The type is set once, in the mapping, and applies uniformly to that field name everywhere in the index.
2Architecture & Components
Every index has a mapping — a schema-like definition listing every known field name and its type. Unlike a rigid SQL schema, a mapping can grow over time as new fields appear, but each field, once defined, keeps a fixed type for the life of that index.
| Field Type | What It’s For | Example Value |
|---|---|---|
| text | Full-text search — analyzed into individual searchable words | “Wireless noise-cancelling headphones” |
| keyword | Exact match, filtering, sorting, aggregating — never broken into words | “IN_STOCK” |
| long / integer / short / byte | Whole numbers | 42 |
| float / double | Decimal numbers | 29.99 |
| date | Timestamps, supports range queries and date math | “2026-09-18T10:00:00Z” |
| boolean | True/false flags | true |
| object | A nested JSON sub-structure, flattened internally | {“street”: “5th Ave”, “city”: “NYC”} |
| nested | An array of objects, each queried as an independent unit | [{“sku”:”A1″},{“sku”:”A2″}] |
| geo_point | Latitude/longitude coordinates for distance and map queries | {“lat”: 40.7, “lon”: -74.0} |
Multi-fields
A single field can be indexed multiple ways at once — for example, “title” as analyzed text for search and “title.raw” as an unanalyzed keyword for exact sorting, both from the same source value.
Runtime Fields
Fields calculated on the fly at search time from a script, rather than stored on disk at index time — useful for occasional or experimental fields you don’t want to fully reindex for.
Metadata Fields
Built-in fields like _id, _index, and _source aren’t part of your data model, but behave like reserved system fields attached to every document.
Dynamic Fields
Fields Elasticsearch discovers and types automatically the first time it sees them in an incoming document, based on best-guess heuristics.
graph TD
A[Document JSON arrives] --> B{Field already
in mapping?}
B -- Yes --> C[Validate value against
existing field type]
B -- No --> D{Dynamic mapping
enabled?}
D -- Yes --> E[Guess type from value
e.g. string with digits -> keyword or text]
D -- No / strict --> F[Reject the document]
C --> G[Route value into correct
data structure per type]
E --> G
G --> H[(Inverted Index for text/keyword)]
G --> I[(Doc Values for sort/aggregate)]
3Internal Working
Behind the scenes, Elasticsearch doesn’t store a field just once — it can build up to three different internal structures for a single field, depending on how that field is used:
Inverted Index (for text & keyword)
Text fields are analyzed — lowercased, tokenized, sometimes stemmed — and every resulting word is added to a dictionary mapping words to the documents containing them, enabling fast full-text search.
Doc Values (for sorting & aggregating)
A separate, column-oriented structure is built on disk that stores each document’s value for a field in a compact, sequential format — perfect for operations like sorting by price or averaging a rating, which need to scan every value efficiently rather than look words up.
_source Storage
The field’s original, untouched value is also kept inside the document’s stored _source JSON, so it can be returned exactly as submitted in search results, regardless of how it was internally analyzed or indexed.
Think of a spice jar in a kitchen. The label on the jar (searchable by name — “cumin”) is like the inverted index. The jars lined up in alphabetical order on a shelf (letting you scan quickly from A to Z) is like doc values. And the original purchase receipt tucked in a drawer, showing exactly what you bought and when, is like _source — the untouched original record.
This is also why field type choice matters so much for text: a “text” field is broken into words and loses its exact original form for filtering purposes (you can’t reliably filter for the exact phrase “IN STOCK” against an analyzed field), while a “keyword” field is stored whole and exact, but can’t match individual words inside a sentence. Many production mappings use both, via multi-fields, precisely to get both behaviors from one source value.
Doc values are enabled by default for almost every field type because sorting and aggregating are so common — but they consume extra disk space. Fields you’re certain you’ll never sort or aggregate on can have doc_values explicitly disabled to save space.
4Data Flow & Lifecycle
Step 1 — First Appearance
The very first time Elasticsearch sees a new field name in an incoming document (and dynamic mapping is allowed), it inspects the value and guesses a type — a string might become “text” with a “keyword” sub-field automatically added, a number becomes “long” or “float”, and so on.
Step 2 — Locked-In Type
Once a field’s type is set — whether by dynamic guessing or explicit mapping — it cannot be changed for that index. Every future document must supply a compatible value, or the write is rejected.
Step 3 — Ongoing Use
From then on, every document indexed supplies a value for that field (or omits it), every search query can reference it, and every aggregation can summarize across it.
Step 4 — Changing a Field’s Type
If you genuinely need to change a field’s type (say, from “text” to “keyword”), you cannot edit the mapping in place. Instead, you create a brand-new index with the corrected mapping and reindex all existing documents into it — a common, well-understood operational pattern in Elasticsearch.
Fields are optional per document. If a document doesn’t include a “discount” field, that’s completely valid — Elasticsearch simply treats the field as absent for that document, and queries like “exists” or “missing” can specifically search for documents that do or don’t have a given field.
5Advantages, Disadvantages & Trade-offs
Advantages
- Fine-grained typing means each field is stored and indexed in the way best suited to how it will actually be queried.
- Multi-fields let one source value serve both full-text search and exact filtering without duplicating your data model.
- Dynamic mapping lets you get started quickly, without pre-declaring every field up front.
- Runtime fields allow experimentation with new calculated fields without a full reindex.
Disadvantages
- A field’s type is permanent once set — correcting a mistake requires reindexing into a new index.
- Dynamic mapping can guess wrong (for example, treating a phone number as a numeric type, breaking leading-zero values).
- Every unique field adds overhead to the cluster’s mapping metadata, which is held in memory on every node.
- Doc values and multiple representations of the same field (via multi-fields) increase disk usage.
The core trade-off with fields is between flexibility and control. Letting Elasticsearch dynamically create fields is fast to start with but risky at scale; explicitly mapping every field up front is more upfront effort but far safer and more predictable in production. Most mature systems start dynamic during prototyping, then “freeze” a reviewed, explicit mapping before going live.
6Security
Because a document might contain both harmless and highly sensitive fields side by side — like a customer document holding both “loyalty_tier” and “social_security_number” — Elasticsearch’s security layer allows control at the individual field level, not just the whole document or index.
Field Grants & Excludes
A role can be configured to allow access to only specific fields (a grant list) or to allow everything except specific fields (an except list), so different teams see different “shapes” of the same document.
_source Includes/Excludes
Independent of security roles, queries themselves can request that only certain fields be returned in _source, reducing payload size and accidental exposure of unneeded fields.
Sensitive Field Handling
Highly sensitive fields (payment details, government IDs) are commonly excluded from being indexed at all, or hashed/tokenized before indexing, so the raw sensitive value never becomes searchable text.
Field-level security is like handing out the same medical chart to different people with different sections stapled shut: a billing clerk sees the insurance fields but not the diagnosis fields, while a doctor sees the opposite — same document, different visible fields, based entirely on who’s asking.
7Monitoring, Logging & Metrics
Fields quietly drive several important operational metrics that teams need to watch, especially in systems where new fields can appear dynamically from evolving application data.
- Total field count vs. field limit: Elasticsearch enforces a configurable cap (index.mapping.total_fields.limit, commonly 1,000 by default) to prevent uncontrolled mapping growth; monitoring how close an index is to this limit catches “mapping explosion” early.
- Fielddata circuit breaker: certain legacy operations on text fields load values into memory; Elasticsearch tracks this usage and rejects operations that would exceed configured memory limits, protecting the cluster from crashing.
- Slow query logs by field: logs of expensive queries often reveal which specific fields are being searched or aggregated inefficiently, guiding mapping or query optimization.
- Mapping update frequency: a rapidly growing number of dynamically created fields over time is a leading indicator of an upstream data quality or schema-design issue.
8Design Patterns & Anti-patterns
Pattern: Multi-Field Design
Deliberately map a single source value into both a “text” field (for relevance-ranked search) and a “keyword” sub-field (for exact filtering, sorting, and aggregations) — the standard way to get both behaviors without duplicating source data.
Pattern: Explicit Mapping Before Production
Use dynamic mapping only during early prototyping. Before going live, capture the discovered field types, review and correct them, and apply them as an explicit mapping to lock in predictable, reviewed behavior.
Pattern: Runtime Fields for Exploration
When you’re unsure whether a calculated field will actually be useful, define it as a runtime field first — it costs nothing at index time — and only “promote” it to a real, stored field once its value is proven.
Uncontrolled Dynamic Fields
Allowing arbitrary, user-supplied keys to become field names (for example, storing a dictionary of tags as object keys instead of an array) can silently create thousands of unique fields, pushing an index toward its field-count limit and bloating cluster mapping metadata.
Using “text” for Everything
Mapping every string field as plain “text” — including things like status codes, IDs, or categories that really need exact matching — leads to broken filters, incorrect sorting, and confusing aggregation results.
9Best Practices & Common Mistakes
Best Practices
- Explicitly map fields you know the shape of; reserve dynamic mapping for genuinely unpredictable data.
- Use “keyword” for anything you’ll filter, sort, or aggregate on exactly; use “text” only for genuine free-text search.
- Disable doc_values on fields you’re certain will never be sorted or aggregated, to save disk space.
- Set a sensible index.mapping.total_fields.limit and alert well before it’s reached.
- Use source filtering in queries to return only the fields the client actually needs.
Common Mistakes
- Letting deeply nested, user-generated JSON create an unbounded number of dynamic fields.
- Forgetting that changing a field’s type requires a full reindex, not an in-place mapping edit.
- Aggregating on an analyzed “text” field instead of its “keyword” multi-field, producing meaningless per-word buckets.
- Storing large blobs of unrelated data in a single generic field instead of modeling it properly.
10Real-World & Industry Examples
Product Attributes
Large retailers map “price” as a numeric field for range filtering, “category” as a keyword for faceted navigation, and “description” as text for full-text search — three field types, three very different jobs, on the same product document.
Structured Log Fields
Log analytics platforms map “log.level” and “service.name” as keyword fields for fast filtering, while the free-form “message” field is mapped as text so engineers can full-text search error messages during incidents.
Geo Fields
Location-based platforms use geo_point fields to power “restaurants near me” style searches, sorting and filtering results by real-world distance from a given coordinate.
Field-Level Access Control
Financial platforms commonly restrict access to fields like account numbers or balances using field-level security, while keeping general transaction metadata visible to a broader set of internal roles.
11Frequently Asked Questions
12Summary and Key Takeaways
Key Takeaways
- A field is a single named, typed piece of data inside a document — the smallest unit Elasticsearch actually indexes, searches, and aggregates on.
- Every field’s type is defined in the index’s mapping and, once set, cannot be changed without reindexing.
- Text fields feed the inverted index for full-text search; most fields also get doc values for fast sorting and aggregation.
- Multi-fields let one source value serve both full-text search and exact filtering at the same time.
- Dynamic mapping is convenient for getting started but risky if left uncontrolled in production — it can silently create thousands of unwanted fields.
- Field-level security and source filtering let different consumers see different “shapes” of the same underlying document.
- Good field design — the right type for the right purpose — is one of the single highest-leverage decisions in an Elasticsearch data model.