Modeling Scheme Design

This section introduces how to transform time series data application scenarios into IoTDB time series modeling.

1. Time Series Data Model

Before designing an IoTDB data model, it's essential to understand time series data and its underlying structure. For more details, refer to: Time Series Data Model

2. Two Time Series Model in IoTDB

IoTDB offers two data modeling syntaxes—tree model and table model, each with its distinct characteristics as follows:

Tree Model: It manages data points as objects, with each data point corresponding to a time series. The data point names, segmented by dots, form a tree-like directory structure that corresponds one-to-one with the physical world, making the read and write operations on data points straightforward and intuitive.

Table Model: It is recommended to create a table for each type of device. The collection of physical quantities from devices of the same type shares certain commonalities (such as the collection of temperature and humidity physical quantities), allowing for flexible and rich data analysis.

2.1 Model Characteristics

Both model syntaxes have their own applicable scenarios.

The following table compares the tree model and the table model from various dimensions, including applicable scenarios and typical operations. Users can choose the appropriate model based on their specific usage requirements to achieve efficient data storage and management.

Dimension	Tree Model	Table Model
Applicable Scenarios	Measurements management, monitoring scenarios	Device management, analysis scenarios
Typical Operations	Read and write operations by specifying data point paths	Data filtering and analysis through tags
Structural Characteristics	Flexible addition and deletion, similar to a file system	Template-based management, facilitating data governance
Syntax Characteristics	Concise	Standardized
Performance Comparison	Similar

Notes:

• Both model spaces can coexist within the same cluster instance. Each model follows distinct syntax and database naming conventions, and they remain isolated by default.

• When establishing a database connection via client tools (Cli) or SDKs, specify the model syntax using the sql_dialect parameter (Tree syntax is used by default).

3. Application Scenarios

The application scenarios mainly include two categories:

• Scenario 1: Using the tree model for data reading and writing.

• Scenario 2: Using the table model for data reading and writing.

3.1 Scenario 1: Tree Model

3.1.1 Characteristics

• Simple and intuitive, corresponding one-to-one with monitoring points in the physical world.

• Flexible like a file system, allowing the design of any branch structure.

• Suitable for industrial monitoring scenarios such as DCS and SCADA.

3.1.2 Basic Concepts

Concept	Definition
Database	Definition: A path prefixed with root.. Naming Recommendation: Only include the next level node under root, such as root.db. Quantity Recommendation: The upper limit is related to memory. A single database can fully utilize machine resources; there is no need to create multiple databases for performance reasons. Creation Method: Recommended to create manually, but can also be created automatically when a time series is created (defaults to the next level node under root).
Time Series (Data Point)	Definition: A path prefixed with the database path, segmented by ., and can contain any number of levels, such as root.db.turbine.device1.metric1. Each time series can have different data types. Naming Recommendation: Only include unique identifiers (similar to a composite primary key) in the path, generally not exceeding 10 levels. Typically, place tags with low cardinality (fewer distinct values) at the front to facilitate system compression of common prefixes. Quantity Recommendation: The total number of time series manageable by the cluster is related to total memory; refer to the resource recommendation section. There is no limit to the number of child nodes at any level. Creation Method: Can be created manually or automatically during data writing.
Device	Definition: The second-to-last level is the device, such as device1 in root.db.turbine.device1.metric1. Creation Method: Cannot create a device alone; it exists as time series are created.

3.1.3 Modeling Examples

3.1.3.1 How to model when managing multiple types of devices?

• If different types of devices in the scenario have different hierarchical paths and data point sets, create branches under the database node by device type. Each device type can have a different data point structure.

3.1.3.2 How to model when there are no devices, only data points?

• For example, in a monitoring system for a station, each data point has a unique number but does not correspond to any specific device.

3.1.3.3 How to model when a device has both sub-devices and data points?

• For example, in an energy storage scenario, each layer of the structure monitors its voltage and current. The following modeling approach can be used.

3.2 Scenario 2: Table Model

3.2.1 Characteristics

• Models and manages device time series data using time series tables, facilitating analysis with standard SQL.

• Suitable for device data analysis or migrating data from other databases to IoTDB.

3.2.2 Basic Concepts

• Database: Can manage multiple types of devices.

• Time Series Table: Corresponds to a type of device.

Category	Definition
Time Column (TIME)	Each time series table must have a time column named time, with the data type TIMESTAMP.
Tag Column (TAG) |	Unique identifiers (composite primary key) for devices, ranging from 0 to multiple. Tag information cannot be modified or deleted but can be added. Recommended to arrange from coarse to fine granularity.
Data Point Column (FIELD) |	A device can collect 1 to multiple data points, with values changing over time. There is no limit to the number of data point columns; it can reach hundreds of thousands.
Attribute Column (ATTRIBUTE)	Supplementary descriptions of devices, not changing over time. Device attribute information can range from 0 to multiple and can be updated or added. A small number of static attributes that may need modification can be stored here.

Data Filtering Efficiency: Time Column = Tag Column > Attribute Column > Data Point Column.

3.2.3 Modeling Examples

3.2.3.1 How to model when managing multiple types of devices?

• Recommended to create a table for each type of device, with each table having different tags and data point sets.

• Even if devices are related or have hierarchical relationships, it is recommended to create a table for each type of device.

3.2.3.2 How to model when there are no device identifier columns or attribute columns?

• There is no limit to the number of columns; it can reach hundreds of thousands.

3.2.3.3 How to model when a device has both sub-devices and data points?

• Each device has multiple sub-devices and data point information. It is recommended to create a table for each type of device for management.