diff --git a/src/.vuepress/public/img/tree-to-table-1.png b/src/.vuepress/public/img/tree-to-table-1.png new file mode 100644 index 000000000..64f2b5497 Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-1.png differ diff --git a/src/.vuepress/public/img/tree-to-table-2.png b/src/.vuepress/public/img/tree-to-table-2.png new file mode 100644 index 000000000..8bd8b3074 Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-2.png differ diff --git a/src/.vuepress/public/img/tree-to-table-3.png b/src/.vuepress/public/img/tree-to-table-3.png new file mode 100644 index 000000000..3798666b3 Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-3.png differ diff --git a/src/.vuepress/public/img/tree-to-table-4.png b/src/.vuepress/public/img/tree-to-table-4.png new file mode 100644 index 000000000..5d1e93151 Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-4.png differ diff --git a/src/.vuepress/public/img/tree-to-table-5.png b/src/.vuepress/public/img/tree-to-table-5.png new file mode 100644 index 000000000..61c1eb493 Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-5.png differ diff --git a/src/.vuepress/public/img/tree-to-table-6.png b/src/.vuepress/public/img/tree-to-table-6.png new file mode 100644 index 000000000..9d0465c70 Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-6.png differ diff --git a/src/.vuepress/public/img/tree-to-table-7.png b/src/.vuepress/public/img/tree-to-table-7.png new file mode 100644 index 000000000..1c33773b5 Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-7.png differ diff --git a/src/.vuepress/public/img/tree-to-table-8.png b/src/.vuepress/public/img/tree-to-table-8.png new file mode 100644 index 000000000..e9d71e7fd Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-8.png differ diff --git a/src/.vuepress/public/img/tree-to-table-en-1.png b/src/.vuepress/public/img/tree-to-table-en-1.png new file mode 100644 index 000000000..064d2b6bf Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-en-1.png differ diff --git a/src/.vuepress/public/img/tree-to-table-en-2.png b/src/.vuepress/public/img/tree-to-table-en-2.png new file mode 100644 index 000000000..2c66904aa Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-en-2.png differ diff --git a/src/.vuepress/public/img/tree-to-table-en-3.png b/src/.vuepress/public/img/tree-to-table-en-3.png new file mode 100644 index 000000000..339f4a428 Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-en-3.png differ diff --git a/src/.vuepress/public/img/tree-to-table-en-4.png b/src/.vuepress/public/img/tree-to-table-en-4.png new file mode 100644 index 000000000..235e9923c Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-en-4.png differ diff --git a/src/.vuepress/public/img/tree-to-table-en-5.png b/src/.vuepress/public/img/tree-to-table-en-5.png new file mode 100644 index 000000000..b00467674 Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-en-5.png differ diff --git a/src/.vuepress/public/img/tree-to-table-en-6.png b/src/.vuepress/public/img/tree-to-table-en-6.png new file mode 100644 index 000000000..e13ab8617 Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-en-6.png differ diff --git a/src/.vuepress/public/img/tree-to-table-en-7.png b/src/.vuepress/public/img/tree-to-table-en-7.png new file mode 100644 index 000000000..94ac77b9f Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-en-7.png differ diff --git a/src/.vuepress/public/img/tree-to-table-en-8.png b/src/.vuepress/public/img/tree-to-table-en-8.png new file mode 100644 index 000000000..b8d52bc77 Binary files /dev/null and b/src/.vuepress/public/img/tree-to-table-en-8.png differ diff --git a/src/.vuepress/sidebar/V2.0.x/en-Table.ts b/src/.vuepress/sidebar/V2.0.x/en-Table.ts index b563a84e6..f83177115 100644 --- a/src/.vuepress/sidebar/V2.0.x/en-Table.ts +++ b/src/.vuepress/sidebar/V2.0.x/en-Table.ts @@ -102,6 +102,7 @@ export const enSidebar = { { text: 'Authority Management', link: 'Authority-Management' }, ], }, + { text: 'Tree-to-Table Mapping', link: 'Tree-to-Table' }, { text: 'System Maintenance', collapsible: true, diff --git a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts index 63378b2f4..b545e319f 100644 --- a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts +++ b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts @@ -93,6 +93,7 @@ export const zhSidebar = { collapsible: true, children: [{ text: '权限管理', link: 'Authority-Management' }], }, + { text: '树转表视图', link: 'Tree-to-Table' }, { text: '系统运维', collapsible: true, diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts b/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts index 247a7c120..93d0d1977 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts @@ -107,6 +107,7 @@ export const enSidebar = { ], }, { text: 'Tiered Storage', link: 'Tiered-Storage_timecho' }, + { text: 'Tree-to-Table Mapping', link: 'Tree-to-Table' }, { text: 'System Maintenance', collapsible: true, diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts index 2cda499e2..ef31507cb 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts @@ -96,6 +96,7 @@ export const zhSidebar = { children: [{ text: '权限管理', link: 'Authority-Management' }], }, { text: '多级存储', link: 'Tiered-Storage_timecho' }, + { text: '树转表视图', link: 'Tree-to-Table' }, { text: '系统运维', collapsible: true, diff --git a/src/UserGuide/Master/Table/User-Manual/Tree-to-Table.md b/src/UserGuide/Master/Table/User-Manual/Tree-to-Table.md new file mode 100644 index 000000000..6a155042f --- /dev/null +++ b/src/UserGuide/Master/Table/User-Manual/Tree-to-Table.md @@ -0,0 +1,581 @@ + +# Tree-to-Table Mapping + +## 1. Functional Overview + +IoTDB introduces a tree-to-table function, which enables the creation of table views from existing tree-model data. This allows querying via table views, achieving collaborative processing of both tree and table models for the same dataset: + +* During the data writing phase, the tree-model syntax is used, supporting flexible data ingestion and expansion. +* During the data analysis phase, the table-model syntax is adopted, allowing complex data analysis through standard SQL queries. + +![](/img/tree-to-table-en-1.png) + +> * This feature supports from version V2.0.5. +> * Table views are read-only, so data cannot be written through them. + + ## 2. Feature Description +### 2.1 Creating a Table View +#### 2.1.1 Syntax Definition + +```SQL +-- create (or replace) view on tree +CREATE + [OR REPLACE] + VIEW view_name ([viewColumnDefinition (',' viewColumnDefinition)*]) + [comment] + [RESTRICT] + [WITH properties] + AS prefixPath + +viewColumnDefinition + : column_name [dataType] TAG [comment] # tagColumn + | column_name [dataType] TIME [comment] # timeColumn + | column_name [dataType] FIELD [FROM original_measurement] [comment] # fieldColumn + ; + +comment + : COMMENT string + ; +``` + +> Note: Columns only support tags, fields, or time; attributes are not supported. + +#### 2.1.2 Syntax Explanation +1. **`prefixPath`** + +Corresponds to the path in the tree model. The last level of the path must be `**`, and no other levels can contain `*`or `**`. This path determines the subtree corresponding to the VIEW. + +2. **`view_name`** + +The name of the view, which follows the same rules as a table name (for specific constraints, refer to [Create Table](../Basic-Concept/Table-Management.md#\_1-1-create-a-table)), e.g., `db.view`. + +3. **`viewColumnDefinition`** + +* `TAG`: Each TAG column corresponds, in order, to the path nodes at the levels following the `prefixPath`. +* `FIELD`: A FIELD column corresponds to a measurement (leaf node) in the tree model. + * If a FIELD column is specified, the column name uses the declared `column_name`. + * If `original_measurement`is declared, it maps directly to that measurement in the tree model. Otherwise, the lowercase `column_name`is used as the measurement name for mapping. + * Mapping multiple FIELD columns to the same measurement name in the tree model is not supported. + * If the `dataType`for a FIELD column is not specified, the system defaults to the data type of the mapped measurement in the tree model. + * If a device in the tree model does not contain certain declared FIELD columns, or if their data types are inconsistent with the declared FIELD columns, the value for that FIELD column will always be `NULL`when querying that device. + * If no FIELD columns are specified, the system automatically scans for all measurements under the `prefixPath`subtree (including all ordinary sequence measurements and measurements defined in any templates whose mounted paths overlap with the `prefixPath`) during creation. The column names will use the measurement names from the tree model. + * The tree model cannot have measurements with the same name (case-insensitive) but different data types. + +4. **`WITH properties`** + +Currently, only TTL is supported. It indicates that data older than TTL (in milliseconds) will not be displayed in query results, i.e., effectively `WHERE time > now() - TTL`. If a TTL is also set in the tree model, the query uses the smaller value of the two. + +> Note: The table view's TTL does not affect the actual TTL of the devices in the tree model. When data reaches the TTL set in the tree model, it will be physically deleted by the system. + +5. **`OR REPLACE`** + +A table and a view cannot have the same name. If a table with the same name already exists during creation, an error will be reported. If a view with the same name already exists, it will be replaced. + +6. **`RESTRICT`** + +This constrains the number of levels of the tree model devices that are matched (starting from the level below the `prefixPath`). If the `RESTRICT`keyword is present, only devices whose level count exactly equals the number of TAG columns are matched. Otherwise, devices whose level count is less than or equal to the number of TAG columns are matched. The default behavior is non-RESTRICT, meaning devices with a level count less than or equal to the number of TAG columns are matched. + +#### 2.1.3 Usage Example +1. Tree Model and Table View Schema + +![](/img/tree-to-table-en-2.png) + +2. Creating the Table View + +* Creation Statement: + +```SQL +CREATE OR REPLACE VIEW viewdb."wind_turbine" + (wind_turbine_group String TAG, + wind_turbine_number String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD + ) +with (ttl=604800000) +AS root.db.** +``` + +* Detailed Explanation + +This statement creates a view named `viewdb.wind_turbine`(an error will occur if `viewdb`does not exist). If the view already exists, it will be replaced. + +* It creates a table view for the time series mounted under the tree model path `root.db.**`. +* It has two `TAG` columns, `wind_turbine_group `and `wind_turbine_number`, so the table view will only include devices from the 3rd level of the original tree model. +* It has two `FIELD`columns, `voltage` and `current`. Here, these `FIELD` columns correspond to measurement names in the tree model that are also `voltage` and `current`, and only select time series of type `DOUBLE`. + +**Renaming measurement requirement:** + +If the measurement name in the tree model is `current_new`, but you want the corresponding `FIELD` column name in the table view to be `current`, the SQL should be changed as follows: + +```SQL +CREATE OR REPLACE VIEW viewdb."wind_turbine" + (wind_turbine_group String TAG, + wind_turbine_number String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD FROM current_new + ) +with (ttl=604800000) +AS root.db.** +``` + +### 2.2 Modifying a Table View +#### 2.2.1 Syntax Definition + +The ALTER VIEW function supports modifying the view name, adding columns, renaming columns, deleting columns, setting the view's TTL property, and adding comments via COMMENT. + +```SQL +-- Rename view +ALTER VIEW [IF EXISTS] viewName RENAME TO to=identifier + +-- Add a column to the view +ALTER VIEW [IF EXISTS] viewName ADD COLUMN [IF NOT EXISTS] viewColumnDefinition +viewColumnDefinition + : column_name [dataType] TAG # tagColumn + | column_name [dataType] FIELD [FROM original_measurement] # fieldColumn + +-- Rename a column in the view +ALTER VIEW [IF EXISTS] viewName RENAME COLUMN [IF EXISTS] oldName TO newName + +-- Delete a column from the view +ALTER VIEW [IF EXISTS] viewName DROP COLUMN [IF EXISTS] columnName + +-- Modify the view's TTL +ALTER VIEW [IF EXISTS] viewName SET PROPERTIES propertyAssignments + +-- Add comments +COMMENT ON VIEW qualifiedName IS (string | NULL) #commentView +COMMENT ON COLUMN qualifiedName '.' column=identifier IS (string | NULL) #commentColumn +``` + +#### 2.2.2 Syntax Explanation +1. The `SET PROPERTIES`operation currently only supports configuring the TTL property for the table view. +2. The `DROP COLUMN`function only supports deleting FIELD columns; TAG columns cannot be deleted. +3. Modifying the comment will overwrite the original comment. If set to `null`, the previous comment will be erased. +#### 2.2.3 Usage Examples + +```SQL +-- Rename view +ALTER VIEW IF EXISTS tableview1 RENAME TO tableview + +-- Add a column to the view +ALTER VIEW IF EXISTS tableview ADD COLUMN IF NOT EXISTS temperature float field + +-- Rename a column in the view +ALTER VIEW IF EXISTS tableview RENAME COLUMN IF EXISTS temperature TO temp + +-- Delete a column from the view +ALTER VIEW IF EXISTS tableview DROP COLUMN IF EXISTS temp + +-- Modify the view's TTL +ALTER VIEW IF EXISTS tableview SET PROPERTIES TTL=3600 + +-- Add comments +COMMENT ON VIEW tableview IS 'Tree to Table' +COMMENT ON COLUMN tableview.status is Null +``` + +### 2.3 Deleting a Table View +#### 2.3.1 Syntax Definition + +```SQL +DROP VIEW [IF EXISTS] viewName +``` + +#### 2.3.2 Usage Example + +```SQL +DROP VIEW IF EXISTS tableview +``` + +### 2.4 Viewing Table Views +#### 2.4.1 **`Show Tables`** +1. Syntax Definition + +```SQL +SHOW TABLES (DETAILS)? ((FROM | IN) database_name)? +``` + +2. Syntax Explanation + +The `SHOW TABLES (DETAILS)`statement displays the type information of tables or views through the `TABLE_TYPE`field in the result set: + +| Type | `TABLE_TYPE`Field Value | +| -------------------------------------------- | ----------------------------- | +| Ordinary Table（Table) | `BASE TABLE` | +| Tree-to-Table View （Tree View) | `VIEW FROM TREE` | +| System Table（Iinformation\_schema.Tables) | `SYSTEM VIEW` | + +3. Usage Examples + +```SQL +IoTDB> show tables details from database1 ++-----------+-----------+------+---------------+--------------+ +| TableName| TTL(ms)|Status| Comment| TableType| ++-----------+-----------+------+---------------+--------------+ +| tableview| INF| USING| Tree to Table |VIEW FROM TREE| +| table1|31536000000| USING| null| BASE TABLE| +| table2|31536000000| USING| null| BASE TABLE| ++-----------+-----------+------+---------------+--------------+ + +IoTDB> show tables details from information_schema ++--------------+-------+------+-------+-----------+ +| TableName|TTL(ms)|Status|Comment| TableType| ++--------------+-------+------+-------+-----------+ +| columns| INF| USING| null|SYSTEM VIEW| +| config_nodes| INF| USING| null|SYSTEM VIEW| +|configurations| INF| USING| null|SYSTEM VIEW| +| data_nodes| INF| USING| null|SYSTEM VIEW| +| databases| INF| USING| null|SYSTEM VIEW| +| functions| INF| USING| null|SYSTEM VIEW| +| keywords| INF| USING| null|SYSTEM VIEW| +| models| INF| USING| null|SYSTEM VIEW| +| nodes| INF| USING| null|SYSTEM VIEW| +| pipe_plugins| INF| USING| null|SYSTEM VIEW| +| pipes| INF| USING| null|SYSTEM VIEW| +| queries| INF| USING| null|SYSTEM VIEW| +| regions| INF| USING| null|SYSTEM VIEW| +| subscriptions| INF| USING| null|SYSTEM VIEW| +| tables| INF| USING| null|SYSTEM VIEW| +| topics| INF| USING| null|SYSTEM VIEW| +| views| INF| USING| null|SYSTEM VIEW| ++--------------+-------+------+-------+-----------+ +``` + +#### 2.4.2 **`Show Create Table/View`** +1. Syntax Definition + +```SQL +SHOW CREATE TABLE|VIEW viewname; +``` + +2. Syntax Explanation + +* The `SHOW CREATE TABLE`statement can be used to display the complete creation information for ordinary tables or views. +* The `SHOW CREATE VIEW`statement can only be used to display the complete creation information for views. +* Neither statement can be used to display system tables. + +3. Usage Examples + +```SQL +IoTDB> show create table tableview ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| View| Create View| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|tableview|CREATE VIEW "tableview" ("device" STRING TAG,"model" STRING TAG,"status" BOOLEAN FIELD,"hardware" STRING FIELD) COMMENT '树转表' WITH (ttl=INF) AS root.ln.**| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +IoTDB> show create view tableview ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| View| Create View| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|tableview|CREATE VIEW "tableview" ("device" STRING TAG,"model" STRING TAG,"status" BOOLEAN FIELD,"hardware" STRING FIELD) COMMENT '表视图' WITH (ttl=INF) AS root.ln.**| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``` + +### 2.5 Query Differences Between Non-aligned and Aligned Devices + +Queries on tree-to-table views may yield different results compared to equivalent tree model `ALIGN BY DEVICE`queries when dealing with null values in aligned and non-aligned devices. + +* Aligned Devices + * Tree Model Query Behavior:Rows where all selected time series have null values are not retained. + * Table View Query Behavior:Consistent with the table model, rows where all selected fields are null are retained. +* Non-aligned Devices + * Tree Model Query Behavior:Rows where all selected time series have null values are not retained. + * Table View Query Behavior:Consistent with the tree model, rows where all selected fields are null are not retained. +* Explanation Example + * Aligned + + ```SQL + -- Write data in tree model (aligned) + CREATE ALIGNED TIMESERIES root.db.battery.b1(voltage INT32, current FLOAT) + INSERT INTO root.db.battery.b1(time, voltage, current) aligned values (1, 1, 1) + INSERT INTO root.db.battery.b1(time, voltage, current) aligned values (2, null, 1) + + -- Create VIEW statement + CREATE VIEW view1 (battery_id TAG, voltage INT32 FIELD, current FLOAT FIELD) as root.db.battery.** + + -- Query + IoTDB> select voltage from view1 + +-------+ + |voltage| + +-------+ + | 1| + | null| + +-------+ + Total line number = 2 + ``` + + * Non-aligned + + ```SQL + -- Write data in tree model (non-aligned) + CREATE TIMESERIES root.db.battery.b1.voltage INT32 + CREATE TIMESERIES root.db.battery.b1.current FLOAT + INSERT INTO root.db.battery.b1(time, voltage, current) values (1, 1, 1) + INSERT INTO root.db.battery.b1(time, voltage, current) values (2, null, 1) + + -- Create VIEW statement + CREATE VIEW view1 (battery_id TAG, voltage INT32 FIELD, current FLOAT FIELD) as root.db.battery.** + + -- Query + IoTDB> select voltage from view1 + +-------+ + |voltage| + +-------+ + | 1| + +-------+ + Total line number = 1 + + -- Can only ensure all rows are retrieved if the query specifies all FIELD columns, or only non-FIELD columns + IoTDB> select voltage,current from view1 + +-------+-------+ + |voltage|current| + +-------+-------+ + | 1| 1.0| + | null| 1.0| + +-------+-------+ + Total line number = 2 + + IoTDB> select battery_id from view1 + +-----------+ + |battery_id| + +-----------+ + | b1| + | b1| + +-----------+ + Total line number = 2 + + -- If the query involves only some FIELD columns, the final number of rows depends on the number of rows after aligning the specified FIELD columns by timestamp. + IoTDB> select time,voltage from view1 + +-----------------------------+-------+ + | time|voltage| + +-----------------------------+-------+ + |1970-01-01T08:00:00.001+08:00| 1| + +-----------------------------+-------+ + Total line number = 1 + ``` + +## 3. Scenario Examples +### 3.1 Managing Multiple Device Types in the Original Tree Model + +* The scenario involves managing different types of devices, each with its own hierarchical path and set of measurements. +* During Data Writing: Create branches under the database node according to device type. Each device type can have a different measurement structure. +* During Querying: Create a separate table for each device type. Each table will have different tags and sets of measurements. + +![](/img/tree-to-table-en-3.png) + +**SQL for Creating a Table View:** + +```SQL +-- Wind Turbine Table +CREATE VIEW viewdb.wind_turbine + (wind_turbine_group String TAG, + wind_turbine_number String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD + ) +AS root.db.wind_turbine.** + +-- Motor Table +CREATE VIEW viewdb.motor + ( motor_group String TAG, + motor_number String TAG, + power FLOAT FIELD, + electricity FLOAT FIELD, + temperature FLOAT FIELD + ) +AS root.db.motor.** +``` + +### 3.2 Original Tree Model Contains Only Measurements, No Devices + +This scenario occurs in systems like station monitoring where each measurement has a unique identifier but cannot be mapped to specific physical devices. + +> Wide Table Form + +![](/img/tree-to-table-en-4.png) + +**SQL for Creating a Table View:** + +```SQL +CREATE VIEW viewdb.machine + (DCS_PIT_02105A DOUBLE FIELD, + DCS_PIT_02105B DOUBLE FIELD, + DCS_PIT_02105C DOUBLE FIELD, + ... + DCS_XI_02716A DOUBLE FIELD + ) +AS root.db.** +``` + +### 3.3 Original Tree Model Where a Device Has Both Sub-devices and Measurements + +This scenario is common in energy storage systems where each hierarchical level requires monitoring of parameters like voltage and current. + +* Writing Phase: Model according to physical monitoring points at each hierarchical level +* Querying Phase: Create multiple tables based on device categories to manage information at each structural level + +![](/img/tree-to-table-en-5.png) + +**SQL for Creating a Table View:** + +```SQL +-- Battery Compartment +CREATE VIEW viewdb.battery_compartment + (station String TAG, + batter_compartment String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD + ) +RESTRICT +AS root.db.** + +-- Battery Stack +CREATE VIEW viewdb.battery_stack + (station String TAG, + batter_compartment String TAG, + battery_stack String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD + ) +RESTRICT +AS root.db.** + +-- Battery Cluster +CREATE VIEW viewdb.battery_cluster + (station String TAG, + batter_compartment String TAG, + battery_stackString TAG, + battery_cluster String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD + ) +RESTRICT +AS 'root.db.**' + +-- Battery Ceil +CREATE VIEW viewdb.battery_ceil + (station String TAG, + batter_compartment String TAG, + battery_cluster String TAG, + battery_cluster String TAG, + battery_ceil String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD + ) +RESTRICT +AS root.db.** +``` + +### 3.4 Original Tree Model Where a Device Has Only One Measurement Under It + +> Narrow Table Form + +#### 3.4.1 All Measurements Have the Same Data Type + +![](/img/tree-to-table-en-6.png) + +**SQL for Creating a Table View:** + +```SQL +CREATE VIEW viewdb.machine + ( + sensor_id STRING TAG, + value DOUBLE FIELD + ) +AS root.db.** +``` + +#### 3.4.2 Measurements Have Different Data Types +##### 3.4.2.1 Create a Narrow Table View for Each Data Type of Measurement + +**Advantage: ​**The number of table views is constant, only related to the data types in the system. + +**Disadvantage: ​**When querying the value of a specific measurement, its data type must be known in advance to determine which table view to query. + +![](/img/tree-to-table-en-7.png) + +**SQL for Creating a Table View:** + +```SQL +CREATE VIEW viewdb.machine_float + ( + sensor_id STRING TAG, + value FLOAT FIELD + ) +AS root.db.** + +CREATE VIEW viewdb.machine_double + ( + sensor_id STRING TAG, + value DOUBLE FIELD + ) +AS root.db.** + +CREATE VIEW viewdb.machine_int32 + ( + sensor_id STRING TAG, + value INT32 FIELD + ) +AS root.db.** + +CREATE VIEW viewdb.machine_int64 + ( + sensor_id STRING TAG, + value INT64 FIELD + ) +AS root.db.** + +... +``` + +##### 3.4.2.2 Create a Table for Each Measurement + +**Advantage: ​**When querying the value of a specific measurement, there's no need to first check its data type to determine which table to query, making the process simple and convenient. + +**Disadvantage: ​**When there are a large number of measurements, it will introduce too many table views, requiring the writing of a large number of view creation statements. + +![](/img/tree-to-table-en-8.png) + +**SQL for Creating a Table View:** + +```SQL +CREATE VIEW viewdb.DCS_PIT_02105A + ( + value FLOAT FIELD + ) +AS root.db.DCS_PIT_02105A.** + +CREATE VIEW viewdb.DCS_PIT_02105B + ( + value DOUBLE FIELD + ) +AS root.db.DCS_PIT_02105B.** + +CREATE VIEW viewdb.DCS_XI_02716A + ( + value INT64 FIELD + ) +AS root.db.DCS_XI_02716A.** + +...... +``` diff --git a/src/UserGuide/latest-Table/User-Manual/Tree-to-Table.md b/src/UserGuide/latest-Table/User-Manual/Tree-to-Table.md new file mode 100644 index 000000000..c05049f06 --- /dev/null +++ b/src/UserGuide/latest-Table/User-Manual/Tree-to-Table.md @@ -0,0 +1,582 @@ + + +# Tree-to-Table Mapping + +## 1. Functional Overview + +IoTDB introduces a tree-to-table function, which enables the creation of table views from existing tree-model data. This allows querying via table views, achieving collaborative processing of both tree and table models for the same dataset: + +* During the data writing phase, the tree-model syntax is used, supporting flexible data ingestion and expansion. +* During the data analysis phase, the table-model syntax is adopted, allowing complex data analysis through standard SQL queries. + +![](/img/tree-to-table-en-1.png) + +> * This feature supports from version V2.0.5. +> * Table views are read-only, so data cannot be written through them. + + ## 2. Feature Description +### 2.1 Creating a Table View +#### 2.1.1 Syntax Definition + +```SQL +-- create (or replace) view on tree +CREATE + [OR REPLACE] + VIEW view_name ([viewColumnDefinition (',' viewColumnDefinition)*]) + [comment] + [RESTRICT] + [WITH properties] + AS prefixPath + +viewColumnDefinition + : column_name [dataType] TAG [comment] # tagColumn + | column_name [dataType] TIME [comment] # timeColumn + | column_name [dataType] FIELD [FROM original_measurement] [comment] # fieldColumn + ; + +comment + : COMMENT string + ; +``` + +> Note: Columns only support tags, fields, or time; attributes are not supported. + +#### 2.1.2 Syntax Explanation +1. **`prefixPath`** + +Corresponds to the path in the tree model. The last level of the path must be `**`, and no other levels can contain `*`or `**`. This path determines the subtree corresponding to the VIEW. + +2. **`view_name`** + +The name of the view, which follows the same rules as a table name (for specific constraints, refer to [Create Table](../Basic-Concept/Table-Management.md#\_1-1-create-a-table)), e.g., `db.view`. + +3. **`viewColumnDefinition`** + +* `TAG`: Each TAG column corresponds, in order, to the path nodes at the levels following the `prefixPath`. +* `FIELD`: A FIELD column corresponds to a measurement (leaf node) in the tree model. + * If a FIELD column is specified, the column name uses the declared `column_name`. + * If `original_measurement`is declared, it maps directly to that measurement in the tree model. Otherwise, the lowercase `column_name`is used as the measurement name for mapping. + * Mapping multiple FIELD columns to the same measurement name in the tree model is not supported. + * If the `dataType`for a FIELD column is not specified, the system defaults to the data type of the mapped measurement in the tree model. + * If a device in the tree model does not contain certain declared FIELD columns, or if their data types are inconsistent with the declared FIELD columns, the value for that FIELD column will always be `NULL`when querying that device. + * If no FIELD columns are specified, the system automatically scans for all measurements under the `prefixPath`subtree (including all ordinary sequence measurements and measurements defined in any templates whose mounted paths overlap with the `prefixPath`) during creation. The column names will use the measurement names from the tree model. + * The tree model cannot have measurements with the same name (case-insensitive) but different data types. + +4. **`WITH properties`** + +Currently, only TTL is supported. It indicates that data older than TTL (in milliseconds) will not be displayed in query results, i.e., effectively `WHERE time > now() - TTL`. If a TTL is also set in the tree model, the query uses the smaller value of the two. + +> Note: The table view's TTL does not affect the actual TTL of the devices in the tree model. When data reaches the TTL set in the tree model, it will be physically deleted by the system. + +5. **`OR REPLACE`** + +A table and a view cannot have the same name. If a table with the same name already exists during creation, an error will be reported. If a view with the same name already exists, it will be replaced. + +6. **`RESTRICT`** + +This constrains the number of levels of the tree model devices that are matched (starting from the level below the `prefixPath`). If the `RESTRICT`keyword is present, only devices whose level count exactly equals the number of TAG columns are matched. Otherwise, devices whose level count is less than or equal to the number of TAG columns are matched. The default behavior is non-RESTRICT, meaning devices with a level count less than or equal to the number of TAG columns are matched. + +#### 2.1.3 Usage Example +1. Tree Model and Table View Schema + +![](/img/tree-to-table-en-2.png) + +2. Creating the Table View + +* Creation Statement: + +```SQL +CREATE OR REPLACE VIEW viewdb."wind_turbine" + (wind_turbine_group String TAG, + wind_turbine_number String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD + ) +with (ttl=604800000) +AS root.db.** +``` + +* Detailed Explanation + +This statement creates a view named `viewdb.wind_turbine`(an error will occur if `viewdb`does not exist). If the view already exists, it will be replaced. + +* It creates a table view for the time series mounted under the tree model path `root.db.**`. +* It has two `TAG` columns, `wind_turbine_group `and `wind_turbine_number`, so the table view will only include devices from the 3rd level of the original tree model. +* It has two `FIELD`columns, `voltage` and `current`. Here, these `FIELD` columns correspond to measurement names in the tree model that are also `voltage` and `current`, and only select time series of type `DOUBLE`. + +**Renaming measurement requirement:** + +If the measurement name in the tree model is `current_new`, but you want the corresponding `FIELD` column name in the table view to be `current`, the SQL should be changed as follows: + +```SQL +CREATE OR REPLACE VIEW viewdb."wind_turbine" + (wind_turbine_group String TAG, + wind_turbine_number String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD FROM current_new + ) +with (ttl=604800000) +AS root.db.** +``` + +### 2.2 Modifying a Table View +#### 2.2.1 Syntax Definition + +The ALTER VIEW function supports modifying the view name, adding columns, renaming columns, deleting columns, setting the view's TTL property, and adding comments via COMMENT. + +```SQL +-- Rename view +ALTER VIEW [IF EXISTS] viewName RENAME TO to=identifier + +-- Add a column to the view +ALTER VIEW [IF EXISTS] viewName ADD COLUMN [IF NOT EXISTS] viewColumnDefinition +viewColumnDefinition + : column_name [dataType] TAG # tagColumn + | column_name [dataType] FIELD [FROM original_measurement] # fieldColumn + +-- Rename a column in the view +ALTER VIEW [IF EXISTS] viewName RENAME COLUMN [IF EXISTS] oldName TO newName + +-- Delete a column from the view +ALTER VIEW [IF EXISTS] viewName DROP COLUMN [IF EXISTS] columnName + +-- Modify the view's TTL +ALTER VIEW [IF EXISTS] viewName SET PROPERTIES propertyAssignments + +-- Add comments +COMMENT ON VIEW qualifiedName IS (string | NULL) #commentView +COMMENT ON COLUMN qualifiedName '.' column=identifier IS (string | NULL) #commentColumn +``` + +#### 2.2.2 Syntax Explanation +1. The `SET PROPERTIES`operation currently only supports configuring the TTL property for the table view. +2. The `DROP COLUMN`function only supports deleting FIELD columns; TAG columns cannot be deleted. +3. Modifying the comment will overwrite the original comment. If set to `null`, the previous comment will be erased. +#### 2.2.3 Usage Examples + +```SQL +-- Rename view +ALTER VIEW IF EXISTS tableview1 RENAME TO tableview + +-- Add a column to the view +ALTER VIEW IF EXISTS tableview ADD COLUMN IF NOT EXISTS temperature float field + +-- Rename a column in the view +ALTER VIEW IF EXISTS tableview RENAME COLUMN IF EXISTS temperature TO temp + +-- Delete a column from the view +ALTER VIEW IF EXISTS tableview DROP COLUMN IF EXISTS temp + +-- Modify the view's TTL +ALTER VIEW IF EXISTS tableview SET PROPERTIES TTL=3600 + +-- Add comments +COMMENT ON VIEW tableview IS 'Tree to Table' +COMMENT ON COLUMN tableview.status is Null +``` + +### 2.3 Deleting a Table View +#### 2.3.1 Syntax Definition + +```SQL +DROP VIEW [IF EXISTS] viewName +``` + +#### 2.3.2 Usage Example + +```SQL +DROP VIEW IF EXISTS tableview +``` + +### 2.4 Viewing Table Views +#### 2.4.1 **`Show Tables`** +1. Syntax Definition + +```SQL +SHOW TABLES (DETAILS)? ((FROM | IN) database_name)? +``` + +2. Syntax Explanation + +The `SHOW TABLES (DETAILS)`statement displays the type information of tables or views through the `TABLE_TYPE`field in the result set: + +| Type | `TABLE_TYPE`Field Value | +| -------------------------------------------- | ----------------------------- | +| Ordinary Table（Table) | `BASE TABLE` | +| Tree-to-Table View （Tree View) | `VIEW FROM TREE` | +| System Table（Iinformation\_schema.Tables) | `SYSTEM VIEW` | + +3. Usage Examples + +```SQL +IoTDB> show tables details from database1 ++-----------+-----------+------+---------------+--------------+ +| TableName| TTL(ms)|Status| Comment| TableType| ++-----------+-----------+------+---------------+--------------+ +| tableview| INF| USING| Tree to Table |VIEW FROM TREE| +| table1|31536000000| USING| null| BASE TABLE| +| table2|31536000000| USING| null| BASE TABLE| ++-----------+-----------+------+---------------+--------------+ + +IoTDB> show tables details from information_schema ++--------------+-------+------+-------+-----------+ +| TableName|TTL(ms)|Status|Comment| TableType| ++--------------+-------+------+-------+-----------+ +| columns| INF| USING| null|SYSTEM VIEW| +| config_nodes| INF| USING| null|SYSTEM VIEW| +|configurations| INF| USING| null|SYSTEM VIEW| +| data_nodes| INF| USING| null|SYSTEM VIEW| +| databases| INF| USING| null|SYSTEM VIEW| +| functions| INF| USING| null|SYSTEM VIEW| +| keywords| INF| USING| null|SYSTEM VIEW| +| models| INF| USING| null|SYSTEM VIEW| +| nodes| INF| USING| null|SYSTEM VIEW| +| pipe_plugins| INF| USING| null|SYSTEM VIEW| +| pipes| INF| USING| null|SYSTEM VIEW| +| queries| INF| USING| null|SYSTEM VIEW| +| regions| INF| USING| null|SYSTEM VIEW| +| subscriptions| INF| USING| null|SYSTEM VIEW| +| tables| INF| USING| null|SYSTEM VIEW| +| topics| INF| USING| null|SYSTEM VIEW| +| views| INF| USING| null|SYSTEM VIEW| ++--------------+-------+------+-------+-----------+ +``` + +#### 2.4.2 **`Show Create Table/View`** +1. Syntax Definition + +```SQL +SHOW CREATE TABLE|VIEW viewname; +``` + +2. Syntax Explanation + +* The `SHOW CREATE TABLE`statement can be used to display the complete creation information for ordinary tables or views. +* The `SHOW CREATE VIEW`statement can only be used to display the complete creation information for views. +* Neither statement can be used to display system tables. + +3. Usage Examples + +```SQL +IoTDB> show create table tableview ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| View| Create View| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|tableview|CREATE VIEW "tableview" ("device" STRING TAG,"model" STRING TAG,"status" BOOLEAN FIELD,"hardware" STRING FIELD) COMMENT '树转表' WITH (ttl=INF) AS root.ln.**| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +IoTDB> show create view tableview ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| View| Create View| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|tableview|CREATE VIEW "tableview" ("device" STRING TAG,"model" STRING TAG,"status" BOOLEAN FIELD,"hardware" STRING FIELD) COMMENT '表视图' WITH (ttl=INF) AS root.ln.**| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``` + +### 2.5 Query Differences Between Non-aligned and Aligned Devices + +Queries on tree-to-table views may yield different results compared to equivalent tree model `ALIGN BY DEVICE`queries when dealing with null values in aligned and non-aligned devices. + +* Aligned Devices + * Tree Model Query Behavior:Rows where all selected time series have null values are not retained. + * Table View Query Behavior:Consistent with the table model, rows where all selected fields are null are retained. +* Non-aligned Devices + * Tree Model Query Behavior:Rows where all selected time series have null values are not retained. + * Table View Query Behavior:Consistent with the tree model, rows where all selected fields are null are not retained. +* Explanation Example + * Aligned + + ```SQL + -- Write data in tree model (aligned) + CREATE ALIGNED TIMESERIES root.db.battery.b1(voltage INT32, current FLOAT) + INSERT INTO root.db.battery.b1(time, voltage, current) aligned values (1, 1, 1) + INSERT INTO root.db.battery.b1(time, voltage, current) aligned values (2, null, 1) + + -- Create VIEW statement + CREATE VIEW view1 (battery_id TAG, voltage INT32 FIELD, current FLOAT FIELD) as root.db.battery.** + + -- Query + IoTDB> select voltage from view1 + +-------+ + |voltage| + +-------+ + | 1| + | null| + +-------+ + Total line number = 2 + ``` + + * Non-aligned + + ```SQL + -- Write data in tree model (non-aligned) + CREATE TIMESERIES root.db.battery.b1.voltage INT32 + CREATE TIMESERIES root.db.battery.b1.current FLOAT + INSERT INTO root.db.battery.b1(time, voltage, current) values (1, 1, 1) + INSERT INTO root.db.battery.b1(time, voltage, current) values (2, null, 1) + + -- Create VIEW statement + CREATE VIEW view1 (battery_id TAG, voltage INT32 FIELD, current FLOAT FIELD) as root.db.battery.** + + -- Query + IoTDB> select voltage from view1 + +-------+ + |voltage| + +-------+ + | 1| + +-------+ + Total line number = 1 + + -- Can only ensure all rows are retrieved if the query specifies all FIELD columns, or only non-FIELD columns + IoTDB> select voltage,current from view1 + +-------+-------+ + |voltage|current| + +-------+-------+ + | 1| 1.0| + | null| 1.0| + +-------+-------+ + Total line number = 2 + + IoTDB> select battery_id from view1 + +-----------+ + |battery_id| + +-----------+ + | b1| + | b1| + +-----------+ + Total line number = 2 + + -- If the query involves only some FIELD columns, the final number of rows depends on the number of rows after aligning the specified FIELD columns by timestamp. + IoTDB> select time,voltage from view1 + +-----------------------------+-------+ + | time|voltage| + +-----------------------------+-------+ + |1970-01-01T08:00:00.001+08:00| 1| + +-----------------------------+-------+ + Total line number = 1 + ``` + +## 3. Scenario Examples +### 3.1 Managing Multiple Device Types in the Original Tree Model + +* The scenario involves managing different types of devices, each with its own hierarchical path and set of measurements. +* During Data Writing: Create branches under the database node according to device type. Each device type can have a different measurement structure. +* During Querying: Create a separate table for each device type. Each table will have different tags and sets of measurements. + +![](/img/tree-to-table-en-3.png) + +**SQL for Creating a Table View:** + +```SQL +-- Wind Turbine Table +CREATE VIEW viewdb.wind_turbine + (wind_turbine_group String TAG, + wind_turbine_number String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD + ) +AS root.db.wind_turbine.** + +-- Motor Table +CREATE VIEW viewdb.motor + ( motor_group String TAG, + motor_number String TAG, + power FLOAT FIELD, + electricity FLOAT FIELD, + temperature FLOAT FIELD + ) +AS root.db.motor.** +``` + +### 3.2 Original Tree Model Contains Only Measurements, No Devices + +This scenario occurs in systems like station monitoring where each measurement has a unique identifier but cannot be mapped to specific physical devices. + +> Wide Table Form + +![](/img/tree-to-table-en-4.png) + +**SQL for Creating a Table View:** + +```SQL +CREATE VIEW viewdb.machine + (DCS_PIT_02105A DOUBLE FIELD, + DCS_PIT_02105B DOUBLE FIELD, + DCS_PIT_02105C DOUBLE FIELD, + ... + DCS_XI_02716A DOUBLE FIELD + ) +AS root.db.** +``` + +### 3.3 Original Tree Model Where a Device Has Both Sub-devices and Measurements + +This scenario is common in energy storage systems where each hierarchical level requires monitoring of parameters like voltage and current. + +* Writing Phase: Model according to physical monitoring points at each hierarchical level +* Querying Phase: Create multiple tables based on device categories to manage information at each structural level + +![](/img/tree-to-table-en-5.png) + +**SQL for Creating a Table View:** + +```SQL +-- Battery Compartment +CREATE VIEW viewdb.battery_compartment + (station String TAG, + batter_compartment String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD + ) +RESTRICT +AS root.db.** + +-- Battery Stack +CREATE VIEW viewdb.battery_stack + (station String TAG, + batter_compartment String TAG, + battery_stack String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD + ) +RESTRICT +AS root.db.** + +-- Battery Cluster +CREATE VIEW viewdb.battery_cluster + (station String TAG, + batter_compartment String TAG, + battery_stackString TAG, + battery_cluster String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD + ) +RESTRICT +AS 'root.db.**' + +-- Battery Ceil +CREATE VIEW viewdb.battery_ceil + (station String TAG, + batter_compartment String TAG, + battery_cluster String TAG, + battery_cluster String TAG, + battery_ceil String TAG, + voltage DOUBLE FIELD, + current DOUBLE FIELD + ) +RESTRICT +AS root.db.** +``` + +### 3.4 Original Tree Model Where a Device Has Only One Measurement Under It + +> Narrow Table Form + +#### 3.4.1 All Measurements Have the Same Data Type + +![](/img/tree-to-table-en-6.png) + +**SQL for Creating a Table View:** + +```SQL +CREATE VIEW viewdb.machine + ( + sensor_id STRING TAG, + value DOUBLE FIELD + ) +AS root.db.** +``` + +#### 3.4.2 Measurements Have Different Data Types +##### 3.4.2.1 Create a Narrow Table View for Each Data Type of Measurement + +**Advantage: ​**The number of table views is constant, only related to the data types in the system. + +**Disadvantage: ​**When querying the value of a specific measurement, its data type must be known in advance to determine which table view to query. + +![](/img/tree-to-table-en-7.png) + +**SQL for Creating a Table View:** + +```SQL +CREATE VIEW viewdb.machine_float + ( + sensor_id STRING TAG, + value FLOAT FIELD + ) +AS root.db.** + +CREATE VIEW viewdb.machine_double + ( + sensor_id STRING TAG, + value DOUBLE FIELD + ) +AS root.db.** + +CREATE VIEW viewdb.machine_int32 + ( + sensor_id STRING TAG, + value INT32 FIELD + ) +AS root.db.** + +CREATE VIEW viewdb.machine_int64 + ( + sensor_id STRING TAG, + value INT64 FIELD + ) +AS root.db.** + +... +``` + +##### 3.4.2.2 Create a Table for Each Measurement + +**Advantage: ​**When querying the value of a specific measurement, there's no need to first check its data type to determine which table to query, making the process simple and convenient. + +**Disadvantage: ​**When there are a large number of measurements, it will introduce too many table views, requiring the writing of a large number of view creation statements. + +![](/img/tree-to-table-en-8.png) + +**SQL for Creating a Table View:** + +```SQL +CREATE VIEW viewdb.DCS_PIT_02105A + ( + value FLOAT FIELD + ) +AS root.db.DCS_PIT_02105A.** + +CREATE VIEW viewdb.DCS_PIT_02105B + ( + value DOUBLE FIELD + ) +AS root.db.DCS_PIT_02105B.** + +CREATE VIEW viewdb.DCS_XI_02716A + ( + value INT64 FIELD + ) +AS root.db.DCS_XI_02716A.** + +...... +``` diff --git a/src/zh/UserGuide/Master/Table/User-Manual/Tree-to-Table.md b/src/zh/UserGuide/Master/Table/User-Manual/Tree-to-Table.md new file mode 100644 index 000000000..fc6a446c5 --- /dev/null +++ b/src/zh/UserGuide/Master/Table/User-Manual/Tree-to-Table.md @@ -0,0 +1,579 @@ + +# 树转表视图 + +## 1. 功能概述 + +IoTDB 提供了树转表功能，支持通过创建表视图的方式，将已存在的树模型数据转化为表视图，进而通过表视图进行查询，实现了对同一份数据的树模型和表模型协同处理： + +* 数据写入阶段，采用树模型语法，支持数据灵活接入和扩展。 +* 数据分析阶段，采用表模型语法，支持通过标准 SQL 查询语言，执行复杂的数据分析。 + +![](/img/tree-to-table-1.png) + +> - V2.0.5 及以后版本支持该功能。 +> - 表视图只读，不允许通过表视图写入数据。 + +## 2. 功能介绍 +### 2.1 创建表视图 +#### 2.1.1 语法定义 + +```SQL +-- create (or replace) view on tree +CREATE + [OR REPLACE] + VIEW view_name ([viewColumnDefinition (',' viewColumnDefinition)*]) + [comment] + [RESTRICT] + [WITH properties] + AS prefixPath + +viewColumnDefinition + : column_name [dataType] TAG [comment] # tagColumn + | column_name [dataType] TIME [comment] # timeColumn + | column_name [dataType] FIELD [FROM original_measurement] [comment] # fieldColumn + ; + +comment + : COMMENT string + ; +``` + +> 注意：列仅支持 tag / field / time，不支持 attribute。 + +#### 2.1.2 语法说明 +1. **`prefixPath`** + +对应树模型的路径，路径最后一级必须为 `**`，且其他层级均不能出现 `*` 或 `**`。该路径确定 VIEW 对应的子树。 + +2. **`view_name`** + +视图名称，与表名相同（具体约束可参考[创建表](../Basic-Concept/Table-Management.md#\_1-1-创建表)），如 db.view。 + +3. **`viewColumnDefinition`** + +* `TAG`：每个 Tag 列按顺序对应`prefixPath`后面层级的路径节点。 +* `FIELD`：FIELD 列对应树模型中的测点（叶子节点）。 + * 若指定了 FIELD 列，则列名使用声明中的`column_name`。 + * 若声明了 `original_measurement`，则直接映射到树模型该测点。否则取小写`column_name` 作为测点名进行树模型映射。 + * 不支持多个 FIELD 映射到树模型同名测点。 + * 若未指定 FIELD 列的 `dataType`，则默认获取树模型映射测点的数据类型。 + * 若树模型中的设备不包含某些声明的 FIELD 列，或与声明的 FIELD 列的数据类型不一致，则在查询该设备时，该 FIELD 列的值永远为 NULL。 + * 若未指定 FIELD 列，则创建时会自动扫描出`prefixPath`子树下所有的测点（包括定义为所有普通序列的测点，以及挂载路径与 `prefixPath `有所重合的所有模板中的测点），列名使用树模型测点名称。 + * 不支持树模型存在名称（含小写）相同但类型不同的测点 + +4. **`WITH properties`** + +目前仅支持 TTL，表示该视图 TTL ms 之前的数据不会在查询时展示，即`WHERE time > now() - TTL`。若树模型设置了 TTL，则查询时取两者中的更小值。 + +> 注意：表视图 TTL 不影响树模型中设备的真实 TTL，当设备数据达到树模型设定的 TTL 后，将被系统物理删除。 + +5. **`OR REPLACE`** + +table 与 view 不能重名。创建时若已存在同名 table ，则会报错；若已存在同名 view ，则进行替换。 + +6. **`RESTRICT`** + +约束匹配树模型设备的层级数（从 prefixPath 下一层开始），若有 RESTRICT 字段，则匹配层级完全等于 tag 数量的 device，否则匹配层级小于等于 tag 数量的 device。默认非 RESTRICT，即匹配层级小于等于 tag 数量的 device。 + +#### 2.1.3 使用示例 +1. 树模型及表视图原型 + +![](/img/tree-to-table-2.png) + +2. 创建表视图 + +* 创建语句 + +```SQL +CREATE OR REPLACE VIEW viewdb."风机表" + ("风机组" TAG, + "风机号" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD + ) +with (ttl=604800000) +AS root.db.** +``` + +* 具体说明 + +该语句表示，创建出名为 `viewdb."风机表"` 的视图（viewdb 如不存在会报错），如果该视图已存在，则替换该视图： + +* 为挂载于树模型 root.db.\*\* 路径下面的序列创建表视图。 +* 具备`风机组`、`风机号`两个 `TAG` 列，因此表视图中只包含原树模型中第 3 层上的设备。 +* 具备`电压`、`电流`两个 `FIELD` 列。这里两个 `FIELD` 列对应树模型下的序列名同样是`电压`、`电流`，且仅仅选取类型为 `DOUBLE` 的序列。 + + **​序列名的改名需求：​**如果树模型下的序列名为`current`，想要创建出的表视图中对应的 `FIELD` 列名为`电流`，这种情况下，SQL 变更如下： + + ```SQL + CREATE OR REPLACE VIEW viewdb."风机表" + ("风机组" TAG, + "风机号" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD FROM current + ) + AS root.db.** + with (ttl=604800000) + ``` + +### 2.2 修改表视图 +#### 2.2.1 语法定义 + +修改表视图功能支持修改视图名称、添加列、列重命名、删除列、设置视图的 TTL 属性，以及通过 COMMENT 添加注释。 + +```SQL +-- 修改视图名 +ALTER VIEW [IF EXISTS] viewName RENAME TO to=identifier + +-- 在视图中添加某一列 +ALTER VIEW [IF EXISTS] viewName ADD COLUMN [IF NOT EXISTS] viewColumnDefinition +viewColumnDefinition + : column_name [dataType] TAG # tagColumn + | column_name [dataType] FIELD [FROM original_measurement] # fieldColumn + +-- 为视图中的某一列重命名 +ALTER VIEW [IF EXISTS] viewName RENAME COLUMN [IF EXISTS] oldName TO newName + +-- 删除视图中的某一列 +ALTER VIEW [IF EXISTS] viewName DROP COLUMN [IF EXISTS] columnName + +-- 修改视图的 TTL +ALTER VIEW [IF EXISTS] viewName SET PROPERTIES propertyAssignments + +-- 添加注释 +COMMENT ON VIEW qualifiedName IS (string | NULL) #commentView +COMMENT ON COLUMN qualifiedName '.' column=identifier IS (string | NULL) #commentColumn +``` + +#### 2.2.2 语法说明 +1. `SET PROPERTIES`操作目前仅支持对表视图的 TTL 属性进行配置。 +2. 删除列功能，仅支持删除物理量列(FIELD)，标识列(TAG)不支持删除。 +3. 修改后的 comment 会覆盖原有注释，如果指定为 null，则会擦除之前的 comment。 +#### 2.2.3 使用示例 + +```SQL +-- 修改视图名 +ALTER VIEW IF EXISTS tableview1 RENAME TO tableview + +-- 在视图中添加某一列 +ALTER VIEW IF EXISTS tableview ADD COLUMN IF NOT EXISTS temperature float field + +-- 为视图中的某一列重命名 +ALTER VIEW IF EXISTS tableview RENAME COLUMN IF EXISTS temperature TO temp + +-- 删除视图中的某一列 +ALTER VIEW IF EXISTS tableview DROP COLUMN IF EXISTS temp + +-- 修改视图的 TTL +ALTER VIEW IF EXISTS tableview SET PROPERTIES TTL=3600 + +-- 添加注释 +COMMENT ON VIEW tableview IS '树转表' +COMMENT ON COLUMN tableview.status is Null +``` + +### 2.3 删除表视图 +#### 2.3.1 语法定义 + +```SQL +DROP VIEW [IF EXISTS] viewName +``` + +#### 2.3.2 使用示例 + +```SQL +DROP VIEW IF EXISTS tableview +``` + +### 2.4 查看表视图 +#### 2.4.1 **`Show Tables`** +1. 语法定义 + +```SQL +SHOW TABLES (DETAILS)? ((FROM | IN) database_name)? +``` + +2. 语法说明 + +`SHOW TABLES (DETAILS)` 语句通过结果集的`TABLE_TYPE`字段展示表或视图的类型信息： + +| 类型 | `TABLE_TYPE`字段值 | +| -------------------------------------- | ------------------------ | +| 普通表（Table) | `BASE TABLE` | +| 树转表视图（Tree View) | `VIEW FROM TREE` | +| 系统表（Iinformation\_schema.Tables) | `SYSTEM VIEW` | + +3. 使用示例 + +```SQL +IoTDB> show tables details from database1 ++-----------+-----------+------+-------+--------------+ +| TableName| TTL(ms)|Status|Comment| TableType| ++-----------+-----------+------+-------+--------------+ +| tableview| INF| USING| 树转表 |VIEW FROM TREE| +| table1|31536000000| USING| null| BASE TABLE| +| table2|31536000000| USING| null| BASE TABLE| ++-----------+-----------+------+-------+--------------+ + +IoTDB> show tables details from information_schema ++--------------+-------+------+-------+-----------+ +| TableName|TTL(ms)|Status|Comment| TableType| ++--------------+-------+------+-------+-----------+ +| columns| INF| USING| null|SYSTEM VIEW| +| config_nodes| INF| USING| null|SYSTEM VIEW| +|configurations| INF| USING| null|SYSTEM VIEW| +| data_nodes| INF| USING| null|SYSTEM VIEW| +| databases| INF| USING| null|SYSTEM VIEW| +| functions| INF| USING| null|SYSTEM VIEW| +| keywords| INF| USING| null|SYSTEM VIEW| +| models| INF| USING| null|SYSTEM VIEW| +| nodes| INF| USING| null|SYSTEM VIEW| +| pipe_plugins| INF| USING| null|SYSTEM VIEW| +| pipes| INF| USING| null|SYSTEM VIEW| +| queries| INF| USING| null|SYSTEM VIEW| +| regions| INF| USING| null|SYSTEM VIEW| +| subscriptions| INF| USING| null|SYSTEM VIEW| +| tables| INF| USING| null|SYSTEM VIEW| +| topics| INF| USING| null|SYSTEM VIEW| +| views| INF| USING| null|SYSTEM VIEW| ++--------------+-------+------+-------+-----------+ +``` + +#### 2.4.2 **`Show Create Table/View`** +1. 语法定义 + +```SQL +SHOW CREATE TABLE|VIEW viewname; +``` + +2. 语法说明 + +* SHOW CREATE TABLE 语句可用于展示普通表或者视图的完整创建信息； +* SHOW CREATE VIEW 语句仅可用于展示视图的完整创建信息； +* 两种语句均不支持用于展示系统表； + +3. 使用示例 + +```SQL +IoTDB> show create table tableview ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| View| Create View| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|tableview|CREATE VIEW "tableview" ("device" STRING TAG,"model" STRING TAG,"status" BOOLEAN FIELD,"hardware" STRING FIELD) COMMENT '树转表' WITH (ttl=INF) AS root.ln.**| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +IoTDB> show create view tableview ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| View| Create View| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|tableview|CREATE VIEW "tableview" ("device" STRING TAG,"model" STRING TAG,"status" BOOLEAN FIELD,"hardware" STRING FIELD) COMMENT '表视图' WITH (ttl=INF) AS root.ln.**| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``` + +### 2.5 非对齐与对齐设备的查询差异 + +树转表视图在查询对齐设备和非对齐设备中有 null 值的情况下结果​**可能与等价的树模型 align by device 查询不同**​。 + +* **对齐设备** + * 树模型的查询表现：当查询涉及的所有序列在某一行都是null时，不保留该行 + * 表视图的查询表现：与表模型一致，保留全是 null 的行 +* **非对齐设备** + * 树模型的查询表现：当查询涉及的所有序列在某一行都是null时，不保留该行 + * 表视图的查询表现：与树模型一致，不保留全是 null 的行 +* **说明示例** + * 对齐 + + ```SQL + -- 树模型写入数据（对齐） + CREATE ALIGNED TIMESERIES root.db.battery.b1(voltage INT32, current FLOAT) + INSERT INTO root.db.battery.b1(time, voltage, current) aligned values (1, 1, 1) + INSERT INTO root.db.battery.b1(time, voltage, current) aligned values (2, null, 1) + + -- 创建 VIEW 语句 + CREATE VIEW view1 (battery_id TAG, voltage INT32 FIELD, current FLOAT FIELD) as root.db.battery.** + + -- 查询 + IoTDB> select voltage from view1 + +-------+ + |voltage| + +-------+ + | 1| + | null| + +-------+ + Total line number = 2 + ``` + + * 非对齐 + + ```SQL + -- 树模型写入数据（非对齐） + CREATE TIMESERIES root.db.battery.b1.voltage INT32 + CREATE TIMESERIES root.db.battery.b1.current FLOAT + INSERT INTO root.db.battery.b1(time, voltage, current) values (1, 1, 1) + INSERT INTO root.db.battery.b1(time, voltage, current) values (2, null, 1) + + -- 创建 VIEW 语句 + CREATE VIEW view1 (battery_id TAG, voltage INT32 FIELD, current FLOAT FIELD) as root.db.battery.** + + -- 查询 + IoTDB> select voltage from view1 + +-------+ + |voltage| + +-------+ + | 1| + +-------+ + Total line number = 1 + + -- 如果在查询语句中指定了所有 field 列，或是仅指定了非 field 列时，才可以确保查到所有行 + IoTDB> select voltage,current from view1 + +-------+-------+ + |voltage|current| + +-------+-------+ + | 1| 1.0| + | null| 1.0| + +-------+-------+ + Total line number = 2 + + IoTDB> select battery_id from view1 + +-------+ + |battery_id| + +-------+ + | b1| + | b1| + +-------+ + Total line number = 2 + + -- 如果查询中同时有部分 field 列，那最终结果的行数取决于这部分 field 列根据时间戳对齐后的行数 + IoTDB> select time,voltage from view1 + +-----------------------------+-------+ + | time|voltage| + +-----------------------------+-------+ + |1970-01-01T08:00:00.001+08:00| 1| + +-----------------------------+-------+ + Total line number = 1 + ``` + +## 3. 场景示例 +### 3.1 原树模型管理了多种类型的设备 + +* 场景中不同类型的设备具备不同的层级路径和测点集合。 +* ​**写入时**​：在数据库节点下按设备类型创建分支，每种设备下可以有不同的测点结构 +* ​**查询时**​：为每种类型的设备建立一张表，每个表具有不同的标签和测点集合 + +![](/img/tree-to-table-3.png) + +**表视图的创建 SQL：** + +```SQL +-- 风机表 +CREATE VIEW viewdb."风机表" + ("风机组" TAG, + "风机号" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD + ) +AS root.db."风机".** + +-- 电机表 +CREATE VIEW viewdb."电机表" + ("电机组" TAG, + "电机号" TAG, + "功率" FLOAT FIELD, + "电量" FLOAT FIELD, + "温度" FLOAT FIELD + ) +AS root.db."电机".** +``` + +### 3.2 原树模型中没有设备，只有测点 + +如场站的监控系统中，每个测点都有唯一编号，但无法对应到某些设备 + +> 大宽表形式 + +![](/img/tree-to-table-4.png) + +**表视图的创建 SQL：** + +```SQL +CREATE VIEW viewdb.machine + (DCS_PIT_02105A DOUBLE FIELD, + DCS_PIT_02105B DOUBLE FIELD, + DCS_PIT_02105C DOUBLE FIELD, + ... + DCS_XI_02716A DOUBLE FIELD + ) +AS root.db.** +``` + +### 3.3 原树模型中一个设备既有子设备，也有测点 + +如在储能场景中，每一层结构都要监控其电压和电流 + +* ​**写入时**​：按照物理世界的监测点，对每一层结构进行建模 +* ​**查询时**​：按照设备分类，建立多个表对每一层结构信息进行管理 + +![](/img/tree-to-table-5.png) + +**表视图的创建 SQL：** + +```SQL +-- 电池舱表 +CREATE VIEW viewdb."电池舱表" + ("电池站" TAG, + "电池舱" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD + ) +RESTRICT +AS root.db.** + +-- 电池堆表 +CREATE VIEW viewdb."电池堆表" + ("电池站" TAG, + "电池舱" TAG, + "电池堆" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD + ) +RESTRICT +AS root.db.** + +-- 电池簇表 +CREATE VIEW viewdb."电池簇表" + ("电池站" TAG, + "电池舱" TAG, + "电池堆" TAG, + "电池簇" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD + ) +RESTRICT +AS 'root.db.**' + +-- 电芯表 +CREATE VIEW viewdb."电芯表" + ("电池站" TAG, + "电池舱" TAG, + "电池堆" TAG, + "电池簇" TAG, + "电芯" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD + ) +RESTRICT +AS root.db.** +``` + +### 3.4 原树模型中一个设备下只有一个测点 + +> 窄表形式 + +#### 3.4.1 所有测点数据类型相同 + +![](/img/tree-to-table-6.png) + +**表视图的创建 SQL：** + +```SQL +CREATE VIEW viewdb.machine + ( + sensor_id STRING TAG, + value DOUBLE FIELD + ) +AS root.db.** +``` + +#### 3.4.2 测点的数据类型不相同 +##### 3.4.2.1 为每一种数据类型的测点建一个窄表视图 + +​**优点**​：表视图数量是常数个，仅与系统中的数据类型相关 + +​**缺点**​：查询某一个测点值时，需要提前知道其数据类型，再去决定查询哪张表视图 + +![](/img/tree-to-table-7.png) + +**表视图的创建 SQL：** + +```SQL +CREATE VIEW viewdb.machine_float + ( + sensor_id STRING TAG, + value FLOAT FIELD + ) +AS root.db.** + +CREATE VIEW viewdb.machine_double + ( + sensor_id STRING TAG, + value DOUBLE FIELD + ) +AS root.db.** + +CREATE VIEW viewdb.machine_int32 + ( + sensor_id STRING TAG, + value INT32 FIELD + ) +AS root.db.** + +CREATE VIEW viewdb.machine_int64 + ( + sensor_id STRING TAG, + value INT64 FIELD + ) +AS root.db.** + +... +``` + +##### 3.4.2.2 为每一个测点建一个表 + +​**优点**​：查询某一个测点值时，不需要先查一下数据类型，再去决定查询哪张表，简单便捷 + +​**缺点**​：当测点数量较多时，会引入过多的表视图，需要写大量的建视图语句 + +![](/img/tree-to-table-8.png) + +**表视图的创建 SQL：** + +```SQL +CREATE VIEW viewdb.DCS_PIT_02105A + ( + value FLOAT FIELD + ) +AS root.db.DCS_PIT_02105A.** + +CREATE VIEW viewdb.DCS_PIT_02105B + ( + value DOUBLE FIELD + ) +AS root.db.DCS_PIT_02105B.** + +CREATE VIEW viewdb.DCS_XI_02716A + ( + value INT64 FIELD + ) +AS root.db.DCS_XI_02716A.** + +...... +``` diff --git a/src/zh/UserGuide/latest-Table/User-Manual/Tree-to-Table.md b/src/zh/UserGuide/latest-Table/User-Manual/Tree-to-Table.md new file mode 100644 index 000000000..fc6a446c5 --- /dev/null +++ b/src/zh/UserGuide/latest-Table/User-Manual/Tree-to-Table.md @@ -0,0 +1,579 @@ + +# 树转表视图 + +## 1. 功能概述 + +IoTDB 提供了树转表功能，支持通过创建表视图的方式，将已存在的树模型数据转化为表视图，进而通过表视图进行查询，实现了对同一份数据的树模型和表模型协同处理： + +* 数据写入阶段，采用树模型语法，支持数据灵活接入和扩展。 +* 数据分析阶段，采用表模型语法，支持通过标准 SQL 查询语言，执行复杂的数据分析。 + +![](/img/tree-to-table-1.png) + +> - V2.0.5 及以后版本支持该功能。 +> - 表视图只读，不允许通过表视图写入数据。 + +## 2. 功能介绍 +### 2.1 创建表视图 +#### 2.1.1 语法定义 + +```SQL +-- create (or replace) view on tree +CREATE + [OR REPLACE] + VIEW view_name ([viewColumnDefinition (',' viewColumnDefinition)*]) + [comment] + [RESTRICT] + [WITH properties] + AS prefixPath + +viewColumnDefinition + : column_name [dataType] TAG [comment] # tagColumn + | column_name [dataType] TIME [comment] # timeColumn + | column_name [dataType] FIELD [FROM original_measurement] [comment] # fieldColumn + ; + +comment + : COMMENT string + ; +``` + +> 注意：列仅支持 tag / field / time，不支持 attribute。 + +#### 2.1.2 语法说明 +1. **`prefixPath`** + +对应树模型的路径，路径最后一级必须为 `**`，且其他层级均不能出现 `*` 或 `**`。该路径确定 VIEW 对应的子树。 + +2. **`view_name`** + +视图名称，与表名相同（具体约束可参考[创建表](../Basic-Concept/Table-Management.md#\_1-1-创建表)），如 db.view。 + +3. **`viewColumnDefinition`** + +* `TAG`：每个 Tag 列按顺序对应`prefixPath`后面层级的路径节点。 +* `FIELD`：FIELD 列对应树模型中的测点（叶子节点）。 + * 若指定了 FIELD 列，则列名使用声明中的`column_name`。 + * 若声明了 `original_measurement`，则直接映射到树模型该测点。否则取小写`column_name` 作为测点名进行树模型映射。 + * 不支持多个 FIELD 映射到树模型同名测点。 + * 若未指定 FIELD 列的 `dataType`，则默认获取树模型映射测点的数据类型。 + * 若树模型中的设备不包含某些声明的 FIELD 列，或与声明的 FIELD 列的数据类型不一致，则在查询该设备时，该 FIELD 列的值永远为 NULL。 + * 若未指定 FIELD 列，则创建时会自动扫描出`prefixPath`子树下所有的测点（包括定义为所有普通序列的测点，以及挂载路径与 `prefixPath `有所重合的所有模板中的测点），列名使用树模型测点名称。 + * 不支持树模型存在名称（含小写）相同但类型不同的测点 + +4. **`WITH properties`** + +目前仅支持 TTL，表示该视图 TTL ms 之前的数据不会在查询时展示，即`WHERE time > now() - TTL`。若树模型设置了 TTL，则查询时取两者中的更小值。 + +> 注意：表视图 TTL 不影响树模型中设备的真实 TTL，当设备数据达到树模型设定的 TTL 后，将被系统物理删除。 + +5. **`OR REPLACE`** + +table 与 view 不能重名。创建时若已存在同名 table ，则会报错；若已存在同名 view ，则进行替换。 + +6. **`RESTRICT`** + +约束匹配树模型设备的层级数（从 prefixPath 下一层开始），若有 RESTRICT 字段，则匹配层级完全等于 tag 数量的 device，否则匹配层级小于等于 tag 数量的 device。默认非 RESTRICT，即匹配层级小于等于 tag 数量的 device。 + +#### 2.1.3 使用示例 +1. 树模型及表视图原型 + +![](/img/tree-to-table-2.png) + +2. 创建表视图 + +* 创建语句 + +```SQL +CREATE OR REPLACE VIEW viewdb."风机表" + ("风机组" TAG, + "风机号" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD + ) +with (ttl=604800000) +AS root.db.** +``` + +* 具体说明 + +该语句表示，创建出名为 `viewdb."风机表"` 的视图（viewdb 如不存在会报错），如果该视图已存在，则替换该视图： + +* 为挂载于树模型 root.db.\*\* 路径下面的序列创建表视图。 +* 具备`风机组`、`风机号`两个 `TAG` 列，因此表视图中只包含原树模型中第 3 层上的设备。 +* 具备`电压`、`电流`两个 `FIELD` 列。这里两个 `FIELD` 列对应树模型下的序列名同样是`电压`、`电流`，且仅仅选取类型为 `DOUBLE` 的序列。 + + **​序列名的改名需求：​**如果树模型下的序列名为`current`，想要创建出的表视图中对应的 `FIELD` 列名为`电流`，这种情况下，SQL 变更如下： + + ```SQL + CREATE OR REPLACE VIEW viewdb."风机表" + ("风机组" TAG, + "风机号" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD FROM current + ) + AS root.db.** + with (ttl=604800000) + ``` + +### 2.2 修改表视图 +#### 2.2.1 语法定义 + +修改表视图功能支持修改视图名称、添加列、列重命名、删除列、设置视图的 TTL 属性，以及通过 COMMENT 添加注释。 + +```SQL +-- 修改视图名 +ALTER VIEW [IF EXISTS] viewName RENAME TO to=identifier + +-- 在视图中添加某一列 +ALTER VIEW [IF EXISTS] viewName ADD COLUMN [IF NOT EXISTS] viewColumnDefinition +viewColumnDefinition + : column_name [dataType] TAG # tagColumn + | column_name [dataType] FIELD [FROM original_measurement] # fieldColumn + +-- 为视图中的某一列重命名 +ALTER VIEW [IF EXISTS] viewName RENAME COLUMN [IF EXISTS] oldName TO newName + +-- 删除视图中的某一列 +ALTER VIEW [IF EXISTS] viewName DROP COLUMN [IF EXISTS] columnName + +-- 修改视图的 TTL +ALTER VIEW [IF EXISTS] viewName SET PROPERTIES propertyAssignments + +-- 添加注释 +COMMENT ON VIEW qualifiedName IS (string | NULL) #commentView +COMMENT ON COLUMN qualifiedName '.' column=identifier IS (string | NULL) #commentColumn +``` + +#### 2.2.2 语法说明 +1. `SET PROPERTIES`操作目前仅支持对表视图的 TTL 属性进行配置。 +2. 删除列功能，仅支持删除物理量列(FIELD)，标识列(TAG)不支持删除。 +3. 修改后的 comment 会覆盖原有注释，如果指定为 null，则会擦除之前的 comment。 +#### 2.2.3 使用示例 + +```SQL +-- 修改视图名 +ALTER VIEW IF EXISTS tableview1 RENAME TO tableview + +-- 在视图中添加某一列 +ALTER VIEW IF EXISTS tableview ADD COLUMN IF NOT EXISTS temperature float field + +-- 为视图中的某一列重命名 +ALTER VIEW IF EXISTS tableview RENAME COLUMN IF EXISTS temperature TO temp + +-- 删除视图中的某一列 +ALTER VIEW IF EXISTS tableview DROP COLUMN IF EXISTS temp + +-- 修改视图的 TTL +ALTER VIEW IF EXISTS tableview SET PROPERTIES TTL=3600 + +-- 添加注释 +COMMENT ON VIEW tableview IS '树转表' +COMMENT ON COLUMN tableview.status is Null +``` + +### 2.3 删除表视图 +#### 2.3.1 语法定义 + +```SQL +DROP VIEW [IF EXISTS] viewName +``` + +#### 2.3.2 使用示例 + +```SQL +DROP VIEW IF EXISTS tableview +``` + +### 2.4 查看表视图 +#### 2.4.1 **`Show Tables`** +1. 语法定义 + +```SQL +SHOW TABLES (DETAILS)? ((FROM | IN) database_name)? +``` + +2. 语法说明 + +`SHOW TABLES (DETAILS)` 语句通过结果集的`TABLE_TYPE`字段展示表或视图的类型信息： + +| 类型 | `TABLE_TYPE`字段值 | +| -------------------------------------- | ------------------------ | +| 普通表（Table) | `BASE TABLE` | +| 树转表视图（Tree View) | `VIEW FROM TREE` | +| 系统表（Iinformation\_schema.Tables) | `SYSTEM VIEW` | + +3. 使用示例 + +```SQL +IoTDB> show tables details from database1 ++-----------+-----------+------+-------+--------------+ +| TableName| TTL(ms)|Status|Comment| TableType| ++-----------+-----------+------+-------+--------------+ +| tableview| INF| USING| 树转表 |VIEW FROM TREE| +| table1|31536000000| USING| null| BASE TABLE| +| table2|31536000000| USING| null| BASE TABLE| ++-----------+-----------+------+-------+--------------+ + +IoTDB> show tables details from information_schema ++--------------+-------+------+-------+-----------+ +| TableName|TTL(ms)|Status|Comment| TableType| ++--------------+-------+------+-------+-----------+ +| columns| INF| USING| null|SYSTEM VIEW| +| config_nodes| INF| USING| null|SYSTEM VIEW| +|configurations| INF| USING| null|SYSTEM VIEW| +| data_nodes| INF| USING| null|SYSTEM VIEW| +| databases| INF| USING| null|SYSTEM VIEW| +| functions| INF| USING| null|SYSTEM VIEW| +| keywords| INF| USING| null|SYSTEM VIEW| +| models| INF| USING| null|SYSTEM VIEW| +| nodes| INF| USING| null|SYSTEM VIEW| +| pipe_plugins| INF| USING| null|SYSTEM VIEW| +| pipes| INF| USING| null|SYSTEM VIEW| +| queries| INF| USING| null|SYSTEM VIEW| +| regions| INF| USING| null|SYSTEM VIEW| +| subscriptions| INF| USING| null|SYSTEM VIEW| +| tables| INF| USING| null|SYSTEM VIEW| +| topics| INF| USING| null|SYSTEM VIEW| +| views| INF| USING| null|SYSTEM VIEW| ++--------------+-------+------+-------+-----------+ +``` + +#### 2.4.2 **`Show Create Table/View`** +1. 语法定义 + +```SQL +SHOW CREATE TABLE|VIEW viewname; +``` + +2. 语法说明 + +* SHOW CREATE TABLE 语句可用于展示普通表或者视图的完整创建信息； +* SHOW CREATE VIEW 语句仅可用于展示视图的完整创建信息； +* 两种语句均不支持用于展示系统表； + +3. 使用示例 + +```SQL +IoTDB> show create table tableview ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| View| Create View| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|tableview|CREATE VIEW "tableview" ("device" STRING TAG,"model" STRING TAG,"status" BOOLEAN FIELD,"hardware" STRING FIELD) COMMENT '树转表' WITH (ttl=INF) AS root.ln.**| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +IoTDB> show create view tableview ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| View| Create View| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|tableview|CREATE VIEW "tableview" ("device" STRING TAG,"model" STRING TAG,"status" BOOLEAN FIELD,"hardware" STRING FIELD) COMMENT '表视图' WITH (ttl=INF) AS root.ln.**| ++---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +``` + +### 2.5 非对齐与对齐设备的查询差异 + +树转表视图在查询对齐设备和非对齐设备中有 null 值的情况下结果​**可能与等价的树模型 align by device 查询不同**​。 + +* **对齐设备** + * 树模型的查询表现：当查询涉及的所有序列在某一行都是null时，不保留该行 + * 表视图的查询表现：与表模型一致，保留全是 null 的行 +* **非对齐设备** + * 树模型的查询表现：当查询涉及的所有序列在某一行都是null时，不保留该行 + * 表视图的查询表现：与树模型一致，不保留全是 null 的行 +* **说明示例** + * 对齐 + + ```SQL + -- 树模型写入数据（对齐） + CREATE ALIGNED TIMESERIES root.db.battery.b1(voltage INT32, current FLOAT) + INSERT INTO root.db.battery.b1(time, voltage, current) aligned values (1, 1, 1) + INSERT INTO root.db.battery.b1(time, voltage, current) aligned values (2, null, 1) + + -- 创建 VIEW 语句 + CREATE VIEW view1 (battery_id TAG, voltage INT32 FIELD, current FLOAT FIELD) as root.db.battery.** + + -- 查询 + IoTDB> select voltage from view1 + +-------+ + |voltage| + +-------+ + | 1| + | null| + +-------+ + Total line number = 2 + ``` + + * 非对齐 + + ```SQL + -- 树模型写入数据（非对齐） + CREATE TIMESERIES root.db.battery.b1.voltage INT32 + CREATE TIMESERIES root.db.battery.b1.current FLOAT + INSERT INTO root.db.battery.b1(time, voltage, current) values (1, 1, 1) + INSERT INTO root.db.battery.b1(time, voltage, current) values (2, null, 1) + + -- 创建 VIEW 语句 + CREATE VIEW view1 (battery_id TAG, voltage INT32 FIELD, current FLOAT FIELD) as root.db.battery.** + + -- 查询 + IoTDB> select voltage from view1 + +-------+ + |voltage| + +-------+ + | 1| + +-------+ + Total line number = 1 + + -- 如果在查询语句中指定了所有 field 列，或是仅指定了非 field 列时，才可以确保查到所有行 + IoTDB> select voltage,current from view1 + +-------+-------+ + |voltage|current| + +-------+-------+ + | 1| 1.0| + | null| 1.0| + +-------+-------+ + Total line number = 2 + + IoTDB> select battery_id from view1 + +-------+ + |battery_id| + +-------+ + | b1| + | b1| + +-------+ + Total line number = 2 + + -- 如果查询中同时有部分 field 列，那最终结果的行数取决于这部分 field 列根据时间戳对齐后的行数 + IoTDB> select time,voltage from view1 + +-----------------------------+-------+ + | time|voltage| + +-----------------------------+-------+ + |1970-01-01T08:00:00.001+08:00| 1| + +-----------------------------+-------+ + Total line number = 1 + ``` + +## 3. 场景示例 +### 3.1 原树模型管理了多种类型的设备 + +* 场景中不同类型的设备具备不同的层级路径和测点集合。 +* ​**写入时**​：在数据库节点下按设备类型创建分支，每种设备下可以有不同的测点结构 +* ​**查询时**​：为每种类型的设备建立一张表，每个表具有不同的标签和测点集合 + +![](/img/tree-to-table-3.png) + +**表视图的创建 SQL：** + +```SQL +-- 风机表 +CREATE VIEW viewdb."风机表" + ("风机组" TAG, + "风机号" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD + ) +AS root.db."风机".** + +-- 电机表 +CREATE VIEW viewdb."电机表" + ("电机组" TAG, + "电机号" TAG, + "功率" FLOAT FIELD, + "电量" FLOAT FIELD, + "温度" FLOAT FIELD + ) +AS root.db."电机".** +``` + +### 3.2 原树模型中没有设备，只有测点 + +如场站的监控系统中，每个测点都有唯一编号，但无法对应到某些设备 + +> 大宽表形式 + +![](/img/tree-to-table-4.png) + +**表视图的创建 SQL：** + +```SQL +CREATE VIEW viewdb.machine + (DCS_PIT_02105A DOUBLE FIELD, + DCS_PIT_02105B DOUBLE FIELD, + DCS_PIT_02105C DOUBLE FIELD, + ... + DCS_XI_02716A DOUBLE FIELD + ) +AS root.db.** +``` + +### 3.3 原树模型中一个设备既有子设备，也有测点 + +如在储能场景中，每一层结构都要监控其电压和电流 + +* ​**写入时**​：按照物理世界的监测点，对每一层结构进行建模 +* ​**查询时**​：按照设备分类，建立多个表对每一层结构信息进行管理 + +![](/img/tree-to-table-5.png) + +**表视图的创建 SQL：** + +```SQL +-- 电池舱表 +CREATE VIEW viewdb."电池舱表" + ("电池站" TAG, + "电池舱" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD + ) +RESTRICT +AS root.db.** + +-- 电池堆表 +CREATE VIEW viewdb."电池堆表" + ("电池站" TAG, + "电池舱" TAG, + "电池堆" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD + ) +RESTRICT +AS root.db.** + +-- 电池簇表 +CREATE VIEW viewdb."电池簇表" + ("电池站" TAG, + "电池舱" TAG, + "电池堆" TAG, + "电池簇" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD + ) +RESTRICT +AS 'root.db.**' + +-- 电芯表 +CREATE VIEW viewdb."电芯表" + ("电池站" TAG, + "电池舱" TAG, + "电池堆" TAG, + "电池簇" TAG, + "电芯" TAG, + "电压" DOUBLE FIELD, + "电流" DOUBLE FIELD + ) +RESTRICT +AS root.db.** +``` + +### 3.4 原树模型中一个设备下只有一个测点 + +> 窄表形式 + +#### 3.4.1 所有测点数据类型相同 + +![](/img/tree-to-table-6.png) + +**表视图的创建 SQL：** + +```SQL +CREATE VIEW viewdb.machine + ( + sensor_id STRING TAG, + value DOUBLE FIELD + ) +AS root.db.** +``` + +#### 3.4.2 测点的数据类型不相同 +##### 3.4.2.1 为每一种数据类型的测点建一个窄表视图 + +​**优点**​：表视图数量是常数个，仅与系统中的数据类型相关 + +​**缺点**​：查询某一个测点值时，需要提前知道其数据类型，再去决定查询哪张表视图 + +![](/img/tree-to-table-7.png) + +**表视图的创建 SQL：** + +```SQL +CREATE VIEW viewdb.machine_float + ( + sensor_id STRING TAG, + value FLOAT FIELD + ) +AS root.db.** + +CREATE VIEW viewdb.machine_double + ( + sensor_id STRING TAG, + value DOUBLE FIELD + ) +AS root.db.** + +CREATE VIEW viewdb.machine_int32 + ( + sensor_id STRING TAG, + value INT32 FIELD + ) +AS root.db.** + +CREATE VIEW viewdb.machine_int64 + ( + sensor_id STRING TAG, + value INT64 FIELD + ) +AS root.db.** + +... +``` + +##### 3.4.2.2 为每一个测点建一个表 + +​**优点**​：查询某一个测点值时，不需要先查一下数据类型，再去决定查询哪张表，简单便捷 + +​**缺点**​：当测点数量较多时，会引入过多的表视图，需要写大量的建视图语句 + +![](/img/tree-to-table-8.png) + +**表视图的创建 SQL：** + +```SQL +CREATE VIEW viewdb.DCS_PIT_02105A + ( + value FLOAT FIELD + ) +AS root.db.DCS_PIT_02105A.** + +CREATE VIEW viewdb.DCS_PIT_02105B + ( + value DOUBLE FIELD + ) +AS root.db.DCS_PIT_02105B.** + +CREATE VIEW viewdb.DCS_XI_02716A + ( + value INT64 FIELD + ) +AS root.db.DCS_XI_02716A.** + +...... +```