What are global ordinals in Elasticsearch, and when does eager_global_ordinals pay off?

## Ordinals, and why aggregations want them When Elasticsearch writes doc_values for a `keyword` field, it does not repeat the string for every document. Each Lucene segment holds a sorted term dictionary for the field, and each document stores the small integer position of its value in that dictionary. That integer is the **ordinal**. Ordinals are compact, dense, and comparable — sorted ordinal order is sorted term order — which makes them ideal for the counting loop inside a `terms` aggregation: allocate an array of counters, one slot per ordinal, and increment. The catch is that ordinals are **per segment**. Ordinal 7 in one segment and ordinal 7 in another are unrelated strings. A shard-level aggregation spans all its segments, so it needs a translation layer. ## What a global ordinal map is The **global ordinal** map is exactly that layer, built at the shard level: it merges every segment's term dictionary into a single shard-wide numbering and stores, per segment, a mapping from local ordinal to global ordinal. With it in hand, the aggregation can allocate one counter array over the global ordinal space and run its per-document loop as integer arithmetic, only resolving global ordinals back to strings for the handful of buckets that survive into the response. The map's cost is a function of the field's **cardinality** — the number of distinct terms on the shard — not of how many documents match the query. That is the key asymmetry: a query that matches ten documents can still pay for a map covering ten million distinct terms. ## Lazy building, and the refresh cliff Global ordinals are built lazily, on the first request that needs them, and cached on the shard. A refresh exposes new segments and invalidates the map, so the next aggregation rebuilds it. On an index refreshing every second with a high-cardinality field, you get a sawtooth latency profile: most requests are fast, and whichever request lands first after each refresh eats the whole build. That request is not slow because of anything it did — a fact that makes the pattern hard to diagnose from application-side timings alone. The memory the map occupies is accounted for as field data in node stats, so `GET _cat/fielddata?v` on a cluster with heavy keyword aggregations will show significant usage even though nobody enabled `fielddata` on a `text` field anywhere. ## eager_global_ordinals Setting `"eager_global_ordinals": true` on a `keyword` mapping tells Elasticsearch to build the map as part of the refresh, before any search sees the new searcher. Search latency becomes predictable because no query ever pays the build; refreshes become more expensive and, on a write-heavy index, indexing throughput drops because refresh work is on the same critical path. The decision is therefore a ratio question: how often is this field aggregated or used in a `terms`-style lookup, versus how often does the index refresh? Read-heavy, slowly-changing data — a product catalogue faceted on every page load, a reference index refreshed on a schedule — is the good case. A logging data stream ingesting continuously is the bad case: you would pay the build on every refresh and most builds would be wasted. A related detail: `join` fields for parent/child relations enable eager global ordinals by default, because the join implementation cannot work without the map at all and the lazy build would be unavoidable on every query. ## The other lever: execution_hint A `terms` aggregation accepts `"execution_hint": "map"`, which skips global ordinals entirely and builds a hash map from raw term values collected from the matching documents. The tradeoff inverts the asymmetry above: `map` costs in proportion to the number of *matched documents and distinct values found*, not the field's total cardinality. It is the right choice when a very selective query touches a small slice of a very high-cardinality field — for example, a heavily-filtered drill-down on a user ID. Used on a broad query it is worse, because you now hash strings for every hit. The default, `global_ordinals`, is right for the common case. ## Diagnosing it Suspect global ordinals when: the field is `keyword` with high cardinality; latency is bimodal and the slow requests correlate with refreshes; field data memory is high with no `fielddata: true` in the mappings; and a manual refresh followed by an aggregation reproduces the slow case reliably. Remedies in order: reduce cardinality (do you really need to facet on the raw ID?), raise `refresh_interval` on a read-mostly index so the map is rebuilt less often, turn on `eager_global_ordinals` if reads dominate, or switch a selective drill-down query to `execution_hint: map`.