連接器

TDengine 提供了豐富的應(yīng)用程序開發(fā)接口，其中包括 C/C++、Java、Python、Go、Node.js、C# 、RESTful 等，便于用戶快速開發(fā)應(yīng)用。

目前 TDengine 的連接器可支持的平臺廣泛，包括：X64/X86/ARM64/ARM32/MIPS/Alpha 等硬件平臺，以及 Linux/Win64/Win32 等開發(fā)環(huán)境。對照矩陣如下：

CPU	X64 64bit	X64 64bit	X64 64bit	X86 32bit	ARM64	ARM32	MIPS 龍芯	Alpha 申威	X64 海光
OS	Linux	Win64	Win32	Win32	Linux	Linux	Linux	Linux	Linux
C/C++	●	●	●	○	●	●	○	○	○
JDBC	●	●	●	○	●	●	○	○	○
Python	●	●	●	○	●	●	○	--	○
Go	●	●	●	○	●	●	○	--	--
Node.js	●	●	○	○	●	●	○	--	--
C#	●	●	○	○	○	○	○	--	--
RESTful	●	●	●	●	●	●	○	○	○

其中 ● 表示官方測試驗(yàn)證通過，○ 表示非官方測試驗(yàn)證通過，-- 表示未經(jīng)驗(yàn)證。

注意：

• 在沒有安裝 TDengine 服務(wù)端軟件的系統(tǒng)中使用連接器（除 RESTful 外）訪問 TDengine 數(shù)據(jù)庫，需要安裝相應(yīng)版本的客戶端安裝包來使應(yīng)用驅(qū)動（Linux 系統(tǒng)中文件名為 libtaos.so，Windows 系統(tǒng)中為 taos.dll）被安裝在系統(tǒng)中，否則會產(chǎn)生無法找到相應(yīng)庫文件的錯(cuò)誤。
• 所有執(zhí)行 SQL 語句的 API，例如 C/C++ Connector 中的 taos_query、taos_query_a、taos_subscribe 等，以及其它語言中與它們對應(yīng)的 API，每次都只能執(zhí)行一條 SQL 語句，如果實(shí)際參數(shù)中包含了多條語句，它們的行為是未定義的。
• 升級 TDengine 到 2.0.8.0 版本的用戶，必須更新 JDBC。連接 TDengine 必須升級 taos-jdbcdriver 到 2.0.12 及以上。詳細(xì)的版本依賴關(guān)系請參見 taos-jdbcdriver 文檔。
• 無論選用何種編程語言的連接器，2.0 及以上版本的 TDengine 推薦數(shù)據(jù)庫應(yīng)用的每個(gè)線程都建立一個(gè)獨(dú)立的連接，或基于線程建立連接池，以避免連接內(nèi)的“USE statement”狀態(tài)量在線程之間相互干擾（但連接的查詢和寫入操作都是線程安全的）。

安裝連接器驅(qū)動步驟

服務(wù)器應(yīng)該已經(jīng)安裝 TDengine 服務(wù)端安裝包。連接器驅(qū)動安裝步驟如下：

Linux

1. 從濤思官網(wǎng)下載：

• X64 硬件環(huán)境：TDengine-client-2.x.x.x-Linux-x64.tar.gz

• ARM64 硬件環(huán)境：TDengine-client-2.x.x.x-Linux-aarch64.tar.gz

• ARM32 硬件環(huán)境：TDengine-client-2.x.x.x-Linux-aarch32.tar.gz

2. 解壓縮軟件包

將軟件包放置在當(dāng)前用戶可讀寫的任意目錄下，然后執(zhí)行下面的命令：

tar -xzvf TDengine-client-xxxxxxxxx.tar.gz

其中xxxxxxxxx需要替換為實(shí)際版本的字符串。

3. 執(zhí)行安裝腳本

解壓軟件包之后，會在解壓目錄下看到以下文件(目錄)：

? install_client.sh：安裝腳本，用于應(yīng)用驅(qū)動程序 ? taos.tar.gz：應(yīng)用驅(qū)動安裝包 ? driver：TDengine應(yīng)用驅(qū)動driver ? connector: 各種編程語言連接器（Go/Node.js/Python/JDBC） ? examples: 各種編程語言的示例程序（c/C#/Go/JDBC/MATLAB/Python/R）

運(yùn)行install_client.sh進(jìn)行安裝。

4. 配置taos.cfg

編輯 taos.cfg 文件（默認(rèn)路徑/etc/taos/taos.cfg），將 firstEP 修改為 TDengine 服務(wù)器的 End Point，例如：h1.taos.com:6030

提示：

1. 如本機(jī)沒有部署 TDengine 服務(wù)，僅安裝了應(yīng)用驅(qū)動，則 taos.cfg 中僅需配置 firstEP，無需配置 FQDN。
2. 為防止與服務(wù)器端連接時(shí)出現(xiàn) “unable to resolve FQDN” 錯(cuò)誤，建議確認(rèn)客戶端的 hosts 文件已經(jīng)配置正確的 FQDN 值。

Windows x64/x86

1. 從濤思官網(wǎng)下載：

• X64硬件環(huán)境：TDengine-client-2.X.X.X-Windows-x64.exe

• X86硬件環(huán)境：TDengine-client-2.X.X.X-Windows-x86.exe

2. 執(zhí)行安裝程序，按提示選擇默認(rèn)值，完成安裝

3. 安裝路徑

默認(rèn)安裝路徑為：C:\TDengine，其中包括以下文件(目錄)：

? taos.exe：taos shell命令行程序

? cfg : 配置文件目錄 ? driver: 應(yīng)用驅(qū)動動態(tài)鏈接庫 ? examples: 示例程序 bash/C/C#/go/JDBC/Python/Node.js ? include: 頭文件 ? log : 日志文件 ? unins000.exe: 卸載程序

4. 配置taos.cfg

編輯 taos.cfg 文件(默認(rèn)路徑C:\TDengine\cfg\taos.cfg)，將 firstEP 修改為 TDengine 服務(wù)器的 End Point，例如：h1.taos.com:6030

提示：

1. 如利用 FQDN 連接服務(wù)器，必須確認(rèn)本機(jī)網(wǎng)絡(luò)環(huán)境DNS已配置好，或在 hosts 文件中添加 FQDN 尋址記錄，如編輯C:\Windows\system32\drivers\etc\hosts，添加如下的記錄：192.168.1.99 h1.taos.com
2. 卸載：運(yùn)行unins000.exe可卸載TDengine應(yīng)用驅(qū)動。

安裝驗(yàn)證

以上安裝和配置完成后，并確認(rèn) TDengine 服務(wù)已經(jīng)正常啟動運(yùn)行，此時(shí)可以執(zhí)行 taos 客戶端進(jìn)行登錄。

Linux環(huán)境：

在 Linux shell 下直接執(zhí)行 taos，應(yīng)該就能正常連接到 TDengine 服務(wù)，進(jìn)入到 taos shell 界面，示例如下：

$ taos     
Welcome to the TDengine shell from Linux, Client  Version:2.0.5.0  
Copyright (c) 2017 by TAOS Data, Inc. All rights  reserved.     
taos> show databases;           
name       |   created_time    |   ntables  |  vgroups   | replica | quorum | days |    keep1,keep2,keep(D)   | cache(MB)|   blocks  |  minrows   |  maxrows  | wallevel |  fsync    | comp | precision |    status  |  
=========================================================================================================================================================================================================================  
test       | 2020-10-14  10:35:48.617 |     10 |      1 |    1 |   1 |     2 | 3650,3650,3650        |     16|      6 |     100 |    4096 |    1 |    3000 |  2 | ms      | ready    |   
log        | 2020-10-12  09:08:21.651 |      4 |      1 |    1 |   1 |   10 | 30,30,30               |      1|      3 |     100 |    4096 |    1 |    3000 |  2 | us    | ready    |  
Query OK, 2 row(s) in set (0.001198s)     
taos>  

Windows（x64/x86）環(huán)境：

在 cmd 下進(jìn)入到 C:\TDengine 目錄下直接執(zhí)行 taos.exe，應(yīng)該就能正常鏈接到 TDengine 服務(wù)，進(jìn)入到 taos shell 界面，示例如下：

  C:\TDengine>taos     
  Welcome to the TDengine  shell from Linux, Client Version:2.0.5.0  
  Copyright (c) 2017 by  TAOS Data, Inc. All rights reserved.     
  taos> show  databases;         
  name       |   created_time    |   ntables  |  vgroups   | replica | quorum | days |    keep1,keep2,keep(D)   | cache(MB)   |  blocks  |   minrows  |  maxrows   | wallevel |  fsync  | comp | precision |  status    |  
  ===================================================================================================================================================================================================================================================================   
  test       | 2020-10-14  10:35:48.617 |     10 |      1 |    1 |   1 |     2 | 3650,3650,3650        |     16 |      6 |     100 |    4096 |    1 |    3000 |  2 | ms    | ready    |   
  log        | 2020-10-12  09:08:21.651 |      4 |      1 |    1 |   1 |    10 | 30,30,30              |      1 |      3 |     100 |    4096 |    1 |    3000 |  2 | us    | ready    |  
  Query OK, 2 row(s) in  set (0.045000s)     
  taos>  

C/C++ Connector

C/C++連接器支持的系統(tǒng)有：

CPU類型	x64（64bit）			ARM64	ARM32
OS類型	Linux	Win64	Win32	Linux	Linux
支持與否	支持	支持	支持	支持	支持

C/C++ 的 API 類似于 MySQL 的 C API。應(yīng)用程序使用時(shí)，需要包含 TDengine 頭文件 taos.h，里面列出了提供的 API 的函數(shù)原型。安裝后，taos.h 位于：

• Linux：/usr/local/taos/include
• Windows：C:\TDengine\include

#include <taos.h>

注意：

• 在編譯時(shí)需要鏈接 TDengine 動態(tài)庫。Linux 為 libtaos.so ，安裝后，位于 /usr/local/taos/driver。Windows 為 taos.dll，安裝后位于 C:\TDengine。
• 如未特別說明，當(dāng)API的返回值是整數(shù)時(shí)，0 代表成功，其它是代表失敗原因的錯(cuò)誤碼，當(dāng)返回值是指針時(shí)， NULL 表示失敗。
• 在 taoserror.h 中有所有的錯(cuò)誤碼，以及對應(yīng)的原因描述。tstrerror(errno) 可以獲取錯(cuò)誤碼對應(yīng)的錯(cuò)誤信息。

示例程序

使用 C/C++ 連接器的示例代碼請參見 https://github.com/taosdata/TDengine/tree/develop/examples/c。

示例程序源碼也可以在安裝目錄下的 examples/c 路徑下找到：

apitest.c、asyncdemo.c、demo.c、prepare.c、stream.c、subscribe.c

該目錄下有 makefile，在 Linux 環(huán)境下，直接執(zhí)行 make 就可以編譯得到執(zhí)行文件。

在一臺機(jī)器上啟動 TDengine 服務(wù)，執(zhí)行這些示例程序，按照提示輸入 TDengine 服務(wù)的 FQDN，就可以正常運(yùn)行，并打印出信息。

提示：在 ARM 環(huán)境下編譯時(shí)，請將 makefile 中的 -msse4.2 打開，這個(gè)選項(xiàng)只有在 x64/x86 硬件平臺上才能支持。

基礎(chǔ)API

基礎(chǔ) API 用于完成創(chuàng)建數(shù)據(jù)庫連接等工作，為其它 API 的執(zhí)行提供運(yùn)行時(shí)環(huán)境。

• void taos_init()

  初始化運(yùn)行環(huán)境。如果應(yīng)用沒有主動調(diào)用該 API，那么應(yīng)用在調(diào)用 taos_connect() 時(shí)將自動調(diào)用，故應(yīng)用程序一般無需手動調(diào)用該 API。

• void taos_cleanup()

  清理運(yùn)行環(huán)境，應(yīng)用退出前應(yīng)調(diào)用此 API。

• int taos_options(TSDB_OPTION option, const void * arg, ...)

  設(shè)置客戶端選項(xiàng)，目前支持區(qū)域設(shè)置（TSDB_OPTION_LOCALE）、字符集設(shè)置（TSDB_OPTION_CHARSET）、時(shí)區(qū)設(shè)置（TSDB_OPTION_TIMEZONE）、配置文件路徑設(shè)置（TSDB_OPTION_CONFIGDIR）。區(qū)域設(shè)置、字符集、時(shí)區(qū)默認(rèn)為操作系統(tǒng)當(dāng)前設(shè)置。

  返回值為 0 表示成功，-1 表示失敗。

• char *taos_get_client_info()

  獲取客戶端版本信息。

• TAOS *taos_connect(const char *host, const char *user, const char *pass, const char *db, int port)

  創(chuàng)建數(shù)據(jù)庫連接，初始化連接上下文。其中需要用戶提供的參數(shù)包含：

  • host：TDengine 管理主節(jié)點(diǎn)的 FQDN
  • user：用戶名
  • pass：密碼
  • db：數(shù)據(jù)庫名字，如果用戶沒有提供，也可以正常連接，用戶可以通過該連接創(chuàng)建新的數(shù)據(jù)庫，如果用戶提供了數(shù)據(jù)庫名字，則說明該數(shù)據(jù)庫用戶已經(jīng)創(chuàng)建好，缺省使用該數(shù)據(jù)庫
  • port：TDengine 管理主節(jié)點(diǎn)的端口號

  返回值為空表示失敗。應(yīng)用程序需要保存返回的參數(shù)，以便后續(xù) API 調(diào)用。

  提示: 同一進(jìn)程可以根據(jù)不同的 host/port 連接多個(gè) taosd 集群

• char *taos_get_server_info(TAOS *taos)

  獲取服務(wù)端版本信息。

• int taos_select_db(TAOS *taos, const char *db)

  將當(dāng)前的缺省數(shù)據(jù)庫設(shè)置為db。

  返回值為錯(cuò)誤碼。

• void taos_close(TAOS *taos)

  關(guān)閉連接，其中taos是taos_connect函數(shù)返回的指針。

同步查詢API

傳統(tǒng)的數(shù)據(jù)庫操作 API，都屬于同步操作。應(yīng)用調(diào)用 API 后，一直處于阻塞狀態(tài)，直到服務(wù)器返回結(jié)果。TDengine 支持如下 API：

• TAOS_RES* taos_query(TAOS *taos, const char *sql)

  該API用來執(zhí)行 SQL 語句，可以是 DQL、DML 或 DDL 語句。 其中的 taos 參數(shù)是通過 taos_connect 獲得的指針。不能通過返回值是否是 NULL 來判斷執(zhí)行結(jié)果是否失敗，而是需要用 taos_errno 函數(shù)解析結(jié)果集中的錯(cuò)誤代碼來進(jìn)行判斷。

• int taos_result_precision(TAOS_RES *res)

  返回結(jié)果集時(shí)間戳字段的精度，0 代表毫秒，1 代表微秒，2 代表納秒。

• TAOS_ROW taos_fetch_row(TAOS_RES *res)

  按行獲取查詢結(jié)果集中的數(shù)據(jù)。

• int taos_fetch_block(TAOS_RES *res, TAOS_ROW *rows)

  批量獲取查詢結(jié)果集中的數(shù)據(jù)，返回值為獲取到的數(shù)據(jù)的行數(shù)。

• int taos_num_fields(TAOS_RES *res) 和 int taos_field_count(TAOS_RES *res)

  這兩個(gè)API等價(jià)，用于獲取查詢結(jié)果集中的列數(shù)。

• int* taos_fetch_lengths(TAOS_RES *res)

  獲取結(jié)果集中每個(gè)字段的長度。 返回值是一個(gè)數(shù)組，其長度為結(jié)果集的列數(shù)。

• int taos_affected_rows(TAOS_RES *res)

  獲取被所執(zhí)行的 SQL 語句影響的行數(shù)。

• TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)

  獲取查詢結(jié)果集每列數(shù)據(jù)的屬性（列的名稱、列的數(shù)據(jù)類型、列的長度），與 taos_num_fileds 配合使用，可用來解析 taos_fetch_row 返回的一個(gè)元組(一行)的數(shù)據(jù)。 TAOS_FIELD 的結(jié)構(gòu)如下：

typedef struct taosField {
  char     name[65];  // 列名
  uint8_t  type;      // 數(shù)據(jù)類型
  int16_t  bytes;     // 長度，單位是字節(jié)
} TAOS_FIELD;

• void taos_stop_query(TAOS_RES *res)

  停止一個(gè)查詢的執(zhí)行。

• void taos_free_result(TAOS_RES *res)

  釋放查詢結(jié)果集以及相關(guān)的資源。查詢完成后，務(wù)必調(diào)用該 API 釋放資源，否則可能導(dǎo)致應(yīng)用內(nèi)存泄露。但也需注意，釋放資源后，如果再調(diào)用 taos_consume 等獲取查詢結(jié)果的函數(shù)，將導(dǎo)致應(yīng)用 Crash。

• char *taos_errstr(TAOS_RES *res)

  獲取最近一次API調(diào)用失敗的原因,返回值為字符串。

• int taos_errno(TAOS_RES *res)

  獲取最近一次API調(diào)用失敗的原因，返回值為錯(cuò)誤代碼。

注意：2.0及以上版本 TDengine 推薦數(shù)據(jù)庫應(yīng)用的每個(gè)線程都建立一個(gè)獨(dú)立的連接，或基于線程建立連接池。而不推薦在應(yīng)用中將該連接 (TAOS*) 結(jié)構(gòu)體傳遞到不同的線程共享使用。基于 TAOS 結(jié)構(gòu)體發(fā)出的查詢、寫入等操作具有多線程安全性，但 “USE statement” 等狀態(tài)量有可能在線程之間相互干擾。此外，C 語言的連接器可以按照需求動態(tài)建立面向數(shù)據(jù)庫的新連接（該過程對用戶不可見），同時(shí)建議只有在程序最后退出的時(shí)候才調(diào)用 taos_close 關(guān)閉連接。

異步查詢API

同步 API 之外，TDengine 還提供性能更高的異步調(diào)用API處理數(shù)據(jù)插入、查詢操作。在軟硬件環(huán)境相同的情況下，異步 API 處理數(shù)據(jù)插入的速度比同步API快2～4倍。異步 API 采用非阻塞式的調(diào)用方式，在系統(tǒng)真正完成某個(gè)具體數(shù)據(jù)庫操作前，立即返回。調(diào)用的線程可以去處理其他工作，從而可以提升整個(gè)應(yīng)用的性能。異步 API 在網(wǎng)絡(luò)延遲嚴(yán)重的情況下，優(yōu)點(diǎn)尤為突出。

異步 API 都需要應(yīng)用提供相應(yīng)的回調(diào)函數(shù)，回調(diào)函數(shù)參數(shù)設(shè)置如下：前兩個(gè)參數(shù)都是一致的，第三個(gè)參數(shù)依不同的 API 而定。第一個(gè)參數(shù) param 是應(yīng)用調(diào)用異步API時(shí)提供給系統(tǒng)的，用于回調(diào)時(shí)，應(yīng)用能夠找回具體操作的上下文，依具體實(shí)現(xiàn)而定。第二個(gè)參數(shù)是 sql 操作的結(jié)果集，如果為空，比如 insert 操作，表示沒有記錄返回，如果不為空，比如 select 操作，表示有記錄返回。

異步 API 對于使用者的要求相對較高，用戶可根據(jù)具體應(yīng)用場景選擇性使用。下面是兩個(gè)重要的異步 API：

• void taos_query_a(TAOS *taos, const char *sql, void (*fp)(void *param, TAOS_RES *, int code), void *param);

  異步執(zhí)行SQL語句。

  • taos：調(diào)用taos_connect返回的數(shù)據(jù)庫連接
  • sql：需要執(zhí)行的SQL語句
  • fp：用戶定義的回調(diào)函數(shù)，其第三個(gè)參數(shù)code用于指示操作是否成功，0表示成功，負(fù)數(shù)表示失敗(調(diào)用taos_errstr獲取失敗原因)。應(yīng)用在定義回調(diào)函數(shù)的時(shí)候，主要處理第二個(gè)參數(shù)TAOS_RES *，該參數(shù)是查詢返回的結(jié)果集
  • param：應(yīng)用提供一個(gè)用于回調(diào)的參數(shù)

• void taos_fetch_rows_a(TAOS_RES *res, void (*fp)(void *param, TAOS_RES *, int numOfRows), void *param);

  批量獲取異步查詢的結(jié)果集，只能與taos_query_a配合使用。其中：

  • res：taos_query_a回調(diào)時(shí)返回的結(jié)果集
  • fp：回調(diào)函數(shù)。其參數(shù)param是用戶可定義的傳遞給回調(diào)函數(shù)的參數(shù)結(jié)構(gòu)體；numOfRows是獲取到的數(shù)據(jù)的行數(shù)（不是整個(gè)查詢結(jié)果集的函數(shù)）。 在回調(diào)函數(shù)中，應(yīng)用可以通過調(diào)用taos_fetch_row前向迭代獲取批量記錄中每一行記錄。讀完一塊內(nèi)的所有記錄后，應(yīng)用需要在回調(diào)函數(shù)中繼續(xù)調(diào)用taos_fetch_rows_a獲取下一批記錄進(jìn)行處理，直到返回的記錄數(shù)（numOfRows）為零（結(jié)果返回完成）或記錄數(shù)為負(fù)值（查詢出錯(cuò)）。

TDengine 的異步 API 均采用非阻塞調(diào)用模式。應(yīng)用程序可以用多線程同時(shí)打開多張表，并可以同時(shí)對每張打開的表進(jìn)行查詢或者插入操作。需要指出的是，客戶端應(yīng)用必須確保對同一張表的操作完全串行化，即對同一個(gè)表的插入或查詢操作未完成時(shí)（未返回時(shí)），不能夠執(zhí)行第二個(gè)插入或查詢操作。

參數(shù)綁定 API

除了直接調(diào)用 taos_query 進(jìn)行查詢，TDengine 也提供了支持參數(shù)綁定的 Prepare API，與 MySQL 一樣，這些 API 目前也僅支持用問號 ? 來代表待綁定的參數(shù)。文檔中有時(shí)也會把此功能稱為“原生接口寫入”。

從 2.1.1.0 和 2.1.2.0 版本開始，TDengine 大幅改進(jìn)了參數(shù)綁定接口對數(shù)據(jù)寫入（INSERT）場景的支持。這樣在通過參數(shù)綁定接口寫入數(shù)據(jù)時(shí)，就避免了 SQL 語法解析的資源消耗，從而在絕大多數(shù)情況下顯著提升寫入性能。此時(shí)的典型操作步驟如下：

1. 調(diào)用 taos_stmt_init 創(chuàng)建參數(shù)綁定對象；
2. 調(diào)用 taos_stmt_prepare 解析 INSERT 語句；
3. 如果 INSERT 語句中預(yù)留了表名但沒有預(yù)留 TAGS，那么調(diào)用 taos_stmt_set_tbname 來設(shè)置表名；
4. 如果 INSERT 語句中既預(yù)留了表名又預(yù)留了 TAGS（例如 INSERT 語句采取的是自動建表的方式），那么調(diào)用 taos_stmt_set_tbname_tags 來設(shè)置表名和 TAGS 的值；
5. 調(diào)用 taos_stmt_bind_param_batch 以多列的方式設(shè)置 VALUES 的值，或者調(diào)用 taos_stmt_bind_param 以單行的方式設(shè)置 VALUES 的值；
6. 調(diào)用 taos_stmt_add_batch 把當(dāng)前綁定的參數(shù)加入批處理；
7. 可以重復(fù)第 3～6 步，為批處理加入更多的數(shù)據(jù)行；
8. 調(diào)用 taos_stmt_execute 執(zhí)行已經(jīng)準(zhǔn)備好的批處理指令；
9. 執(zhí)行完畢，調(diào)用 taos_stmt_close 釋放所有資源。

說明：如果 taos_stmt_execute 執(zhí)行成功，假如不需要改變 SQL 語句的話，那么是可以復(fù)用 taos_stmt_prepare 的解析結(jié)果，直接進(jìn)行第 3～6 步綁定新數(shù)據(jù)的。但如果執(zhí)行出錯(cuò)，那么并不建議繼續(xù)在當(dāng)前的環(huán)境上下文下繼續(xù)工作，而是建議釋放資源，然后從 taos_stmt_init 步驟重新開始。

除 C/C++ 語言外，TDengine 的 Java 語言 JNI Connector 也提供參數(shù)綁定接口支持，具體請另外參見：參數(shù)綁定接口的 Java 用法。

接口相關(guān)的具體函數(shù)如下（也可以參考 prepare.c 文件中使用對應(yīng)函數(shù)的方式）：

• TAOS_STMT* taos_stmt_init(TAOS *taos)

  創(chuàng)建一個(gè) TAOS_STMT 對象用于后續(xù)調(diào)用。

• int taos_stmt_prepare(TAOS_STMT *stmt, const char *sql, unsigned long length)

  解析一條 SQL 語句，將解析結(jié)果和參數(shù)信息綁定到 stmt 上，如果參數(shù) length 大于 0，將使用此參數(shù)作為 SQL 語句的長度，如等于 0，將自動判斷 SQL 語句的長度。

• int taos_stmt_bind_param(TAOS_STMT *stmt, TAOS_BIND *bind)

  不如 taos_stmt_bind_param_batch 效率高，但可以支持非 INSERT 類型的 SQL 語句。
  進(jìn)行參數(shù)綁定，bind 指向一個(gè)數(shù)組（代表所要綁定的一行數(shù)據(jù)），需保證此數(shù)組中的元素?cái)?shù)量和順序與 SQL 語句中的參數(shù)完全一致。TAOS_BIND 的使用方法與 MySQL 中的 MYSQL_BIND 一致，具體定義如下：

typedef struct TAOS_BIND {
  int            buffer_type;
  void *         buffer;
  unsigned long  buffer_length;  // 未實(shí)際使用
  unsigned long *length;
  int *          is_null;
  int            is_unsigned;    // 未實(shí)際使用
  int *          error;          // 未實(shí)際使用
} TAOS_BIND;

• int taos_stmt_set_tbname(TAOS_STMT* stmt, const char* name)

  （2.1.1.0 版本新增，僅支持用于替換 INSERT 語句中的參數(shù)值）
  當(dāng) SQL 語句中的表名使用了 ? 占位時(shí)，可以使用此函數(shù)綁定一個(gè)具體的表名。

• int taos_stmt_set_tbname_tags(TAOS_STMT* stmt, const char* name, TAOS_BIND* tags)

  （2.1.2.0 版本新增，僅支持用于替換 INSERT 語句中的參數(shù)值）
  當(dāng) SQL 語句中的表名和 TAGS 都使用了 ? 占位時(shí)，可以使用此函數(shù)綁定具體的表名和具體的 TAGS 取值。最典型的使用場景是使用了自動建表功能的 INSERT 語句（目前版本不支持指定具體的 TAGS 列）。tags 參數(shù)中的列數(shù)量需要與 SQL 語句中要求的 TAGS 數(shù)量完全一致。

• int taos_stmt_bind_param_batch(TAOS_STMT* stmt, TAOS_MULTI_BIND* bind)

  （2.1.1.0 版本新增，僅支持用于替換 INSERT 語句中的參數(shù)值）
  以多列的方式傳遞待綁定的數(shù)據(jù)，需要保證這里傳遞的數(shù)據(jù)列的順序、列的數(shù)量與 SQL 語句中的 VALUES 參數(shù)完全一致。TAOS_MULTI_BIND 的具體定義如下：

typedef struct TAOS_MULTI_BIND {
  int          buffer_type;
  void *       buffer;
  uintptr_t    buffer_length;
  int32_t *    length;
  char *       is_null;
  int          num;             // 列的個(gè)數(shù)，即 buffer 中的參數(shù)個(gè)數(shù)
} TAOS_MULTI_BIND;

• int taos_stmt_add_batch(TAOS_STMT *stmt)

  將當(dāng)前綁定的參數(shù)加入批處理中，調(diào)用此函數(shù)后，可以再次調(diào)用 taos_stmt_bind_param 或 taos_stmt_bind_param_batch 綁定新的參數(shù)。需要注意，此函數(shù)僅支持 INSERT/IMPORT 語句，如果是 SELECT 等其他 SQL 語句，將返回錯(cuò)誤。

• int taos_stmt_execute(TAOS_STMT *stmt)

  執(zhí)行準(zhǔn)備好的語句。目前，一條語句只能執(zhí)行一次。

• TAOS_RES* taos_stmt_use_result(TAOS_STMT *stmt)

  獲取語句的結(jié)果集。結(jié)果集的使用方式與非參數(shù)化調(diào)用時(shí)一致，使用完成后，應(yīng)對此結(jié)果集調(diào)用 taos_free_result 以釋放資源。

• int taos_stmt_close(TAOS_STMT *stmt)

  執(zhí)行完畢，釋放所有資源。

• char * taos_stmt_errstr(TAOS_STMT *stmt)

  （2.1.3.0 版本新增）
  用于在其他 stmt API 返回錯(cuò)誤（返回錯(cuò)誤碼或空指針）時(shí)獲取錯(cuò)誤信息。

Schemaless 方式寫入接口

除了使用 SQL 方式或者使用參數(shù)綁定 API 寫入數(shù)據(jù)外，還可以使用 Schemaless 的方式完成寫入。Schemaless 可以免于預(yù)先創(chuàng)建超級表/數(shù)據(jù)子表的數(shù)據(jù)結(jié)構(gòu)，而是可以直接寫入數(shù)據(jù)，TDengine 系統(tǒng)會根據(jù)寫入的數(shù)據(jù)內(nèi)容自動創(chuàng)建和維護(hù)所需要的表結(jié)構(gòu)。Schemaless 的使用方式詳見 Schemaless 寫入 章節(jié)，這里介紹與之配套使用的 C/C++ API。

• TAOS_RES* taos_schemaless_insert(TAOS* taos, const char* lines[], int numLines, int protocol, int precision)

  功能說明
  該接口將行協(xié)議的文本數(shù)據(jù)寫入到 TDengine 中。

  參數(shù)說明
  taos: 數(shù)據(jù)庫連接，通過 taos_connect 函數(shù)建立的數(shù)據(jù)庫連接。
  lines：文本數(shù)據(jù)。滿足解析格式要求的無模式文本字符串。
  numLines:文本數(shù)據(jù)的行數(shù)，不能為 0 。
  protocol: 行協(xié)議類型，用于標(biāo)識文本數(shù)據(jù)格式。
  precision：文本數(shù)據(jù)中的時(shí)間戳精度字符串。

  返回值
  TAOS_RES 結(jié)構(gòu)體，應(yīng)用可以通過使用 taos_errstr 獲得錯(cuò)誤信息，也可以使用 taos_errno 獲得錯(cuò)誤碼。
  在某些情況下，返回的 TAOS_RES 為 NULL，此時(shí)仍然可以調(diào)用 taos_errno 來安全地獲得錯(cuò)誤碼信息。
  返回的 TAOS_RES 需要調(diào)用方來負(fù)責(zé)釋放，否則會出現(xiàn)內(nèi)存泄漏。

  說明
  協(xié)議類型是枚舉類型，包含以下三種格式：
  TSDB_SML_LINE_PROTOCOL：InfluxDB 行協(xié)議（Line Protocol)
  TSDB_SML_TELNET_PROTOCOL: OpenTSDB 文本行協(xié)議
  TSDB_SML_JSON_PROTOCOL: OpenTSDB JSON 協(xié)議格式

  時(shí)間戳分辨率的定義，定義在 taos.h 文件中，具體內(nèi)容如下：
  TSDB_SML_TIMESTAMP_NOT_CONFIGURED = 0,
  TSDB_SML_TIMESTAMP_HOURS,
  TSDB_SML_TIMESTAMP_MINUTES,
  TSDB_SML_TIMESTAMP_SECONDS,
  TSDB_SML_TIMESTAMP_MILLI_SECONDS,
  TSDB_SML_TIMESTAMP_MICRO_SECONDS,
  TSDB_SML_TIMESTAMP_NANO_SECONDS

  需要注意的是，時(shí)間戳分辨率參數(shù)只在協(xié)議類型為 SML_LINE_PROTOCOL 的時(shí)候生效。
  對于 OpenTSDB 的文本協(xié)議，時(shí)間戳的解析遵循其官方解析規(guī)則 — 按照時(shí)間戳包含的字符的數(shù)量來確認(rèn)時(shí)間精度。

  支持版本
  該功能接口從 2.3.0.0 版本開始支持。

#include <stdlib.h>
#include <stdio.h>
#include <taos.h>

int main() {
  const char* host = "127.0.0.1";
  const char* user = "root";
  const char* passwd = "taosdata";

  // connect to server
  TAOS* taos = taos_connect(host, user, passwd, "test", 0);

  // prepare the line string
  char* lines1[] = {
      "stg,t1=3i64,t2=4f64,t3=\"t3\" c1=3i64,c3=L\"passit\",c2=false,c4=4f64 1626006833639000000",
      "stg,t1=4i64,t3=\"t4\",t2=5f64,t4=5f64 c1=3i64,c3=L\"passitagin\",c2=true,c4=5f64,c5=5f64 1626006833641000000"
  };

  // schema-less insert
  TAOS_RES* res = taos_schemaless_insert(taos, lines1, 2, TSDB_SML_LINE_PROTOCOL, TSDB_SML_TIMESTAMP_NANO_SECONDS);
  if (taos_errno(res) != 0) {
    printf("failed to insert schema-less data, reason: %s\n", taos_errstr(res));
  }

  taos_free_result(res);

  // close the connection
  taos_close(taos);
  return (code);
}

數(shù)據(jù)訂閱接口

訂閱 API 目前支持訂閱一張或多張表，并通過定期輪詢的方式不斷獲取寫入表中的最新數(shù)據(jù)。

• TAOS_SUB *taos_subscribe(TAOS* taos, int restart, const char* topic, const char *sql, TAOS_SUBSCRIBE_CALLBACK fp, void *param, int interval)

  該函數(shù)負(fù)責(zé)啟動訂閱服務(wù)，成功時(shí)返回訂閱對象，失敗時(shí)返回 NULL，其參數(shù)為：

  • taos：已經(jīng)建立好的數(shù)據(jù)庫連接
  • restart：如果訂閱已經(jīng)存在，是重新開始，還是繼續(xù)之前的訂閱
  • topic：訂閱的主題（即名稱），此參數(shù)是訂閱的唯一標(biāo)識
  • sql：訂閱的查詢語句，此語句只能是 select 語句，只應(yīng)查詢原始數(shù)據(jù)，只能按時(shí)間正序查詢數(shù)據(jù)
  • fp：收到查詢結(jié)果時(shí)的回調(diào)函數(shù)（稍后介紹函數(shù)原型），只在異步調(diào)用時(shí)使用，同步調(diào)用時(shí)此參數(shù)應(yīng)該傳 NULL
  • param：調(diào)用回調(diào)函數(shù)時(shí)的附加參數(shù)，系統(tǒng)API將其原樣傳遞到回調(diào)函數(shù)，不進(jìn)行任何處理
  • interval：輪詢周期，單位為毫秒。異步調(diào)用時(shí)，將根據(jù)此參數(shù)周期性的調(diào)用回調(diào)函數(shù)，為避免對系統(tǒng)性能造成影響，不建議將此參數(shù)設(shè)置的過?。煌秸{(diào)用時(shí)，如兩次調(diào)用 taos_consume 的間隔小于此周期，API將會阻塞，直到時(shí)間間隔超過此周期。

• typedef void (*TAOS_SUBSCRIBE_CALLBACK)(TAOS_SUB* tsub, TAOS_RES *res, void* param, int code)

  異步模式下，回調(diào)函數(shù)的原型，其參數(shù)為：

  • tsub：訂閱對象
  • res：查詢結(jié)果集，注意結(jié)果集中可能沒有記錄
  • param：調(diào)用 taos_subscribe 時(shí)客戶程序提供的附加參數(shù)
  • code：錯(cuò)誤碼

  注意：在這個(gè)回調(diào)函數(shù)里不可以做耗時(shí)過長的處理，尤其是對于返回的結(jié)果集中數(shù)據(jù)較多的情況，否則有可能導(dǎo)致客戶端阻塞等異常狀態(tài)。如果必須進(jìn)行復(fù)雜計(jì)算，則建議在另外的線程中進(jìn)行處理。

• TAOS_RES *taos_consume(TAOS_SUB *tsub)

  同步模式下，該函數(shù)用來獲取訂閱的結(jié)果。 用戶應(yīng)用程序?qū)⑵渲糜谝粋€(gè)循環(huán)之中。 如兩次調(diào)用 taos_consume() 的間隔小于訂閱的輪詢周期，API將會阻塞，直到時(shí)間間隔超過此周期。 如果數(shù)據(jù)庫有新記錄到達(dá)，該API將返回該最新的記錄，否則返回一個(gè)沒有記錄的空結(jié)果集。 如果返回值為 NULL，說明系統(tǒng)出錯(cuò)。 異步模式下，用戶程序不應(yīng)調(diào)用此 API。

  注意：在調(diào)用 taos_consume() 之后，用戶應(yīng)用應(yīng)確保盡快調(diào)用 taos_fetch_row() 或 taos_fetch_block() 來處理訂閱結(jié)果，否則服務(wù)端會持續(xù)緩存查詢結(jié)果數(shù)據(jù)等待客戶端讀取，極端情況下會導(dǎo)致服務(wù)端內(nèi)存消耗殆盡，影響服務(wù)穩(wěn)定性。

• void taos_unsubscribe(TAOS_SUB *tsub, int keepProgress)

  取消訂閱。 如參數(shù) keepProgress 不為0，API會保留訂閱的進(jìn)度信息，后續(xù)調(diào)用 taos_subscribe() 時(shí)可以基于此進(jìn)度繼續(xù)；否則將刪除進(jìn)度信息，后續(xù)只能重新開始讀取數(shù)據(jù)。

Python Connector

Python 連接器的使用參見視頻教程

• 安裝：參見下面具體步驟
• 示例程序：位于 install_directory/examples/python

安裝

Python 連接器支持的系統(tǒng)有：Linux 64/Windows x64

安裝前準(zhǔn)備：

• 已安裝好 TDengine 應(yīng)用驅(qū)動，請參考安裝連接器驅(qū)動步驟
• 已安裝 Python 2.7 or >= 3.4
• 已安裝 pip

Python連接器安裝

Python 連接器可以通過 pip 從 PyPI 下載安裝。注意 TDengine Python 連接器的包名為 taospy 而不是 taos（這是一個(gè)與 TDengine 無關(guān)的另一個(gè)程序）。但為保持向后兼容性，仍然使用 import taos 導(dǎo)入。

pip install taospy

如果不使用系統(tǒng)默認(rèn)的 python 和 pip，則需要指定 pip 的版本或路徑：

pip2 install taospy
pip3 install taospy

Python 命令行依賴 taos 動態(tài)庫 libtaos.so 或 taos.dll, 對于 Windows 客戶端，安裝TDengine windows 客戶端后，如果不能正常 import taos，可以將 C:\TDengine\driver\taos.dll 拷貝到 C:\windows\system32 目錄后重新嘗試。

對于無法聯(lián)網(wǎng)用戶，可以將TDengine客戶端中的 connector/python 路徑（Linux 下其安裝路徑為 /usr/local/taos/connector/python/，Windows 下默認(rèn)安裝路徑為 C:\TDengine\connector\python）添加到 PYTHONPATH 環(huán)境變量中使用。

示例程序

示例程序源碼位于 <install_directory>/examples/python，有：

• read_example.py Python示例源程序

用戶可以參考 read_example.py 這個(gè)程序來設(shè)計(jì)用戶自己的寫入、查詢程序。

在安裝了對應(yīng)的應(yīng)用驅(qū)動后，通過 import taos 引入 taos 類。主要步驟如下：

• 通過 taos.connect 獲取 TaosConnection對象，這個(gè)對象可以一個(gè)程序只申請一個(gè)，在多線程中共享。

• 通過 TaosConnection 對象的 .cursor() 方法獲取一個(gè)新的游標(biāo)對象，這個(gè)游標(biāo)對象必須保證每個(gè)線程獨(dú)享。

• 通過游標(biāo)對象的 execute()方法，執(zhí)行寫入或查詢的 SQL 語句。

• 如果執(zhí)行的是寫入語句，execute 返回的是成功寫入的行數(shù)信息 affected rows。

• 如果執(zhí)行的是查詢語句，則 execute 執(zhí)行成功后，需要通過 fetchall 方法去拉取結(jié)果集。 具體方法可以參考示例代碼。

安裝驗(yàn)證

運(yùn)行如下指令：

cd {install_directory}/examples/python/PYTHONConnectorChecker/`
python3 PythonChecker.py -host <fqdn>

驗(yàn)證通過將打印出成功信息。

Python 連接器的使用

PEP-249 兼容 API

您可以像其他數(shù)據(jù)庫一樣，使用類似 PEP-249 數(shù)據(jù)庫 API 規(guī)范風(fēng)格的 API：

import taos

conn = taos.connect()
cursor = conn.cursor()

cursor.execute("show databases")
results = cursor.fetchall()
for row in results:
    print(row)

代碼示例

1. 導(dǎo)入 TDengine 客戶端模塊

   import taos

2. 獲取連接并獲取游標(biāo)對象

   conn = taos.connect(host="127.0.0.1", user="root", password="taosdata", config="/etc/taos")
   c1 = conn.cursor()

   host 是 TDengine 服務(wù)端所在IP, config 為客戶端配置文件所在目錄。

3. 寫入數(shù)據(jù)

   import datetime
   
   # 創(chuàng)建數(shù)據(jù)庫
   c1.execute('create database db')
   c1.execute('use db')
   # 建表
   c1.execute('create table tb (ts timestamp, temperature int, humidity float)')
   # 插入數(shù)據(jù)
   start_time = datetime.datetime(2019, 11, 1)
   affected_rows = c1.execute('insert into tb values (\'%s\', 0, 0.0)' %start_time)
   # 批量插入數(shù)據(jù)
   time_interval = datetime.timedelta(seconds=60)
   sqlcmd = ['insert into tb values']
   for irow in range(1,11):
       start_time += time_interval
       sqlcmd.append('(\'%s\', %d, %f)' %(start_time, irow, irow*1.2))
   affected_rows = c1.execute(' '.join(sqlcmd))

4. 查詢數(shù)據(jù)

   c1.execute('select * from tb')
   # 拉取查詢結(jié)果
   data = c1.fetchall()
   # 返回的結(jié)果是一個(gè)列表，每一行構(gòu)成列表的一個(gè)元素
   numOfRows = c1.rowcount
   numOfCols = len(c1.description)
   for irow in range(numOfRows):
       print("Row%d: ts=%s, temperature=%d, humidity=%f" %(irow, data[irow][0], data[irow][1], data[irow][2]))
   
   # 直接使用cursor 循環(huán)拉取查詢結(jié)果
   c1.execute('select * from tb')
   for data in c1:
       print("ts=%s, temperature=%d, humidity=%f" %(data[0], data[1], data[2]))

Query API

從 v2.1.0 版本開始, 我們提供另外一種方法：connection.query 來操作數(shù)據(jù)庫。

import taos

conn = taos.connect()
conn.execute("create database if not exists pytest")

result = conn.query("show databases")
num_of_fields = result.field_count
for field in result.fields:
    print(field)
for row in result:
    print(row)
conn.execute("drop database pytest")

query 方法會返回一個(gè) TaosResult 對象，并提供了以下屬性或方法:

屬性:

• fields: TaosFields 集合類，提供返回?cái)?shù)據(jù)的列信息。
• field_count: 返回?cái)?shù)據(jù)的列數(shù).
• affected_rows: 插入數(shù)據(jù)的行數(shù).
• row_count: 查詢數(shù)據(jù)結(jié)果數(shù).
• precision: 當(dāng)前數(shù)據(jù)庫的時(shí)間精度.

方法:

• fetch_all(): 類似于 cursor.fetchall() 返回同樣的集合數(shù)據(jù)
• fetch_all_into_dict(): v2.1.1 新添加的API，將上面的數(shù)據(jù)轉(zhuǎn)換成字典類型返回
• blocks_iter() rows_iter(): 根據(jù)底層API提供的兩種不同迭代器。
• fetch_rows_a: 異步API
• errno: 錯(cuò)誤碼
• errstr: 錯(cuò)誤信息
• close: 關(guān)閉結(jié)果對象，一般不需要直接調(diào)用

訂閱 API

1. 創(chuàng)建一個(gè)同步訂閱隊(duì)列：

   # 創(chuàng)建一個(gè)主題為 'test' 消費(fèi)周期為1000毫秒的訂閱
   #   第一個(gè)參數(shù)為 True 表示重新開始訂閱，如為 False 且之前創(chuàng)建過主題為 'test' 的訂閱，
   #   則表示繼續(xù)消費(fèi)此訂閱的數(shù)據(jù)，而不是重新開始消費(fèi)所有數(shù)據(jù)
   sub = conn.subscribe(True, "test", "select * from tb;", 1000)

2. 消費(fèi)訂閱的數(shù)據(jù)

   data = sub.consume()
   for d in data:
       print(d)

3. 取消訂閱

   sub.close()

4. 關(guān)閉連接

   conn.close()

JSON 類型

從 taospy v2.2.0 開始，Python 連接器開始支持 JSON 數(shù)據(jù)類型的標(biāo)簽（TDengine版本要求 Beta 版 2.3.5+， 穩(wěn)定版 2.4.0+）。

創(chuàng)建一個(gè)使用JSON類型標(biāo)簽的超級表及其子表：

# encoding:UTF-8
import taos

conn = taos.connect()
conn.execute("create database if not exists py_test_json_type")
conn.execute("use py_test_json_type")

conn.execute("create stable s1 (ts timestamp, v1 int) tags (info json)")
conn.execute("create table s1_1 using s1 tags ('{\"k1\": \"v1\"}')")

查詢子表標(biāo)簽及表名：

tags = conn.query("select info, tbname from s1").fetch_all_into_dict()
tags

tags 內(nèi)容為：

[{'info': '{"k1":"v1"}', 'tbname': 's1_1'}]

獲取 JSON 中某值：

k1 = conn.query("select info->'k1' as k1 from s1").fetch_all_into_dict()
"""
>>> k1
[{'k1': '"v1"'}]
"""

更多 JSON 類型的操作方式請參考 JSON 類型使用說明。

關(guān)于納秒 (nanosecond) 在 Python 連接器中的說明

由于目前 Python 對 nanosecond 支持的不完善(參見鏈接 1. 2. )，目前的實(shí)現(xiàn)方式是在 nanosecond 精度時(shí)返回整數(shù)，而不是 ms 和 us 返回的 datetime 類型，應(yīng)用開發(fā)者需要自行處理，建議使用 pandas 的 to_datetime()。未來如果 Python 正式完整支持了納秒，濤思數(shù)據(jù)可能會修改相關(guān)接口。

1. https://stackoverflow.com/questions/10611328/parsing-datetime-strings-containing-nanoseconds
2. https://www.python.org/dev/peps/pep-0564/

幫助信息

用戶可通過 Python 的幫助信息直接查看模塊的使用信息，或者參考 examples/python 目錄中的示例程序。以下為部分常用類和方法：

• TaosConnection 類

  參考 Python 中 help(taos.TaosConnection)。 這個(gè)類對應(yīng)客戶端和 TDengine 建立的一個(gè)連接。在客戶端多線程的場景下，推薦每個(gè)線程申請一個(gè)獨(dú)立的連接實(shí)例，而不建議多線程共享一個(gè)連接。

• TaosCursor 類

  參考 Python 中 help(taos.TaosCursor)。 這個(gè)類對應(yīng)客戶端進(jìn)行的寫入、查詢操作。在客戶端多線程的場景下，這個(gè)游標(biāo)實(shí)例必須保持線程獨(dú)享，不能跨線程共享使用，否則會導(dǎo)致返回結(jié)果出現(xiàn)錯(cuò)誤。

• connect 方法

  用于生成 taos.TaosConnection 的實(shí)例。

RESTful Connector

為支持各種不同類型平臺的開發(fā)，TDengine 提供符合 REST 設(shè)計(jì)標(biāo)準(zhǔn)的 API，即 RESTful API。為最大程度降低學(xué)習(xí)成本，不同于其他數(shù)據(jù)庫 RESTful API 的設(shè)計(jì)方法，TDengine 直接通過 HTTP POST 請求 BODY 中包含的 SQL 語句來操作數(shù)據(jù)庫，僅需要一個(gè) URL。RESTful 連接器的使用參見視頻教程。

注意：與原生連接器的一個(gè)區(qū)別是，RESTful 接口是無狀態(tài)的，因此 USE db_name 指令沒有效果，所有對表名、超級表名的引用都需要指定數(shù)據(jù)庫名前綴。（從 2.2.0.0 版本開始，支持在 RESTful url 中指定 db_name，這時(shí)如果 SQL 語句中沒有指定數(shù)據(jù)庫名前綴的話，會使用 url 中指定的這個(gè) db_name。從 2.4.0.0 版本開始，RESTful 默認(rèn)有 taosAdapter 提供，要求必須在 url 中指定 db_name。）

安裝

RESTful 接口不依賴于任何 TDengine 的庫，因此客戶端不需要安裝任何 TDengine 的庫，只要客戶端的開發(fā)語言支持 HTTP 協(xié)議即可。

驗(yàn)證

在已經(jīng)安裝 TDengine 服務(wù)器端的情況下，可以按照如下方式進(jìn)行驗(yàn)證。

下面以 Ubuntu 環(huán)境中使用 curl 工具（確認(rèn)已經(jīng)安裝）來驗(yàn)證 RESTful 接口的正常。

下面示例是列出所有的數(shù)據(jù)庫，請把 h1.taosdata.com 和 6041（缺省值）替換為實(shí)際運(yùn)行的 TDengine 服務(wù) fqdn 和端口號：

curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' h1.taosdata.com:6041/rest/sql

返回值結(jié)果如下表示驗(yàn)證通過：

{
  "status": "succ",
  "head": ["name","created_time","ntables","vgroups","replica","quorum","days","keep1,keep2,keep(D)","cache(MB)","blocks","minrows","maxrows","wallevel","fsync","comp","precision","status"],
  "data": [
    ["log","2020-09-02 17:23:00.039",4,1,1,1,10,"30,30,30",1,3,100,4096,1,3000,2,"us","ready"],
    ],
  "rows": 1
}

RESTful 連接器的使用

HTTP 請求格式

http://<fqdn>:<port>/rest/sql/[db_name]

參數(shù)說明：

• fqnd: 集群中的任一臺主機(jī) FQDN 或 IP 地址
• port: 配置文件中 httpPort 配置項(xiàng)，缺省為 6041
• db_name: 可選參數(shù)，指定本次所執(zhí)行的 SQL 語句的默認(rèn)數(shù)據(jù)庫庫名。（從 2.2.0.0 版本開始支持）

例如：http://h1.taos.com:6041/rest/sql/test 是指向地址為 h1.taos.com:6041 的 url，并將默認(rèn)使用的數(shù)據(jù)庫庫名設(shè)置為 test。

HTTP 請求的 Header 里需帶有身份認(rèn)證信息，TDengine 支持 Basic 認(rèn)證與自定義認(rèn)證兩種機(jī)制，后續(xù)版本將提供標(biāo)準(zhǔn)安全的數(shù)字簽名機(jī)制來做身份驗(yàn)證。

• 自定義身份認(rèn)證信息如下所示（稍后介紹）

Authorization: Taosd <TOKEN>

• Basic身份認(rèn)證信息如下所示

Authorization: Basic <TOKEN>

HTTP 請求的 BODY 里就是一個(gè)完整的 SQL 語句，SQL 語句中的數(shù)據(jù)表應(yīng)提供數(shù)據(jù)庫前綴，例如 \.\。如果表名不帶數(shù)據(jù)庫前綴，又沒有在 url 中指定數(shù)據(jù)庫名的話，系統(tǒng)會返回錯(cuò)誤。因?yàn)?HTTP 模塊只是一個(gè)簡單的轉(zhuǎn)發(fā)，沒有當(dāng)前 DB 的概念。

使用 curl 通過自定義身份認(rèn)證方式來發(fā)起一個(gè) HTTP Request，語法如下：

curl -H 'Authorization: Basic <TOKEN>' -d '<SQL>' <ip>:<PORT>/rest/sql/[db_name]

或者

curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql/[db_name]

其中，TOKEN 為 {username}:{password} 經(jīng)過 Base64 編碼之后的字符串，例如 root:taosdata 編碼后為 cm9vdDp0YW9zZGF0YQ==

HTTP 返回格式

返回值為 JSON 格式，如下:

{
    "status": "succ",
    "head": ["ts","current", …],
    "column_meta": [["ts",9,8],["current",6,4], …],
    "data": [
        ["2018-10-03 14:38:05.000", 10.3, …],
        ["2018-10-03 14:38:15.000", 12.6, …]
    ],
    "rows": 2
} 

說明：

• status: 告知操作結(jié)果是成功還是失敗。
• head: 表的定義，如果不返回結(jié)果集，則僅有一列 “affected_rows”。（從 2.0.17.0 版本開始，建議不要依賴 head 返回值來判斷數(shù)據(jù)列類型，而推薦使用 column_meta。在未來版本中，有可能會從返回值中去掉 head 這一項(xiàng)。）
• column_meta: 從 2.0.17.0 版本開始，返回值中增加這一項(xiàng)來說明 data 里每一列的數(shù)據(jù)類型。具體每個(gè)列會用三個(gè)值來說明，分別為：列名、列類型、類型長度。例如["current",6,4]表示列名為“current”；列類型為 6，也即 float 類型；類型長度為 4，也即對應(yīng) 4 個(gè)字節(jié)表示的 float。如果列類型為 binary 或 nchar，則類型長度表示該列最多可以保存的內(nèi)容長度，而不是本次返回值中的具體數(shù)據(jù)長度。當(dāng)列類型是 nchar 的時(shí)候，其類型長度表示可以保存的 unicode 字符數(shù)量，而不是 bytes。
• data: 具體返回的數(shù)據(jù)，一行一行的呈現(xiàn)，如果不返回結(jié)果集，那么就僅有 [[affected_rows]]。data 中每一行的數(shù)據(jù)列順序，與 column_meta 中描述數(shù)據(jù)列的順序完全一致。
• rows: 表明總共多少行數(shù)據(jù)。

column_meta 中的列類型說明：

• 1：BOOL
• 2：TINYINT
• 3：SMALLINT
• 4：INT
• 5：BIGINT
• 6：FLOAT
• 7：DOUBLE
• 8：BINARY
• 9：TIMESTAMP
• 10：NCHAR

自定義授權(quán)碼

HTTP 請求中需要帶有授權(quán)碼 <TOKEN>，用于身份識別。授權(quán)碼通常由管理員提供，可簡單的通過發(fā)送 HTTP GET 請求來獲取授權(quán)碼，操作如下：

curl http://<fqnd>:<port>/rest/login/<username>/<password>

其中，fqdn 是 TDengine 數(shù)據(jù)庫的 fqdn 或 ip 地址，port 是 TDengine 服務(wù)的端口號，username 為數(shù)據(jù)庫用戶名，password 為數(shù)據(jù)庫密碼，返回值為 JSON 格式，各字段含義如下：

• status：請求結(jié)果的標(biāo)志位

• code：返回值代碼

• desc：授權(quán)碼

獲取授權(quán)碼示例：

curl http://192.168.0.1:6041/rest/login/root/taosdata

返回值：

{
  "status": "succ",
  "code": 0,
  "desc": "/KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04"
}

使用示例

• 在 demo 庫里查詢表 d1001 的所有記錄：

curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sql

返回值：

{
    "status": "succ",
    "head": ["ts","current","voltage","phase"],
    "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
    "data": [
        ["2018-10-03 14:38:05.000",10.3,219,0.31],
        ["2018-10-03 14:38:15.000",12.6,218,0.33]
    ],
    "rows": 2
}

• 創(chuàng)建庫 demo：

curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 192.168.0.1:6041/rest/sql

返回值：

{
    "status": "succ",
    "head": ["affected_rows"],
    "column_meta": [["affected_rows",4,4]],
    "data": [[1]],
    "rows": 1
}

其他用法

結(jié)果集采用 Unix 時(shí)間戳

HTTP 請求 URL 采用 sqlt 時(shí)，返回結(jié)果集的時(shí)間戳將采用 Unix 時(shí)間戳格式表示，例如

curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sqlt

返回值：

{
    "status": "succ",
    "head": ["ts","current","voltage","phase"],
    "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
    "data": [
        [1538548685000,10.3,219,0.31],
        [1538548695000,12.6,218,0.33]
    ],
    "rows": 2
}

結(jié)果集采用 UTC 時(shí)間字符串

HTTP 請求 URL 采用 sqlutc 時(shí)，返回結(jié)果集的時(shí)間戳將采用 UTC 時(shí)間字符串表示，例如

  curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6041/rest/sqlutc

返回值：

{
    "status": "succ",
    "head": ["ts","current","voltage","phase"],
    "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
    "data": [
        ["2018-10-03T14:38:05.000+0800",10.3,219,0.31],
        ["2018-10-03T14:38:15.000+0800",12.6,218,0.33]
    ],
    "rows": 2
}

重要配置項(xiàng)

下面僅列出一些與 RESTful 接口有關(guān)的配置參數(shù)，其他系統(tǒng)參數(shù)請看配置文件里的說明。（注意：配置修改后，需要重啟 taosd 服務(wù)才能生效）

• 對外提供 RESTful 服務(wù)的端口號，默認(rèn)綁定到 6041（實(shí)際取值是 serverPort + 11，因此可以通過修改 serverPort 參數(shù)的設(shè)置來修改）。
• httpMaxThreads: 啟動的線程數(shù)量，默認(rèn)為 2（2.0.17.0 版本開始，默認(rèn)值改為 CPU 核數(shù)的一半向下取整）。
• restfulRowLimit: 返回結(jié)果集（JSON 格式）的最大條數(shù)，默認(rèn)值為 10240。
• httpEnableCompress: 是否支持壓縮，默認(rèn)不支持，目前 TDengine 僅支持 gzip 壓縮格式。
• httpDebugFlag: 日志開關(guān)，默認(rèn) 131。131：僅錯(cuò)誤和報(bào)警信息，135：調(diào)試信息，143：非常詳細(xì)的調(diào)試信息，默認(rèn) 131。
• httpDbNameMandatory: 是否必須在 RESTful url 中指定默認(rèn)的數(shù)據(jù)庫名。默認(rèn)為 0，即關(guān)閉此檢查。如果設(shè)置為 1，那么每個(gè) RESTful url 中都必須設(shè)置一個(gè)默認(rèn)數(shù)據(jù)庫名，否則無論此時(shí)執(zhí)行的 SQL 語句是否需要指定數(shù)據(jù)庫，都會返回一個(gè)執(zhí)行錯(cuò)誤，拒絕執(zhí)行此 SQL 語句。

CSharp Connector

• C# 連接器支持的系統(tǒng)有：Linux 64/Windows x64/Windows x86

• C# 連接器現(xiàn)在也支持從Nuget下載引用

• 在 Windows 系統(tǒng)上，C# 應(yīng)用程序可以使用 TDengine 的原生 C 接口來執(zhí)行所有數(shù)據(jù)庫操作，后續(xù)版本將提供 ORM（Dapper）框架驅(qū)動。

安裝準(zhǔn)備

• 應(yīng)用驅(qū)動安裝請參考安裝連接器驅(qū)動步驟。
• 接口文件 TDengineDrivercs.cs 和參考程序示例 TDengineTest.cs 均位于 Windows 客戶端 install_directory/examples/C#目錄下。
• 安裝.NET SDK

示例程序

示例程序源碼位于

• {client_install_directory}/examples/C#
• C# example source code on GitHub

注意: TDengineTest.cs C# 示例源程序，包含了數(shù)據(jù)庫連接參數(shù)，以及如何執(zhí)行數(shù)據(jù)插入、查詢等操作。

安裝驗(yàn)證

需要先安裝 .NET SDK

cd {client_install_directory}/examples/C#/C#Checker
//運(yùn)行測試
dotnet run -- -h <FQDN>. // 此步驟會先build，然后再運(yùn)行。

C#連接器的使用

在 Windows 系統(tǒng)上，C# 應(yīng)用程序可以使用 TDengine 的 C# 連接器接口來執(zhí)行所有數(shù)據(jù)庫的操作。使用的具體步驟如下所示：

• 創(chuàng)建一個(gè) C# project（需要 .NET SDK）.

mkdir test
cd test 
dotnet new console

• 通過 Nuget 引用 TDengineDriver 包

dotnet add package TDengine.Connector

• 在項(xiàng)目中需要用到 TDengineConnector 的地方引用 TDengineDriver namespace。

using TDengineDriver;

• 用戶可以參考TDengineTest.cs來定義數(shù)據(jù)庫連接參數(shù)，以及如何執(zhí)行數(shù)據(jù)插入、查詢等操作。

注意：

• TDengine V2.0.3.0 之后同時(shí)支持 32 位和 64 位 Windows 系統(tǒng)，所以 C# 項(xiàng)目在生成 .exe 文件時(shí)，“解決方案”/“項(xiàng)目”的“平臺”請選擇對應(yīng)的 x86 或 x64。
• 此接口目前已經(jīng)在 Visual Studio 2015/2017 中驗(yàn)證過，其它 Visual Studio 版本尚待驗(yàn)證。
• 此連接器需要用到 taos.dll 文件，所以在未安裝客戶端時(shí)需要在執(zhí)行應(yīng)用程序前，拷貝 Windows{client_install_directory}/driver 目錄中的 taos.dll 文件到項(xiàng)目最后生成 .exe 可執(zhí)行文件所在的文件夾。之后運(yùn)行 exe 文件，即可訪問 TDengine 數(shù)據(jù)庫并做插入、查詢等操作。

第三方驅(qū)動

Maikebing.Data.Taos 是一個(gè) TDengine 的 ADO.NET 提供器，支持 Linux，Windows。該開發(fā)包由熱心貢獻(xiàn)者麥殼餅@@maikebing提供，具體請參考

//接口下載
https://github.com/maikebing/Maikebing.EntityFrameworkCore.Taos   
//用法說明    
http://www.fjzmyy.cn/blog/2020/11/02/1901.html                    

Go Connector

安裝準(zhǔn)備

Go 連接器支持的系統(tǒng)有：

CPU類型	x64（64bit）			aarch64	aarch32
OS類型	Linux	Win64	Win32	Linux	Linux
支持與否	支持	支持	支持	支持	開發(fā)中

安裝前準(zhǔn)備：

• 已安裝好 TDengine 應(yīng)用驅(qū)動，參考安裝連接器驅(qū)動步驟。

示例程序

使用 Go 連接器的示例代碼請參考 https://github.com/taosdata/TDengine/tree/develop/examples/go 以及視頻教程。

示例程序源碼也位于安裝目錄下的 examples/go/taosdemo.go 文件中。

提示：建議 Go 版本是 1.13 及以上，并開啟模塊支持：

go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.io,direct

在 taosdemo.go 所在目錄下進(jìn)行編譯和執(zhí)行：

go mod init taosdemo
go get github.com/taosdata/driver-go/taosSql
# use win branch in Windows platform.
#go get github.com/taosdata/driver-go/taosSql@win
go build
./taosdemo -h fqdn -p serverPort

Go 連接器的使用

TDengine 提供了GO驅(qū)動程序包taosSql。taosSql 實(shí)現(xiàn)了 GO 語言的內(nèi)置接口 database/sql/driver。用戶只需按如下方式引入包就可以在應(yīng)用程序中訪問 TDengine。

import (
  "database/sql"
  _ "github.com/taosdata/driver-go/v2/taosSql"
)

提示：下劃線與雙引號之間必須有一個(gè)空格。

taosSql 的 v2 版本進(jìn)行了重構(gòu)，分離出內(nèi)置數(shù)據(jù)庫操作接口 database/sql/driver 到目錄 taosSql；訂閱、 stmt 等其他功能放到目錄 af。

常用 API

• sql.Open(DRIVER_NAME string, dataSourceName string) *DB

  該 API 用來打開 DB，返回一個(gè)類型為*DB的對象，一般情況下，DRIVER_NAME設(shè)置為字符串 taosSql，dataSourceName 設(shè)置為字符串 user:password@/tcp(host:port)/dbname，如果客戶想要用多個(gè) goroutine 并發(fā)訪問 TDengine, 那么需要在各個(gè) goroutine 中分別創(chuàng)建一個(gè) sql.Open 對象并用之訪問 TDengine。

  注意： 該 API 成功創(chuàng)建的時(shí)候，并沒有做權(quán)限等檢查，只有在真正執(zhí)行 Query 或者 Exec 的時(shí)候才能真正的去創(chuàng)建連接，并同時(shí)檢查 user/password/host/port 是不是合法。另外，由于整個(gè)驅(qū)動程序大部分實(shí)現(xiàn)都下沉到 taosSql 所依賴的 libtaos 動態(tài)庫中。所以，sql.Open 本身特別輕量。

• func (db *DB) Exec(query string, args ...interface{}) (Result, error)

  sql.Open 內(nèi)置的方法，用來執(zhí)行非查詢相關(guān) SQL

• func (db *DB) Query(query string, args ...interface{}) (*Rows, error)

  sql.Open 內(nèi)置的方法，用來執(zhí)行查詢語句

• func (db *DB) Prepare(query string) (*Stmt, error)

  sql.Open 內(nèi)置的方法，Prepare creates a prepared statement for later queries or executions.

• func (s *Stmt) Exec(args ...interface{}) (Result, error)

  sql.Open 內(nèi)置的方法，executes a prepared statement with the given arguments and returns a Result summarizing the effect of the statement.

• func (s *Stmt) Query(args ...interface{}) (*Rows, error)

  sql.Open 內(nèi)置的方法，Query executes a prepared query statement with the given arguments and returns the query results as a *Rows.

• func (s *Stmt) Close() error

  sql.Open 內(nèi)置的方法，Close closes the statement.

其他代碼示例

Consume Messages from Kafka 是一個(gè)通過 Go 語言實(shí)現(xiàn)消費(fèi) Kafka 隊(duì)列寫入 TDengine 的示例程序，也可以作為通過 Go 連接 TDengine 的寫法參考。

Go RESTful的使用

引入

import (
  "database/sql"
  _ "github.com/taosdata/driver-go/v2/taosRestful"
)

go.mod? 的文件 require 塊使用?github.com/taosdata/driver-go/v2 develop?之后執(zhí)行?go mod tidy?

sql.Open?的driverName 為?taosRestful

DSN

格式為：

數(shù)據(jù)庫用戶名:數(shù)據(jù)庫密碼@連接方式(域名或ip:端口)/[數(shù)據(jù)庫][?參數(shù)]

樣例：

root:taosdata@http(localhost:6041)/test?readBufferSize=52428800

參數(shù)：

disableCompression 是否接受壓縮數(shù)據(jù)，默認(rèn)為 true 不接受壓縮數(shù)據(jù)，如果傳輸數(shù)據(jù)使用 gzip 壓縮設(shè)置為 false。

readBufferSize 讀取數(shù)據(jù)的緩存區(qū)大小默認(rèn)為 4K(4096)，當(dāng)查詢結(jié)果數(shù)據(jù)量多時(shí)可以適當(dāng)調(diào)大該值。

使用限制

由于 RESTful 接口無狀態(tài)所以 use db 語法不會生效，需要將 db 名稱放到 SQL 語句中，如：create table if not exists tb1 (ts timestamp, a int)改為create table if not exists test.tb1 (ts timestamp, a int)否則將報(bào)錯(cuò)[0x217] Database not specified or available。

也可以將 db 名稱放到 DSN 中，將 root:taosdata@http(localhost:6041)/ 改為 root:taosdata@http(localhost:6041)/test，此方法在 TDengine 2.4.0.5 版本的 taosAdapter 開始支持。當(dāng)指定的 db 不存在時(shí)執(zhí)行 create database 語句不會報(bào)錯(cuò)，而執(zhí)行針對該 db 的其他查詢或?qū)懭氩僮鲿?bào)錯(cuò)。完整示例如下：

package main

import (
    "database/sql"
    "fmt"
    "time"

    _ "github.com/taosdata/driver-go/v2/taosRestful"
)

func main() {
    var taosDSN = "root:taosdata@http(localhost:6041)/test"
    taos, err := sql.Open("taosRestful", taosDSN)
    if err != nil {
        fmt.Println("failed to connect TDengine, err:", err)
        return
    }
    defer taos.Close()
    taos.Exec("create database if not exists test")
    taos.Exec("create table if not exists tb1 (ts timestamp, a int)")
    _, err = taos.Exec("insert into tb1 values(now, 0)(now+1s,1)(now+2s,2)(now+3s,3)")
    if err != nil {
        fmt.Println("failed to insert, err:", err)
        return
    }
    rows, err := taos.Query("select * from tb1")
    if err != nil {
        fmt.Println("failed to select from table, err:", err)
        return
    }

    defer rows.Close()
    for rows.Next() {
        var r struct {
            ts time.Time
            a  int
        }
        err := rows.Scan(&r.ts, &r.a)
        if err != nil {
            fmt.Println("scan error:\n", err)
            return
        }
        fmt.Println(r.ts, r.a)
    }
}

常見問題

• 無法找到包github.com/taosdata/driver-go/v2/taosRestful

  將 go.mod 中 require 塊對github.com/taosdata/driver-go/v2的引用改為github.com/taosdata/driver-go/v2 develop，之后執(zhí)行 go mod tidy。

• stmt 相關(guān)接口崩潰

  RESTful 不支持 stmt 相關(guān)接口，建議使用db.Exec和db.Query。

• 使用 use db 語句后執(zhí)行其他語句報(bào)錯(cuò) [0x217] Database not specified or available

  在 RESTful 接口中 SQL 語句的執(zhí)行無上下文關(guān)聯(lián)，使用 use db 語句不會生效，解決辦法見上方使用限制章節(jié)。

• 使用 taosSql 不報(bào)錯(cuò)使用 taosRestful 報(bào)錯(cuò) [0x217] Database not specified or available

  因?yàn)?RESTful 接口無狀態(tài)，使用 use db 語句不會生效，解決辦法見上方使用限制章節(jié)。

• 升級 github.com/taosdata/driver-go/v2/taosRestful

  將 go.mod 文件中對 github.com/taosdata/driver-go/v2 的引用改為 github.com/taosdata/driver-go/v2 develop，之后執(zhí)行 go mod tidy。

• readBufferSize 參數(shù)調(diào)大后無明顯效果

  readBufferSize 調(diào)大后會減少獲取結(jié)果時(shí) syscall 的調(diào)用。如果查詢結(jié)果的數(shù)據(jù)量不大，修改該參數(shù)不會帶來明顯提升，如果該參數(shù)修改過大，瓶頸會在解析 JSON 數(shù)據(jù)。如果需要優(yōu)化查詢速度，需要根據(jù)實(shí)際情況調(diào)整該值來達(dá)到查詢效果最優(yōu)。

• disableCompression 參數(shù)設(shè)置為 false 時(shí)查詢效率降低

  當(dāng) disableCompression 參數(shù)設(shè)置為 false 時(shí)查詢結(jié)果會 gzip 壓縮后傳輸，拿到數(shù)據(jù)后要先進(jìn)行 gzip 解壓。

Node.js Connector

Node.js 連接器支持的系統(tǒng)有：

CPU類型	x64（64bit）			aarch64	aarch32
OS類型	Linux	Win64	Win32	Linux	Linux
支持與否	支持	支持	支持	支持	支持

Node.js 連接器的使用參見視頻教程。

安裝準(zhǔn)備

• 應(yīng)用驅(qū)動安裝請參考安裝連接器驅(qū)動步驟。

安裝Node.js連接器

用戶可以通過 npm 來進(jìn)行安裝，也可以通過源代碼 src/connector/nodejs/ 來進(jìn)行安裝。具體安裝步驟如下：

首先，通過 npm 安裝 Node.js 連接器。

npm install td2.0-connector

我們建議用戶使用 npm 安裝 Node.js 連接器。如果您沒有安裝 npm，可以將 src/connector/nodejs/ 拷貝到您的 Node.js 項(xiàng)目目錄下。

我們使用 node-gyp 和 TDengine 服務(wù)端進(jìn)行交互。安裝 Node.js 連接器之前，還需要根據(jù)具體操作系統(tǒng)來安裝下文提到的一些依賴工具。

Linux

• python (建議v2.7 , v3.x.x 目前還不支持)
• node 2.0.6支持v12.x和v10.x，2.0.5及更早版本支持v10.x版本，其他版本可能存在包兼容性的問題。
• make
• C 語言編譯器比如 GCC

Windows

安裝方法1

使用微軟的 windows-build-tools 在 cmd 命令行界面執(zhí)行 npm install --global --production windows-build-tools 即可安裝所有的必備工具。

安裝方法2

手動安裝以下工具：

• 安裝 Visual Studio 相關(guān)：Visual Studio Build 工具 或者 Visual Studio 2017 Community
• 安裝 Python 2.7(v3.x.x 暫不支持) 并執(zhí)行 npm config set python python2.7
• 進(jìn)入cmd命令行界面，npm config set msvs_version 2017

如果以上步驟不能成功執(zhí)行，可以參考微軟的 Node.js 用戶手冊 。

如果在 Windows 10 ARM 上使用 ARM64 Node.js，還需添加 "Visual C++ compilers and libraries for ARM64" 和 "Visual C++ ATL for ARM64"。

示例程序

示例程序源碼位于 install_directory/examples/nodejs，有：

Node-example.js Node.js示例源程序 Node-example-raw.js

安裝驗(yàn)證

在安裝好 TDengine 客戶端后，使用 nodejsChecker.js 程序能夠驗(yàn)證當(dāng)前環(huán)境是否支持 Node.js 方式訪問 TDengine。

驗(yàn)證方法：

1. 新建安裝驗(yàn)證目錄，例如：~/tdengine-test，拷貝 GitHub 上 nodejsChecker.js 源程序。下載地址：https://github.com/taosdata/TDengine/tree/develop/examples/nodejs/nodejsChecker.js。

2. 在命令行中執(zhí)行以下命令：

npm init -y
npm install td2.0-connector
node nodejsChecker.js host=localhost

3. 執(zhí)行以上步驟后，在命令行會輸出 Node.js 連接 TDengine 實(shí)例，并執(zhí)行簡答插入和查詢的結(jié)果。

Node.js連接器的使用

以下是 Node.js 連接器的一些基本使用方法，詳細(xì)的使用方法可參考TDengine Node.js connector。

建立連接

使用 Node.js 連接器時(shí)，必須先 require td2.0-connector，然后使用 taos.connect 函數(shù)建立到服務(wù)端的連接。例如如下代碼：

const taos = require('td2.0-connector');
var conn = taos.connect({host:"taosdemo.com", user:"root", password:"taosdata", config:"/etc/taos",port:6030})
var cursor = conn.cursor(); // Initializing a new cursor

建立了一個(gè)到 hostname 為 taosdemo.com，端口為 6030（TDengine的默認(rèn)端口號）的連接。連接指定了用戶名（root）和密碼（taosdata）。taos.connect 函數(shù)必須提供的參數(shù)是host，其它參數(shù)在沒有提供的情況下會使用如下的默認(rèn)值。taos.connect 返回了 cursor 對象，使用 cursor 來執(zhí)行 SQL 語句。

執(zhí)行 SQL 和插入數(shù)據(jù)

對于 DDL 語句（例如create database、create table、use等），可以使用 cursor 的 execute 方法。代碼如下：

cursor.execute('create database if not exists test;')

以上代碼創(chuàng)建了一個(gè)名稱為 test 的數(shù)據(jù)庫。對于 DDL 語句，一般沒有返回值，cursor 的 execute 返回值為 0。

對于 Insert 語句，代碼如下：

var affectRows = cursor.execute('insert into test.weather values(now, 22.3, 34);')

execute 方法的返回值為該語句影響的行數(shù)，上面的 SQL 向 test 庫的 weather 表中，插入了一條數(shù)據(jù)，則返回值 affectRows 為 1。

TDengine 目前還不支持 delete 語句。但從 2.0.8.0 版本開始，可以通過 CREATE DATABASE 時(shí)指定的 UPDATE 參數(shù)來啟用對數(shù)據(jù)行的 update。

查詢

可通過 cursor.query 函數(shù)來查詢數(shù)據(jù)庫。

var query = cursor.query('show databases;')

查詢的結(jié)果可以通過 query.execute() 函數(shù)獲取并打印出來。

var promise = query.execute();
promise.then(function(result) {
  result.pretty(); 
});

格式化查詢語句還可以使用query的bind方法。如下面的示例：query會自動將提供的數(shù)值填入查詢語句的?里。

var query = cursor.query('select * from meterinfo.meters where ts <= ? and areaid = ?;').bind(new Date(), 5);
query.execute().then(function(result) {
  result.pretty();
})

如果在query語句里提供第二個(gè)參數(shù)并設(shè)為true也可以立即獲取查詢結(jié)果。如下：

var promise = cursor.query('select * from meterinfo.meters where v1 = 30;', true)
promise.then(function(result) {
  result.pretty();
})

關(guān)閉連接

在完成插入、查詢等操作后，要關(guān)閉連接。代碼如下：

conn.close();

異步函數(shù)

異步查詢數(shù)據(jù)庫的操作和上面類似，只需要在cursor.execute, TaosQuery.execute等函數(shù)后面加上_a。

var promise1 = cursor.query('select count(*), avg(v1), avg(v2) from meter1;').execute_a()
var promise2 = cursor.query('select count(*), avg(v1), avg(v2) from meter2;').execute_a();
promise1.then(function(result) {
  result.pretty();
})
promise2.then(function(result) {
  result.pretty();
})

示例

node-example.js 提供了一個(gè)使用 Node.js 連接器建表，插入天氣數(shù)據(jù)并查詢插入的數(shù)據(jù)的代碼示例。

node-example-raw.js 同樣是一個(gè)使用 Node.js 連接器建表，插入天氣數(shù)據(jù)并查詢插入的數(shù)據(jù)的代碼示例，但和上面不同的是，該示例只使用 cursor。