<!--

    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at
    
        http://www.apache.org/licenses/LICENSE-2.0
    
    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

-->
# Timeseries Data Model

## 1. What is Time Series Data?

In today's interconnected world, industries such as the Internet of Things (IoT) and manufacturing are undergoing rapid digital transformation. Sensors are widely deployed on various devices to collect real-time operational data. For example:

- **Motors** record voltage and current.
- **Wind Turbines** track blade speed, angular velocity, and power output.
- **Vehicles** capture GPS coordinates, speed, and fuel consumption.
- **Bridges** monitor vibration frequency, deflection, and displacement.

Sensor data collection has permeated almost every industry, generating vast amounts of **time series data**.

![](/img/time-series-data-en-01.png)

Each data collection point is referred to as a **measurement point** (also known as a physical quantity, time series, signal, metric, or measurement value). As time progresses, new data is continuously recorded for each measurement point, forming a **time series**. In tabular form, a time series consists of two columns: **timestamp** and **value**. When visualized, a time series appears as a trend chart over time, resembling an "electrocardiogram" of a device.

![](/img/time-series-data-en-02.png)

Given the vast amount of time-series data generated by sensors, structuring this data effectively is essential for digital transformation across industries. Therefore, time-series data modeling is primarily centered around **devices** and **sensors**.

## 2. Key Concepts in Time Series Data

Several fundamental concepts define time-series data:

| **Device**              | Also known as an entity or equipment, a device is a real-world object that generates time-series data. In IoTDB, a device serves as a logical grouping of multiple time series. A device could be a physical machine, a measuring instrument, or a collection of sensors. Examples include:<br>- Energy sector: A wind turbine, identified by parameters such as region, power station, line, model, and instance.<br>- Manufacturing sector: A robotic arm, uniquely identified by an IoT platform-assigned ID.<br>- Connected vehicles: A car, identified by its Vehicle Identification Number (VIN).<br>- Monitoring systems: A CPU, identified by attributes such as data center, rack, hostname, and device type. |
| ------------------------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **FIELD**   | Also referred to as a physical quantity, signal, metric, or status point, a field represents a specific measurable property recorded by a sensor. Each field corresponds to a measurement point that periodically captures environmental data. Examples include:<br>- Energy and power: Current, voltage, wind speed, rotational speed.<br>- Connected vehicles: Fuel level, vehicle speed, latitude, longitude.<br>- Manufacturing: Temperature, humidity.                                                                                                                                                                                                                                                            |
| **Data Point**        | A data point consists of a timestamp and a value. The timestamp is typically stored as a long integer, while the value can be of various data types such as BOOLEAN, FLOAT, or INT32. <br>In tabular format, a data point corresponds to a single row in a time-series dataset, while in graphical representation, it is a single point on a time-series chart.<br> <img src="/img/time-series-data-en-03.png" alt="" style="width: 70%;"/>                                                                                                                                                                                                                                                                            |
| **Frequency**       | The sampling frequency determines how often a sensor records data within a given timeframe.<br>For example, if a temperature sensor records data once per second, its sampling frequency is 1Hz (1 sample per second).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **TTL**  | TTL (Time-to-Live) defines the retention period of stored data. Once the TTL expires, the data is automatically deleted.<br>IoTDB allows different TTL values for different datasets, enabling automated, periodic data deletion. Proper TTL configuration helps:<br>- Manage disk space efficiently, preventing storage overflow.<br>- Maintain high query performance.<br>- Reduce memory resource consumption.                                                                                                                                                                                                                                                                                                      |