小 T 導讀：眾所周知，TDengine 支持多種寫入?yún)f(xié)議，包括 SQL、InfluxDB Line 協(xié)議、OpenTSDB Telnet 協(xié)議、OpenTSDB JSON 格式協(xié)議。但說到如何進行寫入操作，很多讀者可能都是一頭霧水，本篇文章為大家匯總了一系列的寫入教程，方便有需要的開發(fā)者作為寫入指南收藏使用。

TDengine 中的 SQL 寫入即模式化寫入，在寫入到 Database 之前，需要預先定義好數(shù)據(jù)表的 Schema 模式，具體來說就是數(shù)據(jù)表包含多少列，每列存放的數(shù)據(jù)類型是什么。即在建表時使用標準的 SQL 語句指定表的 Schema，再遵照預先建好的列跟標簽值的數(shù)量和類型進行數(shù)據(jù)寫入。

除了 SQL 寫入外， TDengine 還支持三種無模式寫入?yún)f(xié)議，分別是 InfluxDB Line 協(xié)議、OpenTSDB Telnet 協(xié)議和 OpenTSDB JSON 格式協(xié)議。如果你對 NoSQL 比較熟悉，那對無模式寫入應該就不會陌生了。通俗來講，無模式寫入為用戶提供了一種以文本格式將數(shù)據(jù)寫入到 TDengine 的方式，更加便捷。

物聯(lián)網(wǎng)場景中的應用經(jīng)常需要采集比較多的數(shù)據(jù)項，用于實現(xiàn)智能控制、業(yè)務分析和設備監(jiān)控等，由于應用邏輯的版本升級，或者設備自身的硬件調整等原因，數(shù)據(jù)采集項有可能比較頻繁地出現(xiàn)變動，為了在這種情況下仍能方便地完成數(shù)據(jù)記錄工作，TDengine 從 2.2 版本開始就提供了無模式寫入方式，寫入時無需提前創(chuàng)建超級表和子表，其引擎能自適應數(shù)據(jù)并對表結構進行調整。

在使用 TDengine 寫入數(shù)據(jù)時，數(shù)據(jù)可以單條插入，也可以批量插入，可以插入一個數(shù)據(jù)采集點的數(shù)據(jù)，也可以同時插入多個數(shù)據(jù)采集點的數(shù)據(jù)。此外，TDengine 不僅支持多線程插入、時間亂序數(shù)據(jù)插入，也支持歷史數(shù)據(jù)插入。下面將對四種寫入?yún)f(xié)議進行說明，以供參考。

SQL 寫入

用戶可以讓應用通過連接器執(zhí)行 INSERT 語句來插入數(shù)據(jù)，還可以通過 TAOS Shell，手動輸入 INSERT 語句來實現(xiàn)。

• 一次寫入一條

下面這條 INSERT 就將一條記錄寫入到表 d1001 中：

INSERT INTO d1001 VALUES (1538548685000, 10.3, 219, 0.31);

• 一次寫入多條

TDengine 支持一次寫入多條記錄，比如下面這條命令就將兩條記錄寫入到表 d1001 中：

INSERT INTO d1001 VALUES (1538548684000, 10.2, 220, 0.23) (1538548696650, 10.3, 218, 0.25);

• 一次寫入多表

TDengine 也支持一次向多個表寫入數(shù)據(jù)，比如下面這條命令就向 d1001 寫入兩條記錄，向 d1002 寫入一條記錄：

INSERT INTO d1001 VALUES (1538548685000, 10.3, 219, 0.31) (1538548695000, 12.6, 218, 0.33) d1002 VALUES (1538548696800, 12.3, 221, 0.31);

• 注意事項

如果想要提高寫入效率，我們可以使用批量寫入，這樣一批寫入的記錄條數(shù)越多，插入效率就會越高，但需要注意的是，一條記錄不能超過 48 KB，一條 SQL 語句總長度不能超過 1MB。此外，TDengine 支持多線程同時寫入，如果要進一步提高寫入速度，一個客戶端需要打開 20 個以上的線程同時寫。但要注意，線程數(shù)達到一定數(shù)量后將無法再提高，甚至還會下降，因為線程頻繁切換會帶來額外開銷。

對同一張表來說，如果新插入記錄的時間戳已經(jīng)存在，那默認情形下（UPDATE=0）新記錄將被直接拋棄，也就是說，在一張表里時間戳必須是唯一的。如果讓應用自動生成記錄，很可能生成的時間戳是一樣的，這樣一來，成功插入的記錄條數(shù)就會小于應用插入的記錄條數(shù)。如果在創(chuàng)建 Database 時使用了 UPDATE 為 1 的選項，插入相同時間戳的新記錄將覆蓋原有記錄。

最后一點，寫入數(shù)據(jù)的時間戳必須大于當前時間減去配置參數(shù) keep 的時間，如果 keep 配置為 3650 天，那么將無法寫入比 3650 天還早的數(shù)據(jù)；而且寫入數(shù)據(jù)的時間戳也不能大于當前時間加配置參數(shù) days，即如果 days 為 2，那么也將無法寫入比當前時間還晚 2 天的數(shù)據(jù)。

關于 SQL 寫入的更詳細語法規(guī)則可參考此前發(fā)布的使用 TDengine 如何進行 SQL 寫入 一文。

InfluxDB 行協(xié)議

InfluxDB Line 協(xié)議采用一行字符串來表示一行數(shù)據(jù)。分為四部分：

measurement,tag_set field_set timestamp

• measurement 將作為超級表名。它與 tag_set 之間使用一個英文逗號來分隔。
• tag_set 將作為標簽數(shù)據(jù)，其格式形如 <tag_key>=<tag_value>,<tag_key>=<tag_value>，也即可以使用英文逗號來分隔多個標簽數(shù)據(jù)。它與 field_set 之間使用一個半角空格來分隔。
• field_set 將作為普通列數(shù)據(jù)，其格式形如 <field_key>=<field_value>,<field_key>=<field_value>，同樣是使用英文逗號來分隔多個普通列的數(shù)據(jù)。它與 timestamp 之間使用一個半角空格來分隔。
• timestamp 即本行數(shù)據(jù)對應的主鍵時間戳。

例如：

meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611249500

• 注意事項
  • tag_set 中的所有數(shù)據(jù)會自動轉化為 nchar 數(shù)據(jù)類型；
  • field_set 中的每個數(shù)據(jù)項都需要對自身的數(shù)據(jù)類型進行描述，比如 1.2f32 代表 float 類型的數(shù)值 1.2，如果不帶類型后綴會被當作 double 處理；
  • timestamp 支持多種時間精度。寫入數(shù)據(jù)時需要用參數(shù)指定時間精度，支持從小時到納秒的 6 種時間精度。

OpenTSDB 行協(xié)議

OpenTSDB 行協(xié)議同樣采用一行字符串來表示一行數(shù)據(jù)。由于 OpenTSDB 采用的是單列模型，因此一行只能包含一個普通數(shù)據(jù)列，但標簽列依然可以有多個。該協(xié)議同樣分為四部分，具體格式約定如下：

<metric> <timestamp> <value> <tagk_1>=<tagv_1>[ <tagk_n>=<tagv_n>]

需要注意的是：

• metric 將作為超級表名。
• timestamp 為本行數(shù)據(jù)對應的時間戳。根據(jù)時間戳的長度自動識別時間精度。支持秒和毫秒兩種時間精度
• value 為度量值，必須為一個數(shù)值。對應的列名也是 “value”。
• 最后一部分是標簽集， 用空格分隔不同標簽， 所有標簽自動轉化為 nchar 數(shù)據(jù)類型;

例如：

meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3

具體可以參考 OpenTSDB Telnet API 文檔：http://opentsdb.net/docs/build/html/api_telnet/put.html

OpenTSDB JSON 格式協(xié)議

OpenTSDB JSON 格式協(xié)議采用一個 JSON 字符串表示一行或多行數(shù)據(jù)。例如：

[
  {
    "metric": "sys.cpu.nice",
    "timestamp": 1346846400,
    "value": 18,
    "tags": {
      "host": "web01",
      "dc": "lga"
    }
  },
  {
    "metric": "sys.cpu.nice",
    "timestamp": 1346846400,
    "value": 9,
    "tags": {
      "host": "web02",
      "dc": "lga"
    }
  }
]

與 OpenTSDB 行協(xié)議類似，在此種寫入?yún)f(xié)議中，metric 將作為超級表名， timestamp 表示時間戳，value 表示度量值， tags 表示標簽集。具體可以參考 OpenTSDB HTTP API 文檔：http://opentsdb.net/docs/build/html/api_http/put.html

• 注意事項
  • 對于 JSON 格式協(xié)議，TDengine 并不會自動把所有標簽轉成 nchar 類型，僅會將字符串轉為 nchar 類型， 數(shù)值將轉換為 double 類型。
  • TDengine 只接收 JSON 數(shù)組格式的字符串，即使一行數(shù)據(jù)也需要轉換成數(shù)組形式。

寫在最后

為了更高效地向 TDengine 寫入數(shù)據(jù)，客戶端程序要充分且恰當?shù)乩靡韵聨讉€因素：數(shù)據(jù)在不同表（或子表）之間的分布，即要寫入數(shù)據(jù)的相鄰性；單次寫入的數(shù)據(jù)量；并發(fā)連接數(shù)。在單次寫入中盡量只向同一張表（或子表）寫入數(shù)據(jù)，每批次寫入的數(shù)據(jù)量經(jīng)過測試和調優(yōu)，設定為一個最適合當前系統(tǒng)處理能力的數(shù)值，并發(fā)寫入的連接數(shù)同樣經(jīng)過測試和調優(yōu)后，設定為一個最適合當前系統(tǒng)處理能力的數(shù)值，以實現(xiàn)在當前系統(tǒng)中的最佳寫入速度。此外，TDengine 提供的獨特參數(shù)綁定寫入，也是一個有助于實現(xiàn)高效寫入的方法。

但要注意的是，如果無論怎么調節(jié)客戶端程序，taosd 進程的 CPU 使用率始終都很低，那很可能需要增加 vgroup 的數(shù)量，服務端的配置同樣重要。如果大家在寫入操作時遇到了困難，首先可以進入 TDengine 官網(wǎng)-技術文檔頁面進行查詢，如果依然無法解決，我們還有專門的社區(qū)技術人員能夠為你答疑解惑。

此外，如果大家想了解 Java、Python、Go、Rust、Node.js、C#、C 不同語言的寫入示例代碼，也可以進入 TDengine 官網(wǎng)-技術文檔頁面查看更多詳情。