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

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

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

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

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

SQL 寫(xiě)入

用戶(hù)可以讓?xiě)?yīng)用通過(guò)連接器執(zhí)行 INSERT 語(yǔ)句來(lái)插入數(shù)據(jù)，還可以通過(guò) TAOS Shell，手動(dòng)輸入 INSERT 語(yǔ)句來(lái)實(shí)現(xiàn)。

• 一次寫(xiě)入一條

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

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

• 一次寫(xiě)入多條

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

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

• 一次寫(xiě)入多表

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

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

• 注意事項(xiàng)

如果想要提高寫(xiě)入效率，我們可以使用批量寫(xiě)入，這樣一批寫(xiě)入的記錄條數(shù)越多，插入效率就會(huì)越高，但需要注意的是，一條記錄不能超過(guò) 48 KB，一條 SQL 語(yǔ)句總長(zhǎng)度不能超過(guò) 1MB。此外，TDengine 支持多線(xiàn)程同時(shí)寫(xiě)入，如果要進(jìn)一步提高寫(xiě)入速度，一個(gè)客戶(hù)端需要打開(kāi) 20 個(gè)以上的線(xiàn)程同時(shí)寫(xiě)。但要注意，線(xiàn)程數(shù)達(dá)到一定數(shù)量后將無(wú)法再提高，甚至還會(huì)下降，因?yàn)榫€(xiàn)程頻繁切換會(huì)帶來(lái)額外開(kāi)銷(xiāo)。

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

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

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

InfluxDB 行協(xié)議

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

measurement,tag_set field_set timestamp

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

例如：

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

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

OpenTSDB 行協(xié)議

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

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

需要注意的是：

• metric 將作為超級(jí)表名。
• timestamp 為本行數(shù)據(jù)對(duì)應(yīng)的時(shí)間戳。根據(jù)時(shí)間戳的長(zhǎng)度自動(dòng)識(shí)別時(shí)間精度。支持秒和毫秒兩種時(shí)間精度
• value 為度量值，必須為一個(gè)數(shù)值。對(duì)應(yīng)的列名也是 “value”。
• 最后一部分是標(biāo)簽集， 用空格分隔不同標(biāo)簽， 所有標(biāo)簽自動(dòng)轉(zhuǎn)化為 nchar 數(shù)據(jù)類(lèi)型;

例如：

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é)議采用一個(gè) 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é)議類(lèi)似，在此種寫(xiě)入?yún)f(xié)議中，metric 將作為超級(jí)表名， timestamp 表示時(shí)間戳，value 表示度量值， tags 表示標(biāo)簽集。具體可以參考 OpenTSDB HTTP API 文檔：http://opentsdb.net/docs/build/html/api_http/put.html

• 注意事項(xiàng)
  • 對(duì)于 JSON 格式協(xié)議，TDengine 并不會(huì)自動(dòng)把所有標(biāo)簽轉(zhuǎn)成 nchar 類(lèi)型，僅會(huì)將字符串轉(zhuǎn)為 nchar 類(lèi)型， 數(shù)值將轉(zhuǎn)換為 double 類(lèi)型。
  • TDengine 只接收 JSON 數(shù)組格式的字符串，即使一行數(shù)據(jù)也需要轉(zhuǎn)換成數(shù)組形式。

寫(xiě)在最后

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

但要注意的是，如果無(wú)論怎么調(diào)節(jié)客戶(hù)端程序，taosd 進(jìn)程的 CPU 使用率始終都很低，那很可能需要增加 vgroup 的數(shù)量，服務(wù)端的配置同樣重要。如果大家在寫(xiě)入操作時(shí)遇到了困難，首先可以進(jìn)入 TDengine 官網(wǎng)-技術(shù)文檔頁(yè)面進(jìn)行查詢(xún)，如果依然無(wú)法解決，我們還有專(zhuān)門(mén)的社區(qū)技術(shù)人員能夠?yàn)槟愦鹨山饣蟆?/p>

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