Skip to content

quickstart-tsds.md

Latest commit

 

History

History
252 lines (210 loc) · 8.87 KB

quickstart-tsds.md

File metadata and controls

252 lines (210 loc) · 8.87 KB
Raw
navigation_title Quickstart
applies_to
stack serverless
ga
ga
products
id
elasticsearch

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 high-level steps help you see how a TSDS works, so you can decide whether it's right for 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.

Prerequisites

You can follow this guide using any {{es}} deployment. To see all deployment options, refer to . To get started quickly, spin up a cluster locally in Docker.

Create and query a TSDS

:::::{stepper} ::::{step} 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 are used to uniquely identify the time series and are typically based on a descriptive property like location. Metrics are measurements that change over time.

Use an _index_template request to create a template with two identifying dimension fields and two metric fields for weather measurements:

PUT _index_template/quickstart-tsds-template  
{
  "index_patterns": ["quickstart-*"],
  "data_stream": { },   # Indicates this is a data stream, not a regular index.
  "priority": 100, 
  "template": {
    "settings": {
      "index.mode": "time_series"   # The required index mode for TSDS.
    },
    "mappings": {
      "properties": {
        "sensor_id": {
          "type": "keyword",
          "time_series_dimension": true   # Defines a dimension field.
        },
        "location": {
          "type": "keyword",
          "time_series_dimension": true   # Another dimension field.
        },
        "temperature": {
          "type": "half_float",
          "time_series_metric": "gauge"   # A supported field type for metrics.
         },
        "humidity": {
          "type": "half_float",
          "time_series_metric": "gauge"   # A second measurement.
        },
        "@timestamp": {
          "type": "date"
        }
      }
    }
  }
}

This example defines a @timestamp field for illustration purposes. In most cases, you can use the default @timestamp field (which has a default type of date) instead of defining a timestamp in the mapping.

You should get a response of "acknowledged": true that confirms the template was created.

::::

::::{step} 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 a _bulk API request to add multiple documents at once. Make sure to adjust the timestamps to within a few minutes of the current time.

% TODO simplify timestamps

PUT quickstart-weather/_bulk
{ "create":{ } }
{ "@timestamp": "2025-09-08T21:25:00.000Z", "sensor_id": "STATION-0001", "location": "base", "temperature": 26.7, "humidity": 49.9 }
{ "create":{ } }
{ "@timestamp": "2025-09-08T21:26:00.000Z", "sensor_id": "STATION-0002", "location": "base", "temperature": 27.2, "humidity": 50.1 }
{ "create":{ } }
{ "@timestamp": "2025-09-08T21:35:00.000Z", "sensor_id": "STATION-0003", "location": "base", "temperature": 28.1, "humidity": 48.7 }
{ "create":{ } }
{ "@timestamp": "2025-09-08T21:27:00.000Z", "sensor_id": "STATION-0004", "location": "satellite", "temperature": 32.4, "humidity": 88.9 }
{ "create":{ } }
{ "@timestamp": "2025-09-08T21:36:00.000Z", "sensor_id": "STATION-0005", "location": "satellite", "temperature": 32.3, "humidity": 87.5 }

The response shows five sample weather data documents.

:::{dropdown} Example response

{
  "errors": false,
  "took": 0,
  "items": [
    {
      "create": {
        "_index": ".ds-quickstart-weather-2025.09.08-000001",
        "_id": "cFJZQJlNh-Xl8V_rAAABmSs3x-A",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 0,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "create": {
        "_index": ".ds-quickstart-weather-2025.09.08-000001",
        "_id": "c-wsTT0T4CtI3hOuAAABmSs4skA",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 1,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "create": {
        "_index": ".ds-quickstart-weather-2025.09.08-000001",
        "_id": "Hdee5vMpBvZymWvHAAABmStA76A",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 2,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "create": {
        "_index": ".ds-quickstart-weather-2025.09.08-000001",
        "_id": "e3Z2UirUQldsjLr2AAABmSs5nKA",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 3,
        "_primary_term": 1,
        "status": 201
      }
    },
    {
      "create": {
        "_index": ".ds-quickstart-weather-2025.09.08-000001",
        "_id": "N3-RYtQAp6JEsLRNAAABmStB2gA",
        "_version": 1,
        "result": "created",
        "_shards": {
          "total": 2,
          "successful": 2,
          "failed": 0
        },
        "_seq_no": 4,
        "_primary_term": 1,
        "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.

:::

:::: ::::{step} Run a query

Now that your data stream has some documents, you can use the ES|QL _query endpoint to query the data. This sample aggregation shows the maximum of average temperature per sensor for each location, in hourly buckets.

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

:::{dropdown} Example response

MAX(AVG_OVER_TIME(temperature))|   location   |      TBUCKET(1h)       
-------------------------------+--------------+------------------------
27.333333333333332             |base          |2025-09-08T21:00:00.000Z
32.359375                      |satellite     |2025-09-08T21:00:00.000Z

:::

:::{tip} You can also try this aggregation in a data view in {{kib}}. :::

:::: :::::

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 {{es}} API reference documentation: