小 T 導讀：為應對不同場景下的寫入需求，[TDengine]( https://www.taosdata.com/"TDengine") 共提供了四種寫入協議，其中最常用的當屬 SQL 寫入了，為了讓大家在實際寫入操作時更加方便，我們整理了一篇詳細解讀 SQL INSERT 語法規則的文章。建議提前收藏，有需要時可隨時參考。

在諸多[時序資料庫]( https://www.taosdata.com/"時序資料庫")（Time Series Database）中，如果能支援 SQL，則可以大大降低使用者的學習和接入成本，而 TDengine 正是這樣一款產品。

TDengine SQL 是供給使用者進行資料寫入和查詢的主要工具。為了便於使用者快速上手，它在一定程度上與標準 SQL 風格和模式類似。由於 TDengine 的早期版本沒有提供時序資料的刪除功能，因此其 SQL 語法也沒有提供資料刪除的相關功能。不過從 TDengine 企業版從 2.6 開始提供了 DELETE 語句。

為更好地說明 SQL 語法的規則及其特點，本文假設存在一個資料集。以智慧電錶（meters）為例，假設每個智慧電錶採集電流、電壓和相位三個量。其建模如下：
```java
taos> DESCRIBE meters;
             Field              |        Type        |   Length    |    Note    |
=================================================================================
 ts                             | TIMESTAMP          |           8 |            |
 current                        | FLOAT              |           4 |            |
 voltage                        | INT                |           4 |            |
 phase                          | FLOAT              |           4 |            |
 location                       | BINARY             |          64 | TAG        |
 groupid                        | INT                |           4 | TAG        |
```
建立超級表和字表的語句可參考 TDengine 官網的[官方文件]( https://docs.taosdata.com/develop/model/#%E8%87%AA%E5%8A%A8%E5%BB%BA%E8%A1%A8"官方文件")。

以上資料集包含 4 個智慧電錶的資料，按照 TDengine 的建模規則，對應 4 個子表，其名稱分別是 d1001、d1002、d1003 以及 d1004。下面我們將以此模型為例，詳解 TDengine 中的 SQL INSERT 語法規則。寫入語法如下：
```java
INSERT INTO
    tb_name
        [USING stb_name [(tag1_name, ...)] TAGS (tag1_value, ...)]
        [(field1_name, ...)]
        VALUES (field1_value, ...) [(field1_value2, ...) ...] | FILE csv_file_path
    [tb2_name
        [USING stb_name [(tag1_name, ...)] TAGS (tag1_value, ...)]
        [(field1_name, ...)]
        VALUES (field1_value, ...) [(field1_value2, ...) ...] | FILE csv_file_path
    ...];
```

**插入一條或多條記錄**
首先我們需要先指定一個已經建立好的資料子表的表名，並透過 VALUES 關鍵字提供一行或多行資料，即可向資料庫寫入這些資料。例如，執行如下語句可以寫入一行記錄：
```java
INSERT INTO d1001 VALUES (NOW, 10.2, 219, 0.32);
```
或者，可以透過如下語句寫入兩行記錄：
```java
INSERT INTO d1001 VALUES ('2021-07-13 14:06:32.272', 10.2, 219, 0.32) (1626164208000, 10.15, 217, 0.33);
```
在此過程中，需要注意以下三點：

1. 在第二個程式碼示例中，兩行記錄的首列時間戳使用了不同格式的寫法。其中字串格式的時間戳寫法不受所在 Database 的時間精度設定影響；而長整形格式的時間戳寫法會受到所在 Database 的時間精度設定影響——例子中的時間戳在毫秒精度下可以寫作 1626164208000，而如果是在微秒精度設定下就需要寫為 1626164208000000，納秒精度設定下需要寫為 1626164208000000000。
2. 在使用“插入多條記錄”方式寫入資料時，不能把第一列的時間戳取值都設為 NOW，否則會導致語句中的多條記錄使用相同的時間戳，就可能出現相互覆蓋以致這些資料行無法全部被正確儲存的風險。其原因在於，NOW 函式在執行中會被解析為所在 SQL 語句的實際執行時間，出現在同一語句中的多個 NOW 標記也就會被替換為完全相同的時間戳取值。
3. 允許插入的最老記錄的時間戳，認定標準是用當前伺服器時間減去配置的 keep 值（資料保留的天數）；允許插入的最新記錄的時間戳，認定標準是用當前伺服器時間加上配置的 days 值（資料檔案儲存資料的時間跨度，單位為天）。keep 和 days 都是可以在建立資料庫時指定的，預設值分別是 3650 天和 10 天。

**插入記錄，資料對應到指定的列**
當我們向資料子表中插入記錄時，無論插入一行還是多行，都可以讓資料對應到指定的列。對於 SQL 語句中沒有出現的列，資料庫將自動填充為 NULL。但要注意主鍵（時間戳）不能為 NULL。例如：
```java
INSERT INTO d1001 (ts, current, phase) VALUES ('2021-07-13 14:06:33.196', 10.27, 0.31);
```
如果不指定列，即使用全列模式，那麼在 VALUES 部分提供的資料，必須為資料表的每個列都顯式地提供資料。全列模式寫入速度會遠快於指定列，因此建議儘可能採用全列寫入方式，此時空列可以填入 NULL。

**向多個表插入記錄**
可以在一條語句中，分別向多個表插入一條或多條記錄，並且也可以在插入過程中指定列。例如：
```java
INSERT INTO d1001 VALUES ('2021-07-13 14:06:34.630', 10.2, 219, 0.32) ('2021-07-13 14:06:35.779', 10.15, 217, 0.33)
            d1002 (ts, current, phase) VALUES ('2021-07-13 14:06:34.255', 10.27, 0.31）;
```

**插入記錄時自動建表**
如果你在寫資料時並不確定某個表是否存在，此時可以在寫入資料時使用自動建表語法來建立不存在的表，若該表已存在則不會建立新表。在自動建表時，我們要求必須以超級表為模板，並寫明資料表的 TAGS 取值。例如：
```java
INSERT INTO d21001 USING meters TAGS ('California.SanFrancisco', 2) VALUES ('2021-07-13 14:06:32.272', 10.2, 219, 0.32);
```
也可以在自動建表時，只是指定部分 TAGS 列的取值，未被指定的 TAGS 列將置為 NULL。例如：
```java
INSERT INTO d21001 USING meters (groupId) TAGS (2) VALUES ('2021-07-13 14:06:33.196', 10.15, 217, 0.33);
```
自動建表語法也支援在一條語句中向多個表插入記錄。例如：
```java
INSERT INTO d21001 USING meters TAGS ('California.SanFrancisco', 2) VALUES ('2021-07-13 14:06:34.630', 10.2, 219, 0.32) ('2021-07-13 14:06:35.779', 10.15, 217, 0.33)
            d21002 USING meters (groupId) TAGS (2) VALUES ('2021-07-13 14:06:34.255', 10.15, 217, 0.33)
            d21003 USING meters (groupId) TAGS (2) (ts, current, phase) VALUES ('2021-07-13 14:06:34.255', 10.27, 0.31);
```
如果應用的是 2.0.20.5 之前的版本，那在使用自動建表語法並指定列時，子表的列名必須緊跟在子表名稱後面，而不能如例子裡那樣放在 TAGS 和 VALUES 之間。從 2.0.20.5 版本開始，這兩種寫法都可以使用了，但也不能在一條 SQL 語句中混用，否則會報語法錯誤。

**插入來自檔案的資料記錄**
在進行檔案的資料記錄插入時，除了使用 VALUES 關鍵字插入一行或多行資料外，也可以把要寫入的資料放在 CSV 檔案中（英文逗號分隔、英文單引號括住每個值）供 SQL 指令讀取，其中 CSV 檔案無需表頭。例如，如果 /tmp/csvfile.csv 檔案的內容為：
```java
'2021-07-13 14:07:34.630', '10.2', '219', '0.32'
'2021-07-13 14:07:35.779', '10.15', '217', '0.33'
```
那麼透過如下指令可以把這個檔案中的資料寫入子表中：
```java
INSERT INTO d1001 FILE '/tmp/csvfile.csv';
```
如果想要執行自動建表，從 2.1.5.0 版本開始，就已經支援在插入來自 CSV 檔案的資料時，以超級表為模板來自動建立不存在的資料表。例如：
```java
INSERT INTO d21001 USING meters TAGS ('California.SanFrancisco', 2) FILE '/tmp/csvfile.csv';
```

**歷史記錄寫入**
在進行歷史資料寫入時，我們可使用 IMPORT 或者 INSERT 命令。由於 IMPORT 的語法、功能與 INSERT 完全一樣，下面我們就以 INSERT 來說明。

針對 INSERT 型別的 SQL 語句，我們採用的是流式解析策略，在發現後面的錯誤之前，前面正確的部分 SQL 仍會執行。下面的 SQL 中，INSERT 語句是無效的，但是 d1001 仍會被建立。
```java
taos> CREATE TABLE meters(ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS(location BINARY(30), groupId INT);
Query OK, 0 row(s) affected (0.008245s)
taos> SHOW STABLES;
              name              |      created_time       | columns |  tags  |   tables    |
============================================================================================
 meters                         | 2020-08-06 17:50:27.831 |       4 |      2 |           0 |
Query OK, 1 row(s) in set (0.001029s)
taos> SHOW TABLES;
Query OK, 0 row(s) in set (0.000946s)
taos> INSERT INTO d1001 USING meters TAGS('California.SanFrancisco', 2) VALUES('a');
DB error: invalid SQL: 'a' (invalid timestamp) (0.039494s)
taos> SHOW TABLES;
           table_name           |      created_time       | columns |          stable_name           |
======================================================================================================
 d1001                          | 2020-08-06 17:52:02.097 |       4 | meters                         |
Query OK, 1 row(s) in set (0.001091s)
```

**寫在最後**
眾所周知，傳統 database 是把整個 SQL 語句傳送到服務端，由服務端完成所有的處理邏輯。和傳統資料庫不同的是，TDengine 會在客戶端完成大部分處理邏輯。在語法解析階段，由於狀態機解析 SQL 效率不高， 因此針對插入，TDengine 特地設計了流式解析；此外，對於包含表 schema 資訊和表所在 dnode 的 table meta，會在客戶端進行快取，之後只需要從本地 cache 中獲取即可，為了能在服務端實現高效處理，還會在客戶端對每個 table 的資料進行排序和去重……

這些在設計上的諸多細節，也讓 TDengine 實現了高效的資料寫入。值得一提的是，為了滿足部分客戶對效能的極端要求，TDengine 還開發了 stmt 介面，進一步減輕語法解析帶來的效能問題，目前經過多個使用者的線上實踐佐證，效能至少提高了 4～5 倍，歡迎大家試用。

如果你還有關於 SQL 寫入的更多問題，可以移步至 TDengine 官網上的[技術文件]( https://docs.taosdata.com/"技術文件")中檢視更多程式碼細節，也歡迎進入官方社群，尋求社群技術人員的幫助。

------------

想了解更多 TDengine Database的具體細節，歡迎大家在[GitHub]( https://github.com/taosdata/grafanaplugin"GitHub")上檢視相關原始碼。
[![](http://img.blog.itpub.net/blog/2022/05/11/0fd59db1207fc97f.jpeg?x-oss-process=style/bb)](https://www.taosdata.com/?zh "![](http://img.blog.itpub.net/blog/2022/05/11/0fd59db1207fc97f.jpeg?x-oss-process=style/bb)")

TDengine 如何進行 SQL 寫入？官方最全教程來了

相關文章