text vs keyword: Analysis, Exact Matching, Sorting/Aggregation, Multi-Fields, and Normalizers

Learning outcomes

AtlasMart wants shoppers to find “USB C charger” with natural-language matching while merchandisers group results by brand, sort by SKU, and filter a status value without tokenization surprises. A single generic “string” type cannot satisfy all of those requirements correctly. This lesson uses observable token streams and query results to separate text from keyword, then uses multi-fields and normalizers to support multiple access patterns without duplicating source JSON.

1. text and keyword answer different questions

A text field is intended for full-text search. Its analyzer converts a string into a token stream at index time and a compatible analysis process is usually applied to full-text query input. A keyword field treats the value as one logical token for exact/term-level operations. That distinction is semantic, not merely a performance setting.

OpenSearch documents keyword as non-analyzed, exact and case-sensitive by default. Elasticsearch uses the same broad division, but current Elasticsearch 9.x has additional options around text/doc-values behavior that should not be projected onto OpenSearch. A portable course design therefore keeps facets and sorting on explicit keyword fields/subfields.

2. Observe the token stream

DELETE atlasmart-text-keyword-labPUT atlasmart-text-keyword-lab{  "settings": {    "number_of_shards": 1,    "number_of_replicas": 0,    "analysis": {      "normalizer": {        "atlas_lower": {"type":"custom","filter":["lowercase","asciifolding"]}      }    }  },  "mappings": {    "dynamic":"strict",    "properties": {      "product_id":{"type":"keyword"},      "name":{"type":"text","fields":{"raw":{"type":"keyword"}}},      "brand":{"type":"keyword","normalizer":"atlas_lower"},      "status":{"type":"keyword"}    }  }}POST atlasmart-text-keyword-lab/_analyze{"field":"name","text":"USB-C Travel Charger"}POST atlasmart-text-keyword-lab/_analyze{"normalizer":"atlas_lower","text":"ÄTLAS Gear"}

The name analysis should emit multiple terms rather than one literal JSON string. The normalizer should emit exactly one normalized token because normalizers do not tokenize a keyword value into multiple words. Record the actual tokens returned by each product; token details can vary with analyzer configuration and version, so the acceptance criterion is semantic shape, not a memorized token list.

3. One source value, two indexed views

POST atlasmart-text-keyword-lab/_bulk?refresh=true{"index":{"_id":"P-1"}}{"product_id":"P-1","name":"USB-C Travel Charger","brand":"ÄTLAS Gear","status":"ACTIVE"}{"index":{"_id":"P-2"}}{"product_id":"P-2","name":"Compact USB Charger","brand":"Atlas Gear","status":"ACTIVE"}{"index":{"_id":"P-3"}}{"product_id":"P-3","name":"Travel Adapter","brand":"Other","status":"PAUSED"}GET atlasmart-text-keyword-lab/_search{"query":{"match":{"name":"travel charger"}}}GET atlasmart-text-keyword-lab/_search{"query":{"term":{"name.raw":"USB-C Travel Charger"}}}GET atlasmart-text-keyword-lab/_search{"size":0,"aggs":{"brands":{"terms":{"field":"brand"}}}}GET atlasmart-text-keyword-lab/_search{"sort":[{"name.raw":"asc"}],"query":{"match_all":{}}}

name and name.raw are not duplicate properties in _source; they are two indexed representations of the same source field. The text view supports analyzed retrieval. The keyword subfield supports whole-value operations. The normalized brand values demonstrate that exact-value semantics can still be normalized for case/diacritic consistency, but that normalization choice must match business requirements because it changes what “exact” means.

4. Wrong approach: aggregate on the analyzed text field

A developer may try a terms aggregation directly on name. On a conventional mapping, this is rejected or unsupported by default because analyzed text is not the intended grouping surface. Historically, Elasticsearch users sometimes enabled fielddata to make such operations possible, which can consume substantial heap. The safer design for this requirement is the keyword multi-field you already created.

GET atlasmart-text-keyword-lab/_search{  "size":0,  "aggs":{"wrong_product_name_facet":{"terms":{"field":"name"}}}}GET atlasmart-text-keyword-lab/_search{  "size":0,  "aggs":{"correct_product_name_facet":{"terms":{"field":"name.raw"}}}}

5. Boundary cases: IDs that look numeric and long keyword values

Field types come from operations, not appearance. A numeric-looking product ID such as 001234 is usually better as keyword if AtlasMart performs only exact lookup and needs to preserve leading zeros. Conversely, an actual price belongs in a numeric type because range and numeric sort semantics matter. Dynamic mapping can infer both incorrectly relative to business intent.

Keyword values also have indexing limits and parameters such as ignore_above. Dynamic mappings commonly create text plus keyword subfields with an ignore_above threshold; a long value may remain in _source while its keyword subfield is not indexed. That means “I can see the value in the document” does not prove “I can facet/filter it as keyword.” Add a boundary test whenever source length is uncontrolled.

Summary and next step

The source string is not the search contract. You have now proved that analysis, exact matching, sorting, and aggregation require distinct indexed representations. The next lesson extends that requirement-driven method to numeric, date, geo, range, vector, object, flattened-like, and computed field families.

Authoritative references

• Elastic mapping overview — Official mapping guidance and schema-evolution constraints.
• Elastic field data types — Current Elasticsearch field-type reference.
• Elastic mapping limits — Mapping-limit settings and mapping-explosion safeguards.
• OpenSearch mapping documentation — Current OpenSearch mapping entry point.
• OpenSearch supported field types — Current OpenSearch field-type inventory.
• OpenSearch mapping explosion — Field growth risks and mapping-limit controls.
• Elastic text field — Text analysis, multi-fields and text-field options.
• Elastic keyword field — Exact-value keyword semantics and parameters.
• OpenSearch keyword field — OpenSearch keyword behavior and multi-field support.
• OpenSearch normalizer — Single-token normalization for keyword fields.