Elasticsearch / Basic: document and query contracts / Lesson 2
Explicit mappings and field contracts
Choose field behavior before indexing and prevent accidental schema growth or incompatible types.
On this page
Lesson goals
- Distinguish text, keyword, numeric and date fields.
- Explain dynamic strict, multi-fields and reindex boundaries.
One string can serve different questions
A title supports word-based discovery, while a catalog identifier supports exact equality. Mapping both as undifferentiated strings leaves those requirements to accidental defaults. A text field is analyzed into search terms; a keyword field retains an exact value suitable for filtering, sorting and many aggregations. A multi-field can represent one source value in both ways, but the extra representation costs storage and indexing work. Define the actual product question for each field rather than adding a keyword subfield to everything. Human-readable numbers such as accession codes should stay strings when arithmetic is meaningless.
Publish a small deliberate mapping
The request body belongs to index creation for a synthetic museum-artifacts-v1 index. A title has a full-text representation and a raw keyword subfield; year is an integer and acquired_at is a date. Explicit fields avoid a first-document accident, such as a digit-like identifier becoming numeric or an ambiguous date-like string being detected unexpectedly. dynamic: strict rejects unknown fields instead of silently extending the contract. Strictness is useful only when the producer and consumer agree on an evolution workflow; otherwise legitimate new data will fail with no repair path.
{"mappings":{"dynamic":"strict","properties":{"artifact_id":{"type":"keyword"},"title":{"type":"text","fields":{"raw":{"type":"keyword"}}},"year":{"type":"integer"},"acquired_at":{"type":"date"}}}}A synthetic index-creation body. title.raw is a mapped representation, not a separately supplied JSON property.
Ignoring a field differs from indexing it
In ordinary indices with stored _source, dynamic: false can retain unknown source fields while not mapping them for normal search. That is different from strict rejection and different from accepting new fields dynamically. This distinction explains how a returned document can visibly contain a field that an exists or term query cannot use. Do not generalize those storage semantics to specialized newer index modes without checking their documentation. A controlled extension should add a reviewed mapping, update the producer contract and reconcile older documents if their indexed representation must be rebuilt.
Test boundaries rather than one happy document
A malformed integer, an invalid date or an object supplied where a scalar is expected can reject a document. Arrays also need a consistent element type because Elasticsearch does not have a separate ordinary array field type. NULL and empty arrays usually contribute no indexed value, while an empty string can be a legitimate keyword value. Choose missing-value rules at the application boundary and document any null_value mapping. The sample source below conforms to the declared fields, but a parser accepting it does not prove that Elasticsearch accepted or indexed it.
{"artifact_id":"art-101","title":"Bronze compass","year":1890,"acquired_at":"2026-10-01T09:00:00Z"}A valid JSON fixture for reviewing type intent. No engine mapping validation is claimed.
A new type usually needs a new index
Many existing field types cannot be changed in place. A new index with the corrected mapping and a controlled reindex is often required. Adding a new multi-field also does not retroactively populate its representation for documents already indexed; those documents need update or reindex work when that representation is required. Plan aliases, count reconciliation, failed-item accounting and concurrent source changes before switching readers. Mapping explosion is another design problem: arbitrary attribute keys can create unbounded field definitions. A bounded schema or an appropriate flattened representation can be preferable to raising the field limit without understanding the source.
Common errors and fixes
strict_dynamic_mapping_exception
- Why it happens
- A producer sent a field absent from the reviewed strict mapping.
- How to fix it
- Review the source change and add only the intended schema extension.
- Prevent it next time
- Coordinate mapping and producer releases with rejected-item accounting.
mapper_parsing_exception
- Why it happens
- A field value conflicts with its declared or detected type.
- How to fix it
- Inspect the exact field path and original source type.
- Prevent it next time
- Test numeric, object, date and missing-value boundaries before ingestion.
A new multi-field is empty for old documents
- Why it happens
- Adding the mapping did not rebuild prior indexed representations.
- How to fix it
- Plan an authorized update or reindex with reconciliation.
- Prevent it next time
- Include historical data in every mapping-evolution acceptance check.
Check your understanding
1. Should artifact_id 000123 be an integer because it contains digits?
Show worked solution
No. If leading zeros and identity matter, keyword expresses exact identifier semantics. Numeric mapping would discard that representation and suggest meaningless arithmetic. Separate any actual numeric sequence from the displayed business identifier and test exact matching with realistic source values.
2. A field appears in _source but cannot be filtered. What mapping setting could explain it?
Show worked solution
For the ordinary stored-source model, dynamic: false may have ignored the unknown field for mapping while retaining it in source. Inspect the actual mapping and index mode. Add a reviewed representation and rebuild old documents if search needs it; do not assume returned JSON proves an indexed field exists.
Key takeaways
- Mapping chooses search behavior rather than merely validating JSON syntax.
- Schema changes must account for existing indexed documents.