Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 43 ยท Beyond Keywords

Geo Queries and Time-Series Data

Search by location with geo_point, geo_distance and bounding boxes, then store logs and metrics with data streams, rollover and index lifecycle management.

Two kinds of data make Elasticsearch work harder than plain text does. Location data ("restaurants within 2 km") needs math on a sphere. Time-series data (logs, metrics, events) arrives forever, is almost never updated, and gets less valuable as it ages. Elasticsearch has dedicated features for both: the geo_point field with distance queries, and data streams with index lifecycle management for time-based data.

The real cluster cannot run on this site, so requests and settings are read-only. Each half ends with a JavaScript stand-in that does the same thinking with plain code: a distance filter and a rollover simulator. They show the idea, they are not Elasticsearch.

Two special kinds of data

Geo Points on Earth, queried by distance or area.
Time series Append-only events, ordered by time.

Both reward a mapping chosen for the query you will run.

1 / 2

Geo points

A geo_point stores one latitude/longitude pair. You declare it in the mapping, and then you can send the value in several shapes.

JSON
PUT /shops
{ "mappings": { "properties": {
    "name":     { "type": "text" },
    "location": { "type": "geo_point" }
} } }

PUT /shops/_doc/1
{ "name": "Corner Cafe", "location": { "lat": 52.5200, "lon": 13.4050 } }

Other accepted forms are an array [lon, lat], a string "52.52,13.405" and WKT "POINT (13.405 52.52)". Note the traps: the array form puts longitude first, while the string and object forms put latitude first. Mixing these up places your shop in the wrong hemisphere without any error. For polygons, such as delivery zones, there is a separate geo_shape type.

Distance, box and sorting

geo_distance matches points within a radius of a center. It is a filter, so put it in the filter of a bool query (Bool Queries and Compound Logic) to keep scoring clean.

JSON
GET /shops/_search
{
  "query": {
    "bool": {
      "must":   { "match": { "name": "cafe" } },
      "filter": { "geo_distance": { "distance": "2km", "location": { "lat": 52.52, "lon": 13.40 } } }
    }
  },
  "sort": [
    { "_geo_distance": {
        "location": { "lat": 52.52, "lon": 13.40 },
        "order": "asc", "unit": "km"
    } }
  ]
}

Distances use the spherical Earth model (the arc distance), so they are accurate enough for shops and not for surveying. A geo_bounding_box query matches points inside a rectangle defined by top_left and bottom_right corners, which is cheap and fits a map viewport exactly: the user pans the map, and your app sends the visible rectangle. Aggregations such as geo_distance (rings around a center) and geohash_grid (map tiles with counts) turn points into "heat map" data.

Elasticsearch computes this with efficient index structures over the points, rather than calculating the distance to every document. The stand-in below does the brute-force version, which is fine to understand the rules.

JS A geo_distance filter and bounding box

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The nearby cities come out sorted by distance, exactly what _geo_distance sorting returns. The bounding box includes Berlin, Potsdam, Leipzig and Dresden but not Hamburg (too far west) or Munich (too far south). The real engine handles harder cases for you, like boxes that cross the 180ยฐ meridian.

Time-series data and data streams

Logs and metrics share a shape: documents have a @timestamp, are written once, and are queried by recent time ranges. Putting them all in one ever-growing index would be a mistake: one huge index is slow to search, impossible to shrink, and deleting old data would mean slow per-document deletes.

The classic fix is time-based indexes: logs-2026.11.06, logs-2026.11.07, and so on. You search logs-*, and deleting a day means dropping one index, which is instant. A data stream automates this pattern. You write to one name (logs-app), Elasticsearch writes into the newest hidden backing index (named like .ds-logs-app-2026.11.06-000001), and searches across all of them.

JSON
PUT _index_template/logs-app
{
  "index_patterns": ["logs-app"],
  "data_stream": {},
  "template": {
    "settings": { "index.lifecycle.name": "logs-policy" },
    "mappings": { "properties": {
      "@timestamp": { "type": "date" },
      "level":      { "type": "keyword" },
      "message":    { "type": "text" }
    } }
  },
  "priority": 200
}

POST logs-app/_doc
{ "@timestamp": "2026-11-06T09:30:00Z", "level": "error", "message": "payment failed" }

Data streams are append-only: you can add documents (the create operation), but you update or delete by targeting a specific backing index. A @timestamp field is required. That restriction is what makes them cheap to operate, and it fits logs well. If you must update documents regularly, use a normal index with an alias instead.

Rollover and ILM

A rollover closes the current write index and starts a new one. Index lifecycle management (ILM) decides automatically when to roll over and what happens to older indexes.

JSON
PUT _ilm/policy/logs-policy
{
  "policy": { "phases": {
    "hot": {
      "actions": { "rollover": { "max_primary_shard_size": "50gb", "max_age": "7d" } }
    },
    "warm": { "min_age": "30d", "actions": { "forcemerge": { "max_num_segments": 1 } } },
    "delete": { "min_age": "90d", "actions": { "delete": {} } }
  } }
}

This policy rolls over when a primary shard reaches 50 GB or the index is 7 days old, whichever comes first. It compacts older indexes and deletes them after 90 days. The min_age of later phases counts from the rollover. Two good habits: size shards for performance (tens of gigabytes) rather than rolling over daily out of habit, and keep retention rules written down, because ILM deletes data without asking.

JS Simulate rollover and retention

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The output shows two rollovers by max_docs, one by max_age, a delete of the oldest index, and a final search that reads from all remaining indexes at once. Dropping a whole index is the reason time-based layouts delete cheaply.

Choosing your layout

For logs and metrics, use a data stream and a lifecycle policy from day one. For geo data, a plain index with a geo_point is enough, and you can combine geo filters with full-text queries and aggregations like any other field. If your data is both (vehicle positions over time), a data stream with a geo_point mapping works well. For metrics-heavy workloads, Elasticsearch also offers a time series data stream mode that stores metrics more compactly. Check the documentation of your version for its current options before choosing it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In which order does the array form of a geo_point list the coordinates?

    The array form is [lon, lat] (the GeoJSON convention), while the object and string forms put latitude first. Mixing them up silently moves the point.
  2. 2. Why put geo_distance in the filter clause of a bool query?

    A distance is a yes/no condition, so a filter fits. Sorting by distance is a separate _geo_distance sort.
  3. 3. What is a main benefit of a data stream over one large index for logs?

    Data streams are append-only and split into backing indexes. Lifecycle policies then roll over and delete whole indexes cheaply.
  4. 4. When does an ILM rollover action fire if you set both max_primary_shard_size and max_age?

    Rollover conditions are alternatives: the first one reached triggers the rollover (unless you configure otherwise).

Summary

  • geo_point stores a location; geo_distance and geo_bounding_box filter, and _geo_distance sorts by distance.
  • Mind the coordinate order: [lon, lat] in arrays, latitude first in objects and strings.
  • Logs and metrics belong in time-based indexes; a data stream manages the backing indexes for you and is append-only.
  • ILM policies roll over by size or age and delete old indexes in phases.
  • Plan retention deliberately, because lifecycle deletion is automatic and permanent.

Next: Shards, Replicas and Clusters.