This is an automated email from the ASF dual-hosted git repository.
CritasWang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iotdb-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 19774980 Add basic concepts in table management (#1170)
19774980 is described below
commit 19774980260b54a3ed6b2e8f698f9342189a671d
Author: leto-bbq <[email protected]>
AuthorDate: Thu Jun 25 16:32:59 2026 +0800
Add basic concepts in table management (#1170)
---
.../Table/Basic-Concept/Table-Management_apache.md | 58 ++++++++++++++++-----
.../Basic-Concept/Table-Management_apache.md | 58 ++++++++++++++++-----
.../Table/Basic-Concept/Table-Management_apache.md | 60 +++++++++++++++++-----
.../Basic-Concept/Table-Management_apache.md | 58 ++++++++++++++++-----
4 files changed, 185 insertions(+), 49 deletions(-)
diff --git
a/src/UserGuide/Master/Table/Basic-Concept/Table-Management_apache.md
b/src/UserGuide/Master/Table/Basic-Concept/Table-Management_apache.md
index 05642e03..db0b743a 100644
--- a/src/UserGuide/Master/Table/Basic-Concept/Table-Management_apache.md
+++ b/src/UserGuide/Master/Table/Basic-Concept/Table-Management_apache.md
@@ -21,15 +21,49 @@
# Table Management
-Before starting to use the table management functionality, we recommend
familiarizing yourself with the following related background knowledge for a
better understanding and application of the table management features:
-* [Timeseries Data
Model](../Background-knowledge/Navigating_Time_Series_Data_apache.md):
Understand the basic concepts and characteristics of time series data to
establish a foundation for data modeling.
-* [Modeling Scheme
Design](../Background-knowledge/Data-Model-and-Terminology_apache.md): Master
the IoTDB time series model and its applicable scenarios to provide a design
basis for table management.
+In the table model, it is recommended that one table corresponds to one type
of device, for managing time series data of such devices. Devices of the same
type usually have the same or similar set of measurement points, such as wind
turbines, vehicles, production equipment or monitoring objects of the same
category.
-## 1. Table Management
+## 1. Basic Concepts
-### 1.1 Create a Table
+### 1.1 Table
-#### 1.1.1 Manually create a table with CREATE
+Tables are generally used to store time series data for the same type of
device. During data modeling, device identification information can be designed
as TAG columns, static device descriptions as ATTRIBUTE columns, and
time-varying collected values as FIELD columns.
+
+### 1.2 Time Column, Tag Column, Attribute Column and Measurement Column
+
+
+
+The table structure in the table model is generally shown in the figure above.
Columns can be classified into the following categories by purpose:
+
+| Concept | Description |
+| ------- | ----------- |
+| Time Column (TIME) | Each table must contain one time column of the
TIMESTAMP data type, which records the timestamp corresponding to each data
point. |
+| Tag Column (TAG) | Used to identify devices and can serve as the composite
primary key of a device. It typically stores information for locating devices,
such as region, plant, and device ID. Values in tag columns usually do not
change over time. |
+| Attribute Column (ATTRIBUTE) | Used to describe static attributes of a
device, such as model, manufacturer, and maintenance information. Attribute
columns do not change over time and can be added or updated. |
+| Measurement Column (FIELD) | Used to store physical quantities or metrics
collected from devices, whose values change over time, such as temperature,
humidity, current, voltage, and status. |
+
+In terms of query filtering efficiency, the general priority order is: time
column and tag columns first, followed by attribute columns, and measurement
columns last.
+
+### 1.3 Devices and Measurement Points
+
+In the table model, a device is uniquely identified by the combination of
values from all TAG columns in a table. For example, if a table contains three
TAG columns: `region`, `plant_id`, and `device_id`, each unique combination of
`region + plant_id + device_id` represents an independent device.
+
+Measurement points correspond to FIELD columns in the table. One FIELD column
for a single device generates multiple data points over time, and these
time-ordered data points form a time series.
+
+Therefore, the number of measurement points per table in the table model can
be expressed by the following formula:
+`Number of measurement points per table = Number of devices × Number of FIELD
columns`
+
+### 1.4 Table-Level TTL
+
+The TTL of a table defaults to the TTL of its parent database. If a table is
configured with a separate TTL, the table-level TTL takes precedence. Proper
use of table-level TTL allows different data retention periods to be set for
different business tables.
+
+For a more detailed introduction to TTL features, see: [TTL Delete
Data](../Basic-Concept/TTL-Delete-Data_apache.md)
+
+For further information on the IoTDB tree-table twin model, model selection
methods and typical modeling solutions, please refer to [Modeling Scheme
Design](../Background-knowledge/Data-Model-and-Terminology_apache.md).
+
+## 2. Table Management
+
+### 2.1 Create a Table
Manually create a table within the current or specified database.The format is
"database name. table name".
@@ -111,7 +145,7 @@ CREATE TABLE table1 (
Note: If your terminal does not support multi-line paste (e.g., Windows CMD),
please reformat the SQL statement into a single line before execution.
-### 1.2 View Tables
+### 2.2 View Tables
Used to view all tables and their properties in the current or a specified
database.
@@ -143,7 +177,7 @@ show tables details from database1;
+---------------+-----------+------+-------+
```
-### 1.3 View Table Columns
+### 2.3 View Table Columns
Used to view column names, data types, categories, and states of a table.
@@ -183,7 +217,7 @@ desc table1 details;
```
-### 1.4 View Table Creation Statement
+### 2.4 View Table Creation Statement
Retrieves the complete definition statement of a table or view under the table
model. This feature automatically fills in all default values that were omitted
during creation, so the displayed statement may differ from the original CREATE
statement.
@@ -213,7 +247,7 @@ show create table table1;
```
-### 1.5 Update Tables
+### 2.5 Update Tables
Used to update a table, including adding or deleting columns and configuring
table properties.
@@ -254,7 +288,7 @@ COMMENT ON TABLE table1 IS 'table1';
COMMENT ON COLUMN table1.a IS null;
```
-### 1.6 Delete Tables
+### 2.6 Delete Tables
Used to delete a table.
@@ -268,4 +302,4 @@ DROP TABLE (IF EXISTS)? <TABLE_NAME>
```SQL
DROP TABLE table1;
-```
\ No newline at end of file
+```
diff --git
a/src/UserGuide/latest-Table/Basic-Concept/Table-Management_apache.md
b/src/UserGuide/latest-Table/Basic-Concept/Table-Management_apache.md
index 05642e03..db0b743a 100644
--- a/src/UserGuide/latest-Table/Basic-Concept/Table-Management_apache.md
+++ b/src/UserGuide/latest-Table/Basic-Concept/Table-Management_apache.md
@@ -21,15 +21,49 @@
# Table Management
-Before starting to use the table management functionality, we recommend
familiarizing yourself with the following related background knowledge for a
better understanding and application of the table management features:
-* [Timeseries Data
Model](../Background-knowledge/Navigating_Time_Series_Data_apache.md):
Understand the basic concepts and characteristics of time series data to
establish a foundation for data modeling.
-* [Modeling Scheme
Design](../Background-knowledge/Data-Model-and-Terminology_apache.md): Master
the IoTDB time series model and its applicable scenarios to provide a design
basis for table management.
+In the table model, it is recommended that one table corresponds to one type
of device, for managing time series data of such devices. Devices of the same
type usually have the same or similar set of measurement points, such as wind
turbines, vehicles, production equipment or monitoring objects of the same
category.
-## 1. Table Management
+## 1. Basic Concepts
-### 1.1 Create a Table
+### 1.1 Table
-#### 1.1.1 Manually create a table with CREATE
+Tables are generally used to store time series data for the same type of
device. During data modeling, device identification information can be designed
as TAG columns, static device descriptions as ATTRIBUTE columns, and
time-varying collected values as FIELD columns.
+
+### 1.2 Time Column, Tag Column, Attribute Column and Measurement Column
+
+
+
+The table structure in the table model is generally shown in the figure above.
Columns can be classified into the following categories by purpose:
+
+| Concept | Description |
+| ------- | ----------- |
+| Time Column (TIME) | Each table must contain one time column of the
TIMESTAMP data type, which records the timestamp corresponding to each data
point. |
+| Tag Column (TAG) | Used to identify devices and can serve as the composite
primary key of a device. It typically stores information for locating devices,
such as region, plant, and device ID. Values in tag columns usually do not
change over time. |
+| Attribute Column (ATTRIBUTE) | Used to describe static attributes of a
device, such as model, manufacturer, and maintenance information. Attribute
columns do not change over time and can be added or updated. |
+| Measurement Column (FIELD) | Used to store physical quantities or metrics
collected from devices, whose values change over time, such as temperature,
humidity, current, voltage, and status. |
+
+In terms of query filtering efficiency, the general priority order is: time
column and tag columns first, followed by attribute columns, and measurement
columns last.
+
+### 1.3 Devices and Measurement Points
+
+In the table model, a device is uniquely identified by the combination of
values from all TAG columns in a table. For example, if a table contains three
TAG columns: `region`, `plant_id`, and `device_id`, each unique combination of
`region + plant_id + device_id` represents an independent device.
+
+Measurement points correspond to FIELD columns in the table. One FIELD column
for a single device generates multiple data points over time, and these
time-ordered data points form a time series.
+
+Therefore, the number of measurement points per table in the table model can
be expressed by the following formula:
+`Number of measurement points per table = Number of devices × Number of FIELD
columns`
+
+### 1.4 Table-Level TTL
+
+The TTL of a table defaults to the TTL of its parent database. If a table is
configured with a separate TTL, the table-level TTL takes precedence. Proper
use of table-level TTL allows different data retention periods to be set for
different business tables.
+
+For a more detailed introduction to TTL features, see: [TTL Delete
Data](../Basic-Concept/TTL-Delete-Data_apache.md)
+
+For further information on the IoTDB tree-table twin model, model selection
methods and typical modeling solutions, please refer to [Modeling Scheme
Design](../Background-knowledge/Data-Model-and-Terminology_apache.md).
+
+## 2. Table Management
+
+### 2.1 Create a Table
Manually create a table within the current or specified database.The format is
"database name. table name".
@@ -111,7 +145,7 @@ CREATE TABLE table1 (
Note: If your terminal does not support multi-line paste (e.g., Windows CMD),
please reformat the SQL statement into a single line before execution.
-### 1.2 View Tables
+### 2.2 View Tables
Used to view all tables and their properties in the current or a specified
database.
@@ -143,7 +177,7 @@ show tables details from database1;
+---------------+-----------+------+-------+
```
-### 1.3 View Table Columns
+### 2.3 View Table Columns
Used to view column names, data types, categories, and states of a table.
@@ -183,7 +217,7 @@ desc table1 details;
```
-### 1.4 View Table Creation Statement
+### 2.4 View Table Creation Statement
Retrieves the complete definition statement of a table or view under the table
model. This feature automatically fills in all default values that were omitted
during creation, so the displayed statement may differ from the original CREATE
statement.
@@ -213,7 +247,7 @@ show create table table1;
```
-### 1.5 Update Tables
+### 2.5 Update Tables
Used to update a table, including adding or deleting columns and configuring
table properties.
@@ -254,7 +288,7 @@ COMMENT ON TABLE table1 IS 'table1';
COMMENT ON COLUMN table1.a IS null;
```
-### 1.6 Delete Tables
+### 2.6 Delete Tables
Used to delete a table.
@@ -268,4 +302,4 @@ DROP TABLE (IF EXISTS)? <TABLE_NAME>
```SQL
DROP TABLE table1;
-```
\ No newline at end of file
+```
diff --git
a/src/zh/UserGuide/Master/Table/Basic-Concept/Table-Management_apache.md
b/src/zh/UserGuide/Master/Table/Basic-Concept/Table-Management_apache.md
index d2ad3767..38d5a9a3 100644
--- a/src/zh/UserGuide/Master/Table/Basic-Concept/Table-Management_apache.md
+++ b/src/zh/UserGuide/Master/Table/Basic-Concept/Table-Management_apache.md
@@ -21,17 +21,51 @@
# 表管理
-在开始使用表管理功能前，推荐您先了解以下相关预备知识，以便更好地理解和应用表管理功能：
-*
[时序数据模型](../Background-knowledge/Navigating_Time_Series_Data_apache.md)：了解时序数据的基本概念与特点，帮助建立建模基础。
-* [建模方案设计](../Background-knowledge/Data-Model-and-Terminology_apache.md)：掌握
IoTDB 时序模型及适用场景，为表管理提供设计基础。
+在表模型中，推荐一张表对应一类设备，用于管理该类设备的时序数据。同类设备通常具有相同或相近的测点集合，例如同一类风机、车辆、生产设备或监控对象。
-## 1. 表管理
+## 1. 基础概念
-### 1.1 创建表
+### 1.1 表
-#### 1.1.1 通过 Create 语句手动创建表
+表通常用于承载同一类设备的时序数据。建模时可以将设备的标识信息设计为 TAG 列，将设备的静态描述设计为 ATTRIBUTE 列，将随时间变化的采集值设计为
FIELD 列。
-用于在当前数据库中创建表，也可以对任何指定数据库创建表，格式为“数据库名.表名”。
+### 1.2 时间列、标签列、属性列和测点列
+
+
+
+表模型中的表结构通常如上图所示，其中的列按照用途可分为以下几类：
+
+| 概念 | 说明
|
+| --------------------- |
--------------------------------------------------------------------------------------------------------------------
|
+| 时间列（TIME） | 每张表必须包含一个时间列，数据类型为 TIMESTAMP，用于记录数据点对应的时间。
|
+| 标签列（TAG） | 用于标识设备，可作为设备的联合主键，通常存放区域、场站、设备编号等用于定位设备的信息。标签列的值通常不随时间变化。 |
+| 属性列（ATTRIBUTE） | 用于描述设备的静态属性，例如型号、厂商、维护信息等。属性列不随时间变化，可新增或更新。
|
+| 测点列（FIELD） | 用于存储设备采集的物理量或指标，值随时间变化，例如温度、湿度、电流、电压、状态等。
|
+
+在查询筛选效率上，通常可理解为：时间列和标签列优先，其次是属性列，最后是测点列。
+
+### 1.3 设备与测点
+
+在表模型中，一个设备由一张表内全部 TAG 列的取值组合唯一标识。例如表中包含 `region`、`plant_id`、`device_id` 三个 TAG
列，则 `region + plant_id + device_id` 的每一种唯一组合表示一个独立设备。
+
+测点对应表中的 FIELD 列。一个设备的一列 FIELD 会随着时间产生多个数据点，这些按时间排列的数据点构成一条时间序列。
+
+因此，表模型下单表测点数可按以下公式理解：`单表测点数 = device 数量 x FIELD 列数量`。
+
+### 1.4 表级 TTL
+
+表的 TTL 默认为其所在数据库的 TTL。如果表单独设置了 TTL，则以表级 TTL 为准。合理使用表级 TTL 可以对不同业务表设置不同的数据保留周期。
+
+关于 TTL 更详细的功能介绍可查阅：[数据保留时间](../Basic-Concept/TTL-Delete-Data_apache.md)
+
+如需进一步了解 IoTDB
树表孪生模型、模型选择方式及典型建模方案，可参考[建模方案设计](../Background-knowledge/Data-Model-and-Terminology_apache.md)。
+
+
+## 2. 表管理
+
+### 2.1 创建表
+
+Create 语句用于在当前数据库中创建表，也可以对任何指定数据库创建表，格式为“数据库名.表名”。
**语法：**
@@ -110,7 +144,7 @@ CREATE TABLE table1 (
注意：若您使用的终端不支持多行粘贴（例如 Windows CMD），请将 SQL 语句调整为单行格式后再执行。
-### 1.2 查看表
+### 2.2 查看表
用于查看该数据库中或指定数据库中的所有表和表库的属性信息。
@@ -142,7 +176,7 @@ SHOW TABLES DETAILS FROM database1;
+---------------+-----------+------+-------+
```
-### 1.3 查看表的列
+### 2.3 查看表的列
用于查看表的列名、数据类型、类别、状态。
@@ -180,7 +214,7 @@ DESC table1 DETAILS;
+------------+---------+---------+------+------------+
```
-### 1.4 查看表的创建信息
+### 2.4 查看表的创建信息
用于获取表模型下表或视图的完整定义语句。该功能会自动补全创建时省略的所有默认值，因此结果集中所展示的语句可能与原始创建语句不同。
@@ -210,7 +244,7 @@ SHOW CREATE TABLE table1;
```
-### 1.5 修改表
+### 2.5 修改表
用于修改表，包括添加列、删除列以及设置表的属性。
@@ -258,7 +292,7 @@ COMMENT ON TABLE table1 IS 'table1';
COMMENT ON COLUMN table1.a IS null;
```
-### 1.6 删除表
+### 2.6 删除表
用于删除表。
@@ -272,4 +306,4 @@ DROP TABLE (IF EXISTS)? <TABLE_NAME>;
```SQL
DROP TABLE table1;
-```
\ No newline at end of file
+```
diff --git
a/src/zh/UserGuide/latest-Table/Basic-Concept/Table-Management_apache.md
b/src/zh/UserGuide/latest-Table/Basic-Concept/Table-Management_apache.md
index d2ad3767..6dce35a2 100644
--- a/src/zh/UserGuide/latest-Table/Basic-Concept/Table-Management_apache.md
+++ b/src/zh/UserGuide/latest-Table/Basic-Concept/Table-Management_apache.md
@@ -21,17 +21,51 @@
# 表管理
-在开始使用表管理功能前，推荐您先了解以下相关预备知识，以便更好地理解和应用表管理功能：
-*
[时序数据模型](../Background-knowledge/Navigating_Time_Series_Data_apache.md)：了解时序数据的基本概念与特点，帮助建立建模基础。
-* [建模方案设计](../Background-knowledge/Data-Model-and-Terminology_apache.md)：掌握
IoTDB 时序模型及适用场景，为表管理提供设计基础。
+在表模型中，推荐一张表对应一类设备，用于管理该类设备的时序数据。同类设备通常具有相同或相近的测点集合，例如同一类风机、车辆、生产设备或监控对象。
-## 1. 表管理
+## 1. 基础概念
-### 1.1 创建表
+### 1.1 表
-#### 1.1.1 通过 Create 语句手动创建表
+表通常用于承载同一类设备的时序数据。建模时可以将设备的标识信息设计为 TAG 列，将设备的静态描述设计为 ATTRIBUTE 列，将随时间变化的采集值设计为
FIELD 列。
-用于在当前数据库中创建表，也可以对任何指定数据库创建表，格式为“数据库名.表名”。
+### 1.2 时间列、标签列、属性列和测点列
+
+
+
+表模型中的表结构通常如上图所示，其中的列按照用途可分为以下几类：
+
+| 概念 | 说明
|
+| --------------------- |
--------------------------------------------------------------------------------------------------------------------
|
+| 时间列（TIME） | 每张表必须包含一个时间列，数据类型为 TIMESTAMP，用于记录数据点对应的时间。
|
+| 标签列（TAG） | 用于标识设备，可作为设备的联合主键，通常存放区域、场站、设备编号等用于定位设备的信息。标签列的值通常不随时间变化。 |
+| 属性列（ATTRIBUTE） | 用于描述设备的静态属性，例如型号、厂商、维护信息等。属性列不随时间变化，可新增或更新。
|
+| 测点列（FIELD） | 用于存储设备采集的物理量或指标，值随时间变化，例如温度、湿度、电流、电压、状态等。
|
+
+在查询筛选效率上，通常可理解为：时间列和标签列优先，其次是属性列，最后是测点列。
+
+### 1.3 设备与测点
+
+在表模型中，一个设备由一张表内全部 TAG 列的取值组合唯一标识。例如表中包含 `region`、`plant_id`、`device_id` 三个 TAG
列，则 `region + plant_id + device_id` 的每一种唯一组合表示一个独立设备。
+
+测点对应表中的 FIELD 列。一个设备的一列 FIELD 会随着时间产生多个数据点，这些按时间排列的数据点构成一条时间序列。
+
+因此，表模型下单表测点数可按以下公式理解：`单表测点数 = device 数量 x FIELD 列数量`。
+
+### 1.4 表级 TTL
+
+表的 TTL 默认为其所在数据库的 TTL。如果表单独设置了 TTL，则以表级 TTL 为准。合理使用表级 TTL 可以对不同业务表设置不同的数据保留周期。
+
+关于 TTL 更详细的功能介绍可查阅：[数据保留时间](../Basic-Concept/TTL-Delete-Data_apache.md)
+
+如需进一步了解 IoTDB
树表孪生模型、模型选择方式及典型建模方案，可参考[建模方案设计](../Background-knowledge/Data-Model-and-Terminology_apache.md)。
+
+
+## 2. 表管理
+
+### 2.1 创建表
+
+Create 语句用于在当前数据库中创建表，也可以对任何指定数据库创建表，格式为“数据库名.表名”。
**语法：**
@@ -110,7 +144,7 @@ CREATE TABLE table1 (
注意：若您使用的终端不支持多行粘贴（例如 Windows CMD），请将 SQL 语句调整为单行格式后再执行。
-### 1.2 查看表
+### 2.2 查看表
用于查看该数据库中或指定数据库中的所有表和表库的属性信息。
@@ -142,7 +176,7 @@ SHOW TABLES DETAILS FROM database1;
+---------------+-----------+------+-------+
```
-### 1.3 查看表的列
+### 2.3 查看表的列
用于查看表的列名、数据类型、类别、状态。
@@ -180,7 +214,7 @@ DESC table1 DETAILS;
+------------+---------+---------+------+------------+
```
-### 1.4 查看表的创建信息
+### 2.4 查看表的创建信息
用于获取表模型下表或视图的完整定义语句。该功能会自动补全创建时省略的所有默认值，因此结果集中所展示的语句可能与原始创建语句不同。
@@ -210,7 +244,7 @@ SHOW CREATE TABLE table1;
```
-### 1.5 修改表
+### 2.5 修改表
用于修改表，包括添加列、删除列以及设置表的属性。
@@ -258,7 +292,7 @@ COMMENT ON TABLE table1 IS 'table1';
COMMENT ON COLUMN table1.a IS null;
```
-### 1.6 删除表
+### 2.6 删除表
用于删除表。
