This page defines core TSDB concepts. All examples use a single scenario — monitoring air quality across cities — so you can see how each term fits into the same data model.
Sample data
The following table shows air quality readings from monitoring stations across two cities:
| Timestamp | Metric | City | Station | Value |
|---|---|---|---|---|
| 2026-03-28T08:00:00Z | sulfur_dioxide | Hangzhou | station_A | 12 |
| 2026-03-28T08:00:00Z | sulfur_dioxide | Shanghai | station_B | 18 |
| 2026-03-28T08:01:00Z | sulfur_dioxide | Hangzhou | station_A | 13 |
| 2026-03-28T08:01:00Z | temperature | Hangzhou | station_A | 20 |
Each row is a data point. The columns to the right of the timestamp are the metric, tags, and value. The combination of metric and tags defines a time series.
Glossary
TSDB
Time Series Database (TSDB) provides a data management system that allows you to store, query, collect, and analyze time series data in an efficient manner.
Related terms: time series data, metric, data point
Time series data
A series of metric data that is continuously generated at specific intervals.
For example, when you monitor the air quality of a city, the series of data collected per second to measure the sulfur dioxide concentration is the time series data.
Related terms: metric, time series, data point
Metric
A named property being measured. In the sample data, sulfur_dioxide and temperature are metrics.
A metric answers "what are you measuring?" but not "where?" or "which device?". Tags answer those questions.
Related terms: tag, value, data point
Tag
A key-value pair that identifies the specific object being monitored. Tags narrow down a metric to a particular subject. A tag is a subcategory of a specific metric.
In the sample data, city=Hangzhou and station=station_A are tags. Together with the metric, they identify a specific monitoring station in a specific city.
Two tags are equal only if both the key and the value match. city=Hangzhou and city=Shanghai are different tags, even though they share the same key.
Related terms: tag key, tag value, metric, time series
Tag key
The dimension name in a tag key-value pair. In city=Hangzhou, the tag key is city. Common tag keys include city, station, region, and ip_address.
Tag value
The specific value paired with a tag key. In city=Hangzhou, the tag value is Hangzhou.
Value
The numeric measurement recorded for a metric at a given point in time. In the sample data, 12 is the sulfur dioxide concentration measured at station_A in Hangzhou at 08:00.
Related terms: metric, data point, tag
Timestamp
The point in time at which a measurement was taken. In the sample data, 2026-03-28T08:00:00Z is the timestamp.
TSDB supports timestamps accurate to milliseconds, seconds, minutes, or hours.
Related terms: data point, time granularity
Data point
A single measurement record — similar to a row in a SQL database table. Each data point contains:
A metric
One or more tags
A timestamp
A value
In the sample data, the first row (2026-03-28T08:00:00Z | sulfur_dioxide | city=Hangzhou | station=station_A | 12) is one data point.
Related terms: metric, tag, timestamp, value, time series
Time series
The sequence of data points collected for a specific metric-and-tag combination. A time series is defined by one metric and one or more tags — not by the number of data points it contains.
In the sample data, all rows where metric=sulfur_dioxide AND city=Hangzhou AND station=station_A form one time series. Adding more data points to this series (for example, recordings from 08:02, 08:03, and so on) does not create new time series — it extends the existing one.
Each unique combination of metric and tags creates a separate time series:
| Metric | Tags | Time series |
|---|---|---|
| sulfur_dioxide | city=Hangzhou, station=station_A | Series 1 |
| sulfur_dioxide | city=Shanghai, station=station_B | Series 2 |
| temperature | city=Hangzhou, station=station_A | Series 3 |
Related terms: metric, tag, data point, timeline
Timeline
A timeline is equivalent to a time series in TSDB. The two terms refer to the same concept.
Related terms: time series
Time granularity
The interval at which data points are written to a time series. In the sample data, readings are collected every minute, so the time granularity is one minute.
TSDB supports granularities from milliseconds to hours. Examples:
| Use case | Granularity |
|---|---|
| Air quality readings | Every second |
| CPU utilization | Every 5 minutes |
Related terms: data point, downsampling
Data group
A subset of time series grouped by a shared tag value, used to compare metric data across multiple objects.
To compare sulfur dioxide levels across cities, group the data by city:
SELECT avg(sulfur_dioxide), city FROM readings WHERE ... GROUP BY cityThis produces one data group per city, letting you compare Hangzhou, Shanghai, and other cities side by side.
Related terms: tag, time series, aggregation
Aggregation
The process of combining multiple time series into a single result. Use aggregation when you need a summary across multiple objects rather than individual readings.
To calculate the average pollution index for Hangzhou, aggregate the readings from all monitoring stations in Hangzhou into a single value. Combining measurements from multiple physical locations into one result is called spatial aggregation.
Related terms: time series, data group, downsampling
Downsampling
The process of reducing data resolution to make long time ranges easier to query and display.
For example, if air quality readings are collected every second for an entire year, querying a full year at per-second granularity produces over 31 million data points. Downsampling reduces this to one data point per day, making the trend visible without processing all the raw data.
Related terms: time granularity, aggregation, data validity period
Data validity period
The retention period for data. When the data validity period elapses, TSDB automatically releases the data.
Set the data validity period based on how long you need to retain raw and downsampled data. Shorter retention periods reduce storage costs.
Related terms: downsampling