Quickstart: Time series data stream basics

Use this quickstart to set up a time series data stream (TSDS), ingest a few documents, and run a basic query. These steps show how a TSDS works so you can decide whether it fits your data.

A time series is a sequence of data points collected at regular time intervals. For example, you might track CPU usage or stock price over time. This quickstart uses simplified weather sensor readings to show how a TSDS helps you analyze metrics data over time.

By the end of this quickstart, you can:

Create an index template for a TSDS
Ingest sample metrics into a data stream
Query the data with ES|QL

Before you begin

Access to Dev Tools Console in Kibana, or another way to make Elasticsearch API requests
Cluster and index permissions:
- Cluster privilege: manage_index_templates
- Index privileges: create_doc, create_index, read, and delete_index
Familiarity with time series data stream concepts and Elasticsearch index and search basics

You can follow this guide using any Elasticsearch deployment. To see all deployment options, refer to Elastic deployment options > Choosing your deployment type. To get started quickly, spin up a cluster locally in Docker.

Create and query a TSDS

Create an index template

To create a data stream, you need an index template to base it on. The template defines the data stream structure and settings. (For this quickstart, you don't need to understand template details.)

A TSDS uses dimension fields and metric fields. Dimensions uniquely identify the time series and are typically based on a descriptive property like location. Metrics are measurements that change over time.

Use the create index template API to create a template with two identifying dimension fields and two metric fields for weather measurements:
JSON
```
PUT _index_template/quickstart-tsds-template
{
  "index_patterns": ["quickstart-*"],
  "data_stream": { },
  "priority": 100,
  "template": {
    "settings": {
      "index.mode": "time_series"
    },
    "mappings": {
      "properties": {
        "sensor_id": {
          "type": "keyword",
          "time_series_dimension": true
        },
        "location": {
          "type": "keyword",
          "time_series_dimension": true
        },
        "temperature": {
          "type": "half_float",
          "time_series_metric": "gauge"
        },
        "humidity": {
          "type": "half_float",
          "time_series_metric": "gauge"
        },
        "@timestamp": {
          "type": "date"
        }
      }
    }
  }
}
```
1. Indicates this is a data stream, not a regular index.
2. Required index mode for a TSDS.
3. Marks sensor_id as a dimension. The template also defines location as a dimension.
4. Marks temperature as a gauge metric. The template also defines humidity as a gauge.
This example defines a @timestamp field for illustration purposes. Usually, you can use the default @timestamp field (which has a default type of date) instead of defining a timestamp in the mapping.

The response includes "acknowledged": true, which confirms the template was created.

Create a data stream and add sample data

In this step, create a new data stream called quickstart-weather based on the index template defined in Step 1. You can create the data stream and add documents in a single API call.

Use the bulk API to add multiple documents at once. Before you run the request, set each @timestamp to within a few minutes of the current time:

PUT quickstart-weather/_bulk
{ "create":{ } }
{ "@timestamp": "2026-08-17T15:27:00Z", "sensor_id": "STATION-0001", "location": "base", "temperature": 26.7, "humidity": 49.9 }
{ "create":{ } }
{ "@timestamp": "2026-08-17T15:28:00Z", "sensor_id": "STATION-0002", "location": "base", "temperature": 27.2, "humidity": 50.1 }
{ "create":{ } }
{ "@timestamp": "2026-08-17T15:35:00Z", "sensor_id": "STATION-0003", "location": "base", "temperature": 28.1, "humidity": 48.7 }
{ "create":{ } }
{ "@timestamp": "2026-08-17T15:27:00Z", "sensor_id": "STATION-0004", "location": "satellite", "temperature": 32.4, "humidity": 88.9 }
{ "create":{ } }
{ "@timestamp": "2026-08-17T15:36:00Z", "sensor_id": "STATION-0005", "location": "satellite", "temperature": 32.3, "humidity": 87.5 }

A successful request returns "errors": false and a create item for each document.

Example response

{
  "errors": false,
  "took": 201,
  "items": [
    {
      "create": {
        "_index": ".ds-quickstart-weather-2026.08.17-000001",
        "_id": "n1TMXZekg4PbwmflIo-DEH___l_vqrZfe0V20A",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 1,
          "failed": 0
        },
        "_seq_no": -2,
        "_primary_term": 0,
        "status": 201
      }
    },
    ...
  ]
}

Tip

If you get an error about timestamp values, check the error response for the valid timestamp range. For more details, refer to Accepted time range for adding data.

Run a query

With documents in the data stream, you can use the ES|QL query API to query the data. This sample aggregation shows the maximum of average temperature per sensor for each location, in hourly buckets.

POST _query?format=txt
{
  "query": "TS quickstart-weather | STATS max(avg_over_time(temperature)) BY location, TBUCKET(1h)"
}

Example response

max(avg_over_time(temperature))|   location    |      TBUCKET(1h)
-------------------------------+---------------+------------------------
28.09375                       |base           |2026-08-17T15:00:00.000Z
32.40625                       |satellite      |2026-08-17T15:00:00.000Z

Tip

You can also try this aggregation in a data view in Kibana.

Delete the TSDS

When you no longer need the TSDS and index template created in this quickstart, use the delete data streams API and delete index template API. For example:
JSON
```
DELETE /_data_stream/quickstart-weather
DELETE /_index_template/quickstart-tsds-template
```

Next steps

This quickstart introduced the basics of time series data streams. To learn more, explore these topics:

If you're working with OpenTelemetry (OTLP) or Prometheus data, refer to:

For more information about the APIs used in this quickstart, review the Elasticsearch API reference documentation: