高效寫入數(shù)據(jù)

TDengine 支持多種接口寫入數(shù)據(jù)，包括 SQL，Prometheus，Telegraf，collectd，StatsD，EMQX MQTT Broker，HiveMQ Broker，CSV 文件等，后續(xù)還將提供 Kafka，OPC 等接口。數(shù)據(jù)可以單條插入，也可以批量插入，可以插入一個數(shù)據(jù)采集點的數(shù)據(jù)，也可以同時插入多個數(shù)據(jù)采集點的數(shù)據(jù)。支持多線程插入，支持時間亂序數(shù)據(jù)插入，也支持歷史數(shù)據(jù)插入。

SQL 寫入

應(yīng)用通過 C/C++, Java, Go, C#, Python, Node.js 連接器執(zhí)行 SQL insert 語句來插入數(shù)據(jù)，用戶還可以通過 TAOS Shell，手動輸入 SQL insert 語句插入數(shù)據(jù)。比如下面這條 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);

詳細的 SQL INSERT 語法規(guī)則請見 TAOS SQL 的數(shù)據(jù)寫入 章節(jié)。

Tips:

• 要提高寫入效率，需要批量寫入。一批寫入的記錄條數(shù)越多，插入效率就越高。但一條記錄不能超過 48K（2.1.7.0 之前的版本為 16K），一條 SQL 語句總長度不能超過 1M 。
• TDengine 支持多線程同時寫入，要進一步提高寫入速度，一個客戶端需要打開 20 個以上的線程同時寫。但線程數(shù)達到一定數(shù)量后，無法再提高，甚至還會下降，因為線程頻繁切換，帶來額外開銷。
• 對同一張表，如果新插入記錄的時間戳已經(jīng)存在，默認情形下（UPDATE=0）新記錄將被直接拋棄，也就是說，在一張表里，時間戳必須是唯一的。如果應(yīng)用自動生成記錄，很有可能生成的時間戳是一樣的，這樣，成功插入的記錄條數(shù)會小于應(yīng)用插入的記錄條數(shù)。如果在創(chuàng)建數(shù)據(jù)庫時使用了 UPDATE 1 選項，插入相同時間戳的新記錄將覆蓋原有記錄。
• 寫入的數(shù)據(jù)的時間戳必須大于當前時間減去配置參數(shù) keep 的時間。如果 keep 配置為3650天，那么無法寫入比 3650 天還早的數(shù)據(jù)。寫入數(shù)據(jù)的時間戳也不能大于當前時間加配置參數(shù) days。如果 days 為 2，那么無法寫入比當前時間還晚2天的數(shù)據(jù)。

無模式（Schemaless）寫入

前言
在物聯(lián)網(wǎng)應(yīng)用中，常會采集比較多的數(shù)據(jù)項，用于實現(xiàn)智能控制、業(yè)務(wù)分析、設(shè)備監(jiān)控等。由于應(yīng)用邏輯的版本升級，或者設(shè)備自身的硬件調(diào)整等原因，數(shù)據(jù)采集項就有可能比較頻繁地出現(xiàn)變動。為了在這種情況下方便地完成數(shù)據(jù)記錄工作，TDengine 從 2.2.0.0 版本開始，提供調(diào)用 Schemaless 寫入方式，可以免于預(yù)先創(chuàng)建超級表/子表的步驟，隨著數(shù)據(jù)寫入接口能夠自動創(chuàng)建與數(shù)據(jù)對應(yīng)的存儲結(jié)構(gòu)。并且在必要時，Schemaless 將自動增加必要的數(shù)據(jù)列，保證用戶寫入的數(shù)據(jù)可以被正確存儲。
目前，TDengine 的所有官方支持的連接器支持 Schemaless 的操作接口，詳情請參見 Schemaless 方式寫入接口章節(jié)。這里對 Schemaless 的數(shù)據(jù)表達格式進行了描述。
無模式寫入方式建立的超級表及其對應(yīng)的子表與通過 SQL 直接建立的超級表和子表完全沒有區(qū)別，您也可以通過 SQL 語句直接向其中寫入數(shù)據(jù)。需要注意的是，通過無模式寫入方式建立的表，其表名是基于標簽值按照固定的映射規(guī)則生成，所以無法明確地進行表意，缺乏可讀性。

無模式寫入行協(xié)議
TDengine 的無模式寫入的行協(xié)議兼容 InfluxDB 的 行協(xié)議（Line Protocol）、OpenTSDB 的 telnet 行協(xié)議、OpenTSDB 的 JSON 格式協(xié)議。但是使用這三種協(xié)議的時候，需要在 API 中指定輸入內(nèi)容使用解析協(xié)議的標準。

對于 InfluxDB、OpenTSDB 的標準寫入?yún)f(xié)議請參考各自的文檔。下面首先以 InfluxDB 的行協(xié)議為基礎(chǔ)，介紹 TDengine 擴展的協(xié)議內(nèi)容，允許用戶采用更加精細的方式控制（超級表）模式。

Schemaless 采用一個字符串來表達一個數(shù)據(jù)行（可以向?qū)懭?API 中一次傳入多行字符串來實現(xiàn)多個數(shù)據(jù)行的批量寫入），其格式約定如下：

measurement,tag_set field_set timestamp

其中:

• measurement 將作為數(shù)據(jù)表名。它與 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ù)對應(yīng)的主鍵時間戳。

tag_set 中的所有的數(shù)據(jù)自動轉(zhuǎn)化為 nchar 數(shù)據(jù)類型，并不需要使用雙引號（")。
在無模式寫入數(shù)據(jù)行協(xié)議中，field_set 中的每個數(shù)據(jù)項都需要對自身的數(shù)據(jù)類型進行描述。具體來說：

• 如果兩邊有英文雙引號，表示 BINARY(32) 類型。例如 "abc"。
• 如果兩邊有英文雙引號而且?guī)в?L 前綴，表示 NCHAR(32) 類型。例如 L"報錯信息"。
• 對空格、等號（=）、逗號（,）、雙引號（"），前面需要使用反斜杠（\）進行轉(zhuǎn)義。（都指的是英文半角符號）
• 數(shù)值類型將通過后綴來區(qū)分數(shù)據(jù)類型：

序號	后綴	映射類型	大小(字節(jié))
1	無或f64	double	8
2	f32	float	4
3	i8	TinyInt	1
4	i16	SmallInt	2
5	i32	Int	4
6	i64或i	Bigint	8

• t, T, true, True, TRUE, f, F, false, False 將直接作為 BOOL 型來處理。

例如如下數(shù)據(jù)行表示：向名為 st 的超級表下的 t1 標簽為 "3"（NCHAR）、t2 標簽為 "4"（NCHAR）、t3 標簽為 "t3"（NCHAR）的數(shù)據(jù)子表，寫入 c1 列為 3（BIGINT）、c2 列為 false（BOOL）、c3 列為 "passit"（BINARY）、c4 列為 4（DOUBLE）、主鍵時間戳為 1626006833639000000 的一行數(shù)據(jù)。

st,t1=3,t2=4,t3=t3 c1=3i64,c3="passit",c2=false,c4=4f64 1626006833639000000

需要注意的是，如果描述數(shù)據(jù)類型后綴時使用了錯誤的大小寫，或者為數(shù)據(jù)指定的數(shù)據(jù)類型有誤，均可能引發(fā)報錯提示而導(dǎo)致數(shù)據(jù)寫入失敗。

無模式寫入的主要處理邏輯

無模式寫入按照如下原則來處理行數(shù)據(jù)：
1. 將使用如下規(guī)則來生成子表名：首先將 measurement 的名稱和標簽的 key 和 value 組合成為如下的字符串

"measurement,tag_key1=tag_value1,tag_key2=tag_value2"

需要注意的是，這里的 tag_key1, tag_key2 并不是用戶輸入的標簽的原始順序，而是使用了標簽名稱按照字符串升序排列后的結(jié)果。所以，tag_key1 并不是在行協(xié)議中輸入的第一個標簽。 排列完成以后計算該字符串的 MD5 散列值 "md5_val"。然后將計算的結(jié)果與字符串組合生成表名：“t_md5val”。其中的 “t” 是固定的前綴，每個通過該映射關(guān)系自動生成的表都具有該前綴。
2. 如果解析行協(xié)議獲得的超級表不存在，則會創(chuàng)建這個超級表。
3. 如果解析行協(xié)議獲得子表不存在，則 Schemaless 會按照步驟 1 或 2 確定的子表名來創(chuàng)建子表。
4. 如果數(shù)據(jù)行中指定的標簽列或普通列不存在，則在超級表中增加對應(yīng)的標簽列或普通列（只增不減）。
5. 如果超級表中存在一些標簽列或普通列未在一個數(shù)據(jù)行中被指定取值，那么這些列的值在這一行中會被置為 NULL。
6. 對 BINARY 或 NCHAR 列，如果數(shù)據(jù)行中所提供值的長度超出了列類型的限制，自動增加該列允許存儲的字符長度上限（只增不減），以保證數(shù)據(jù)的完整保存。
7. 如果指定的數(shù)據(jù)子表已經(jīng)存在，而且本次指定的標簽列取值跟已保存的值不一樣，那么最新的數(shù)據(jù)行中的值會覆蓋舊的標簽列取值。
8. 整個處理過程中遇到的錯誤會中斷寫入過程，并返回錯誤代碼。

備注：
無模式所有的處理邏輯，仍會遵循 TDengine 對數(shù)據(jù)結(jié)構(gòu)的底層限制，例如每行數(shù)據(jù)的總長度不能超過 48K 字節(jié)（2.1.7.0 之前的版本為 16K）。這方面的具體限制約束請參見 TAOS SQL 邊界限制 章節(jié)。

時間分辨率識別
無模式寫入過程中支持三個指定的模式，具體如下

序號	值	說明
1	SML_LINE_PROTOCOL	InfluxDB行協(xié)議（Line Protocol)
2	SML_TELNET_PROTOCOL	OpenTSDB 文本行協(xié)議
3	SML_JSON_PROTOCOL	JSON 協(xié)議格式

在 SML_LINE_PROTOCOL 解析模式下，需要用戶指定輸入的時間戳的時間分辨率?？捎玫臅r間分辨率如下表所示：

序號	時間分辨率定義	含義
1	TSDB_SML_TIMESTAMP_NOT_CONFIGURED	未定義（無效）
2	TSDB_SML_TIMESTAMP_HOURS	小時
3	TSDB_SML_TIMESTAMP_MINUTES	分鐘
4	TSDB_SML_TIMESTAMP_SECONDS	秒
5	TSDB_SML_TIMESTAMP_MILLI_SECONDS	毫秒
6	TSDB_SML_TIMESTAMP_MICRO_SECONDS	微秒
7	TSDB_SML_TIMESTAMP_NANO_SECONDS	納秒

在 SML_TELNET_PROTOCOL 和 SML_JSON_PROTOCOL 模式下，根據(jù)時間戳的長度來確定時間精度（與 OpenTSDB 標準操作方式相同），此時會忽略用戶指定的時間分辨率。

數(shù)據(jù)模式映射規(guī)則
本節(jié)將說明行協(xié)議的數(shù)據(jù)如何映射成為具有模式的數(shù)據(jù)。每個行協(xié)議中數(shù)據(jù) measurement 映射為 超級表名稱。tag_set 中的 標簽名稱為 數(shù)據(jù)模式中的標簽名，field_set 中的名稱為列名稱。以如下數(shù)據(jù)為例，說明映射規(guī)則：

st,t1=3,t2=4,t3=t3 c1=3i64,c3="passit",c2=false,c4=4f64 1626006833639000000

該行數(shù)據(jù)映射生成一個超級表： st， 其包含了 3 個類型為 nchar 的標簽，分別是：t1, t2, t3。五個數(shù)據(jù)列，分別是ts（timestamp），c1 (bigint），c3(binary)，c2 (bool), c4 (bigint）。映射成為如下 SQL 語句：

create stable st (_ts timestamp, c1 bigint, c2 bool, c3 binary(6), c4 bigint) tags(t1 nchar(1), t2 nchar(1), t3 nchar(2))

數(shù)據(jù)模式變更處理
本節(jié)將說明不同行數(shù)據(jù)寫入情況下，對于數(shù)據(jù)模式的影響。

在使用行協(xié)議寫入一個明確的標識的字段類型的時候，后續(xù)更改該字段的類型定義，會出現(xiàn)明確的數(shù)據(jù)模式錯誤，即會觸發(fā)寫入 API 報告錯誤。如下所示，

st,t1=3,t2=4,t3=t3 c1=3i64,c3="passit",c2=false,c4=4    1626006833639000000
st,t1=3,t2=4,t3=t3 c1=3i64,c3="passit",c2=false,c4=4i   1626006833640000000

第一行的數(shù)據(jù)類型映射將 c4 列定義為 Double， 但是第二行的數(shù)據(jù)又通過數(shù)值后綴方式聲明該列為 BigInt， 由此會觸發(fā)無模式寫入的解析錯誤。

如果列前面的行協(xié)議將數(shù)據(jù)列聲明為了 binary， 后續(xù)的要求長度更長的binary長度，此時會觸發(fā)超級表模式的變更。

st,t1=3,t2=4,t3=t3 c1=3i64,c5="pass"     1626006833639000000
st,t1=3,t2=4,t3=t3 c1=3i64,c5="passit"   1626006833640000000

第一行中行協(xié)議解析會聲明 c5 列是一個 binary(4)的字段，第二次行數(shù)據(jù)寫入會提取列 c5 仍然是 binary 列，但是其寬度為 6，此時需要將binary的寬度增加到能夠容納 新字符串的寬度。

st,t1=3,t2=4,t3=t3 c1=3i64               1626006833639000000
st,t1=3,t2=4,t3=t3 c1=3i64,c6="passit"   1626006833640000000

第二行數(shù)據(jù)相對于第一行來說增加了一個列 c6，類型為 binary(6)。那么此時會自動增加一個列 c6， 類型為 binary(6)。

寫入完整性
TDengine 提供數(shù)據(jù)寫入的冪等性保證，即您可以反復(fù)調(diào)用 API 進行出錯數(shù)據(jù)的寫入操作。但是不提供多行數(shù)據(jù)寫入的原子性保證。即在多行數(shù)據(jù)一批次寫入過程中，會出現(xiàn)部分數(shù)據(jù)寫入成功，部分數(shù)據(jù)寫入失敗的情況。

錯誤碼
如果是無模式寫入過程中的數(shù)據(jù)本身錯誤，應(yīng)用會得到 TSDB_CODE_TSC_LINE_SYNTAX_ERROR 錯誤信息，該錯誤信息表明錯誤發(fā)生在寫入文本中。其他的錯誤碼與原系統(tǒng)一致，可以通過 taos_errstr() 獲取具體的錯誤原因。

除使用 C 版本的 API，也可以使用官網(wǎng)連接器，包括 Java/Go/Python/C#/Node.js/Rust 等。此外，在 TDengine v2.4 及后續(xù)版本中，您還可以通過 taosAdapter 采用 RESTful 的方式直接寫入無模式數(shù)據(jù)。

Prometheus 直接寫入（通過 taosAdapter）

remote_read 和 remote_write 是 Prometheus 數(shù)據(jù)讀寫分離的集群方案。 只需要將 remote_read 和 remote_write url 指向 taosAdapter 對應(yīng)的 url 同時設(shè)置 Basic 驗證即可使用。

• remote_read url : http://host_to_taosAdapter:port(default 6041)/prometheus/v1/remote_read/:db
• remote_write url : http://host_to_taosAdapter:port(default 6041)/prometheus/v1/remote_write/:db

Basic驗證：

• username： TDengine 連接用戶名
• password： TDengine 連接密碼

示例 prometheus.yml 如下：

remote_write:
  - url: "http://localhost:6041/prometheus/v1/remote_write/prometheus_data"
    basic_auth:
      username: root
      password: taosdata

remote_read:
  - url: "http://localhost:6041/prometheus/v1/remote_read/prometheus_data"
    basic_auth:
      username: root
      password: taosdata
    remote_timeout: 10s
    read_recent: true

Telegraf 直接寫入(通過 taosAdapter)

安裝 Telegraf 請參考官方文檔。

TDengine 新版本（2.3.0.0+）包含一個 taosAdapter 獨立程序，負責接收包括 Telegraf 的多種應(yīng)用的數(shù)據(jù)寫入。

配置方法，在 /etc/telegraf/telegraf.conf 增加如下文字，其中 database name 請?zhí)顚懴Ｍ?TDengine 保存 Telegraf 數(shù)據(jù)的數(shù)據(jù)庫名，TDengine server/cluster host、username和 password 填寫 TDengine 實際值：

[[outputs.http]]
  url = "http://<TDengine server/cluster host>:6041/influxdb/v1/write?db=<database name>"
  method = "POST"
  timeout = "5s"
  username = "<TDengine's username>"
  password = "<TDengine's password>"
  data_format = "influx"
  influx_max_line_bytes = 250

然后重啟 telegraf：

sudo systemctl start telegraf

即可在 TDengine 中查詢 metrics 數(shù)據(jù)庫中 Telegraf 寫入的數(shù)據(jù)。

taosAdapter 相關(guān)配置參數(shù)請參考 taosadapter --help 命令輸出以及相關(guān)文檔。

collectd 直接寫入(通過 taosAdapter)

安裝 collectd，請參考官方文檔。

TDengine 新版本（2.3.0.0+）包含一個 taosAdapter 獨立程序，負責接收包括 collectd 的多種應(yīng)用的數(shù)據(jù)寫入。

在 /etc/collectd/collectd.conf 文件中增加如下內(nèi)容，其中 host 和 port 請?zhí)顚?TDengine 和 taosAdapter 配置的實際值：

LoadPlugin network
<Plugin network>
  Server "<TDengine cluster/server host>" "<port for collectd>"
</Plugin>

重啟 collectd

sudo systemctl start collectd

taosAdapter 相關(guān)配置參數(shù)請參考 taosadapter --help 命令輸出以及相關(guān)文檔。

StatsD 直接寫入(通過 taosAdapter)

安裝 StatsD 請參考官方文檔。

TDengine 新版本（2.3.0.0+）包含一個 taosAdapter 獨立程序，負責接收包括 StatsD 的多種應(yīng)用的數(shù)據(jù)寫入。

在 config.js 文件中增加如下內(nèi)容后啟動 StatsD，其中 host 和 port 請?zhí)顚?TDengine 和 taosAdapter 配置的實際值：

backends 部分添加 "./backends/repeater"
repeater 部分添加 { host:'<TDengine server/cluster host>', port: <port for StatsD>}

示例配置文件：

{
port: 8125
, backends: ["./backends/repeater"]
, repeater: [{ host: '127.0.0.1', port: 6044}]
}

taosAdapter 相關(guān)配置參數(shù)請參考 taosadapter --help 命令輸出以及相關(guān)文檔。

icinga2 可以收集監(jiān)控和性能數(shù)據(jù)并寫入 OpenTSDB，taosAdapter 可以支持接收 icinga2 的數(shù)據(jù)并寫入到 TDengine 中。

icinga2 直接寫入(通過 taosAdapter)

• 參考鏈接 https://icinga.com/docs/icinga-2/latest/doc/14-features/#opentsdb-writer 使能 opentsdb-writer
• 使能 taosAdapter 配置項 opentsdb_telnet.enable
• 修改配置文件 /etc/icinga2/features-enabled/opentsdb.conf

object OpenTsdbWriter "opentsdb" {
  host = "host to taosAdapter"
  port = 6048
}

taosAdapter 相關(guān)配置參數(shù)請參考 taosadapter --help 命令輸出以及相關(guān)文檔。

TCollector 直接寫入(通過 taosAdapter)

TCollector 是一個在客戶側(cè)收集本地收集器并發(fā)送數(shù)據(jù)到 OpenTSDB 的進程，taosAdapter 可以支持接收 TCollector 的數(shù)據(jù)并寫入到 TDengine 中。

使能 taosAdapter 配置項 opentsdb_telnet.enable 修改 TCollector 配置文件，修改 OpenTSDB 宿主機地址為 taosAdapter 被部署的地址，并修改端口號為 taosAdapter 使用的端口（默認6049）。

taosAdapter 相關(guān)配置參數(shù)請參考 taosadapter --help 命令輸出以及相關(guān)文檔。

EMQX Broker 直接寫入

MQTT 是流行的物聯(lián)網(wǎng)數(shù)據(jù)傳輸協(xié)議，EMQX 是一開源的 MQTT Broker 軟件，無需任何代碼，只需要在 EMQX Dashboard 里使用“規(guī)則”做簡單配置，即可將 MQTT 的數(shù)據(jù)直接寫入 TDengine。EMQX 支持通過 發(fā)送到 Web 服務(wù)的方式保存數(shù)據(jù)到 TDengine，也在企業(yè)版上提供原生的 TDengine 驅(qū)動實現(xiàn)直接保存。詳細使用方法請參考 EMQX 官方文檔。

HiveMQ Broker 直接寫入

HiveMQ 是一個提供免費個人版和企業(yè)版的 MQTT 代理，主要用于企業(yè)和新興的機器到機器M2M通訊和內(nèi)部傳輸，滿足可伸縮性、易管理和安全特性。HiveMQ 提供了開源的插件開發(fā)包?？梢酝ㄟ^ HiveMQ extension - TDengine 保存數(shù)據(jù)到 TDengine。詳細使用方法請參考 HiveMQ extension - TDengine 說明文檔。