連接器

TDengine 提供了豐富的應用(yong)程序開(kai)發(fa)(fa)接(jie)口，其(qi)中(zhong)包括(kuo) C/C++、Java、Python、Go、Node.js、C# 、RESTful 等(deng)，便于用(yong)戶快速開(kai)發(fa)(fa)應用(yong)。

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

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	●	●	●	●	●	●	○	○	○

其中(zhong) ● 表示(shi)官(guan)方測試驗(yan)證通(tong)過(guo)，○ 表示(shi)非官(guan)方測試驗(yan)證通(tong)過(guo)，-- 表示(shi)未(wei)經驗(yan)證。

注意：

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

安裝連接器驅動步驟

服務器應該已(yi)經安(an)裝(zhuang) TDengine 服務端(duan)安(an)裝(zhuang)包(bao)。連接器驅動安(an)裝(zhuang)步驟(zou)如(ru)下(xia)：

Linux

1. 從濤思官網下載：

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

• ARM64 硬件環境：TDengine-client-2.x.x.x-Linux-aarch64.tar.gz

• ARM32 硬件環境：TDengine-client-2.x.x.x-Linux-aarch32.tar.gz

2. 解壓縮軟件包

將軟件包放(fang)置在(zai)當前用戶可(ke)讀寫的任意目錄下，然后執行(xing)下面的命令：

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

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

3. 執行安裝腳本

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

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

運(yun)行install_client.sh進行安裝。

4. 配置taos.cfg

編輯(ji) taos.cfg 文(wen)件(jian)（默認(ren)路徑/etc/taos/taos.cfg），將 firstEP 修(xiu)改(gai)為 TDengine 服務(wu)器的 End Point，例如：h1.taos.com:6030

提示：

1. 如本機沒有部署 TDengine 服務，僅安裝了應用驅動，則 taos.cfg 中僅需配置 firstEP，無需配置 FQDN。
2. 為防止與服務器端連接時出現 “unable to resolve FQDN” 錯誤，建議確認客戶端的 hosts 文件已經配置正確的 FQDN 值。

Windows x64/x86

1. 從濤思官網下載：

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

• X86硬件環境：TDengine-client-2.X.X.X-Windows-x86.exe

2. 執行安裝程序，按提示選擇默認值，完成安裝

3. 安裝路徑

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

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

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

4. 配置taos.cfg

編輯 taos.cfg 文(wen)件(默(mo)認路(lu)徑C:\TDengine\cfg\taos.cfg)，將(jiang) firstEP 修改為 TDengine 服務器的 End Point，例如：h1.taos.com:6030

提示：

1. 如利用 FQDN 連接服務器，必須確認本機網絡環境DNS已配置好，或在 hosts 文件中添加 FQDN 尋址記錄，如編輯C:\Windows\system32\drivers\etc\hosts，添加如下的記錄：192.168.1.99 h1.taos.com
2. 卸載：運行unins000.exe可卸載TDengine應用驅動。

安裝驗證

以(yi)上安裝(zhuang)和配(pei)置完成(cheng)后，并確認 TDengine 服務已經正常啟動運(yun)行(xing)，此時可以(yi)執行(xing) taos 客(ke)戶端進行(xing)登錄(lu)。

Linux環境：

在 Linux shell 下直接(jie)執行 taos，應該就能正常連接(jie)到(dao)(dao) TDengine 服(fu)務，進入到(dao)(dao) taos shell 界面，示例如(ru)下：

$ 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）環境：

在 cmd 下進入到 C:\TDengine 目錄下直接(jie)執(zhi)行 taos.exe，應該就能(neng)正常鏈接(jie)到 TDengine 服務，進入到 taos shell 界(jie)面，示例(li)如下：

  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++連接器支持的系統有：

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

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

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

#include <taos.h>

注意：

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

示例程序

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

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

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

該目錄下有 makefile，在 Linux 環境下，直接執行 make 就可以編譯(yi)得到(dao)執行文件(jian)。

在一臺機器(qi)上啟動(dong) TDengine 服(fu)務，執(zhi)行這(zhe)些示(shi)例(li)程(cheng)序，按照提示(shi)輸入 TDengine 服(fu)務的(de) FQDN，就可以正(zheng)常運行，并打(da)印出信息。

提示：在 ARM 環境下編譯時，請將 makefile 中的 -msse4.2 打開，這個選項只有在(zai) x64/x86 硬(ying)件平臺上才能支持。

基礎API

基礎 API 用于完成創建數據(ju)庫連接等工(gong)作，為其它 API 的執(zhi)行(xing)(xing)提供運(yun)行(xing)(xing)時環境。

• void taos_init()

  初始化運行環境。如果應用沒有主動調用該 API，那么應用在調用 taos_connect() 時(shi)將自動(dong)調用，故(gu)應用程序(xu)一般(ban)無需手(shou)動(dong)調用該 API。

• void taos_cleanup()

  清理(li)運行(xing)環境，應(ying)用(yong)退出(chu)前應(ying)調用(yong)此 API。

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

  設置客戶端選項，目前支持區域設置（TSDB_OPTION_LOCALE）、字符集設置（TSDB_OPTION_CHARSET）、時區設置（TSDB_OPTION_TIMEZONE）、配置文件路徑設置（TSDB_OPTION_CONFIGDIR）。區域(yu)設(she)置(zhi)、字符集、時區默(mo)認為(wei)操(cao)作系統當(dang)前設(she)置(zhi)。

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

• char *taos_get_client_info()

  獲取客戶端版本(ben)信息。

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

  創建數(shu)據(ju)庫連(lian)(lian)接，初始化連(lian)(lian)接上下文(wen)。其中需要用戶(hu)提供的參數(shu)包含：

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

  返回值為空表示失(shi)敗。應用(yong)程序需要保存返回的參數，以(yi)便后續(xu) API 調用(yong)。

  提示: 同一(yi)進程可(ke)以根(gen)據(ju)不同的 host/port 連接多個(ge) taosd 集(ji)群

• char *taos_get_server_info(TAOS *taos)

  獲取服務端版本信息。

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

  將當前的缺省數據庫設置為db。

  返回值為錯誤碼。

• void taos_close(TAOS *taos)

  關閉連接，其中taos是taos_connect函數返回的指針。

同步查詢API

傳統(tong)的數據庫操(cao)(cao)作(zuo) API，都屬于(yu)同步操(cao)(cao)作(zuo)。應用調用 API 后，一直處于(yu)阻塞狀(zhuang)態(tai)，直到服(fu)務器返(fan)回結(jie)果。TDengine 支持如下 API：

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

  該API用來執行 SQL 語句，可以是 DQL、DML 或 DDL 語句。 其中的 taos 參數是通過 taos_connect 獲得的指針。不能通過返回值是否是 NULL 來判斷執行結果是否失敗，而是需要用 taos_errno 函(han)數解(jie)析結(jie)果集(ji)中的錯(cuo)誤代碼來(lai)進行(xing)判斷(duan)。

• int taos_result_precision(TAOS_RES *res)

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

• TAOS_ROW taos_fetch_row(TAOS_RES *res)

  按行獲取查(cha)詢結果集中的數據。

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

  批量獲取(qu)查詢結(jie)果(guo)集中的數據，返回值為獲取(qu)到的數據的行數。

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

  這兩個(ge)API等價，用于獲取查(cha)詢(xun)結(jie)果(guo)集中的列(lie)數(shu)。

• int* taos_fetch_lengths(TAOS_RES *res)

  獲(huo)取結果集(ji)中(zhong)每個字段的(de)長(chang)度。 返回值是一個數組(zu)，其長(chang)度為結果集(ji)的(de)列數。

• int taos_affected_rows(TAOS_RES *res)

  獲取被所執行的 SQL 語句影響的行數。

• TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)

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

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

• void taos_stop_query(TAOS_RES *res)

  停止一個查詢的執(zhi)行。

• void taos_free_result(TAOS_RES *res)

  釋放查詢結果集以及相關的資源。查詢完成后，務必調用該 API 釋放資源，否則可能導致應用內存泄露。但也需注意，釋放資源后，如果再調用 taos_consume 等獲取查(cha)詢(xun)結果的函數，將(jiang)導致應(ying)用(yong) Crash。

• char *taos_errstr(TAOS_RES *res)

  獲取最近一次API調(diao)用失敗(bai)的(de)原因,返回(hui)值(zhi)為字符(fu)串。

• int taos_errno(TAOS_RES *res)

  獲取最近一次API調用失敗的原因，返回值(zhi)為(wei)錯誤代碼。

注意：2.0及以(yi)上版本 TDengine 推薦(jian)數據庫應(ying)用(yong)的(de)(de)(de)每個(ge)線程(cheng)(cheng)都建(jian)(jian)立(li)(li)一個(ge)獨立(li)(li)的(de)(de)(de)連接(jie)，或基于線程(cheng)(cheng)建(jian)(jian)立(li)(li)連接(jie)池。而不推薦(jian)在(zai)應(ying)用(yong)中(zhong)將該連接(jie) (TAOS*) 結(jie)構(gou)體傳遞(di)到不同(tong)的(de)(de)(de)線程(cheng)(cheng)共享使用(yong)。基于 TAOS 結(jie)構(gou)體發出的(de)(de)(de)查詢、寫入等操作具有多線程(cheng)(cheng)安(an)全性，但 “USE statement” 等狀(zhuang)態(tai)量有可(ke)能在(zai)線程(cheng)(cheng)之間相(xiang)互干擾。此外，C 語(yu)言的(de)(de)(de)連接(jie)器可(ke)以(yi)按(an)照(zhao)需求動態(tai)建(jian)(jian)立(li)(li)面向(xiang)數據庫的(de)(de)(de)新(xin)連接(jie)（該過程(cheng)(cheng)對用(yong)戶不可(ke)見），同(tong)時建(jian)(jian)議只(zhi)有在(zai)程(cheng)(cheng)序最后退出的(de)(de)(de)時候才調用(yong) taos_close 關閉連接(jie)。

異步查詢API

同步 API 之外，TDengine 還提供性(xing)能更高的(de)(de)異(yi)步調(diao)用(yong)(yong)(yong)API處(chu)理數據插(cha)入(ru)、查(cha)詢操作。在軟硬件環境相(xiang)同的(de)(de)情況下，異(yi)步 API 處(chu)理數據插(cha)入(ru)的(de)(de)速度比同步API快(kuai)2～4倍。異(yi)步 API 采用(yong)(yong)(yong)非阻塞式(shi)的(de)(de)調(diao)用(yong)(yong)(yong)方(fang)式(shi)，在系統真正完成(cheng)某個(ge)具體數據庫操作前，立即返(fan)回。調(diao)用(yong)(yong)(yong)的(de)(de)線程(cheng)可以去處(chu)理其他工作，從而可以提升整個(ge)應用(yong)(yong)(yong)的(de)(de)性(xing)能。異(yi)步 API 在網(wang)絡延遲嚴重的(de)(de)情況下，優點(dian)尤為突出。

異步 API 都需要應用提供相應的回調函數，回調函數參數設置如下：前兩個參數都是一致的，第三個參數依不同的 API 而定。第一個參數 param 是應用調用異步API時提供給系統的，用于回調時，應用能夠找回具體操作的上下文，依具體實現而定。第二個參數是 sql 操作的結果集，如果為(wei)空，比(bi)如 insert 操作，表(biao)示沒(mei)有記(ji)錄返回(hui)，如果不為(wei)空，比(bi)如 select 操作，表(biao)示有記(ji)錄返回(hui)。

異步 API 對(dui)于使(shi)用(yong)(yong)者的(de)要求(qiu)相(xiang)對(dui)較高，用(yong)(yong)戶可根據具體應(ying)用(yong)(yong)場景(jing)選擇性使(shi)用(yong)(yong)。下面(mian)是兩(liang)個(ge)重要的(de)異步 API：

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

  異步執行SQL語句(ju)。

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

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

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

  • res：taos_query_a回調時返回的結果集
  • fp：回調函數。其參數param是用戶可定義的傳遞給回調函數的參數結構體；numOfRows是獲取到的數據的行數（不是整個查詢結果集的函數）。 在回調函數中，應用可以通過調用taos_fetch_row前向迭代獲取批量記錄中每一行記錄。讀完一塊內的所有記錄后，應用需要在回調函數中繼續調用taos_fetch_rows_a獲取下一批記錄進行處理，直到返回的記錄數（numOfRows）為零（結果返回完成）或記錄數為負值（查詢出錯）。

TDengine 的異步 API 均采用非阻塞調用模式。應用程序可以用多線程同時打開多張表，并可以同時對每張打開的表進行查詢或者插入操作。需要指出的是，客戶端應用必須確保對同一張表的操作完全串行化，即對(dui)同(tong)一個表(biao)的插入(ru)(ru)或查詢操作未(wei)完成(cheng)時（未(wei)返回時），不(bu)能夠執行(xing)第(di)二個插入(ru)(ru)或查詢操作。

參數綁定 API

除了直接調用 taos_query 進行查詢，TDengine 也提供了支持參數綁定的 Prepare API，與 MySQL 一樣，這些 API 目前也僅支持用問號 ? 來代表待綁(bang)定的參數(shu)。文(wen)檔中有時也會把此功能稱(cheng)為“原生(sheng)接口(kou)寫入(ru)”。

從(cong) 2.1.1.0 和 2.1.2.0 版本開始，TDengine 大幅改進了(le)參數綁(bang)定接口對數據寫(xie)(xie)入（INSERT）場景的支持。這樣在(zai)(zai)通(tong)過參數綁(bang)定接口寫(xie)(xie)入數據時，就避免了(le) SQL 語法解析的資源(yuan)消耗(hao)，從(cong)而在(zai)(zai)絕(jue)大多數情況下(xia)顯著提升寫(xie)(xie)入性能(neng)。此時的典型(xing)操作(zuo)步驟如下(xia)：

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

說明：如果 taos_stmt_execute 執行成功，假如不需要改變 SQL 語句的話，那么是可以復用 taos_stmt_prepare 的解析結果，直接進行第 3～6 步綁定新數據的。但如果執行出錯，那么并不建議繼續在當前的環境上下文下繼續工作，而是建議釋放資源，然后從 taos_stmt_init 步驟重新開始。

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

接口相關(guan)的具體函數(shu)如(ru)下（也(ye)可以(yi)參考 文件中使用對應函數(shu)的方式）：

• TAOS_STMT* taos_stmt_init(TAOS *taos)

  創建一個 TAOS_STMT 對象用(yong)于(yu)后(hou)續調用(yong)。

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

  解析一條 SQL 語句，將(jiang)解析結果和參(can)數(shu)信息綁(bang)定(ding)到 stmt 上，如(ru)果參(can)數(shu) length 大于 0，將(jiang)使用此參(can)數(shu)作(zuo)為 SQL 語句的長度(du)，如(ru)等于 0，將(jiang)自動判斷(duan) SQL 語句的長度(du)。

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

  不如 taos_stmt_bind_param_batch 效率高，但可以支持非 INSERT 類型的 SQL 語句。
  進行參(can)數(shu)(shu)綁定，bind 指向(xiang)一個數(shu)(shu)組（代(dai)表所要綁定的(de)一行數(shu)(shu)據），需保證(zheng)此數(shu)(shu)組中(zhong)(zhong)的(de)元(yuan)素(su)數(shu)(shu)量和順序與 SQL 語句中(zhong)(zhong)的(de)參(can)數(shu)(shu)完(wan)全一致。TAOS_BIND 的(de)使用(yong)方法(fa)與 MySQL 中(zhong)(zhong)的(de) MYSQL_BIND 一致，具體定義如下：

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

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

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

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

  （2.1.2.0 版本新增，僅支持用于替換 INSERT 語句中的參數值）
  當 SQL 語句中的表名和 TAGS 都使用了 ? 占位時，可以使用(yong)此函數(shu)綁定(ding)具體(ti)的(de)(de)表(biao)名和具體(ti)的(de)(de) TAGS 取值。最典型的(de)(de)使用(yong)場景(jing)是使用(yong)了(le)自動建表(biao)功(gong)能(neng)的(de)(de) INSERT 語句（目前版(ban)本不支(zhi)持指(zhi)定(ding)具體(ti)的(de)(de) TAGS 列(lie)）。tags 參數(shu)中的(de)(de)列(lie)數(shu)量需要與 SQL 語句中要求的(de)(de) TAGS 數(shu)量完(wan)全一致。

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

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

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

• int taos_stmt_add_batch(TAOS_STMT *stmt)

  將當前綁定的參數加入批處理中，調用此函數后，可以再次調用 taos_stmt_bind_param 或 taos_stmt_bind_param_batch 綁定新的參數(shu)。需(xu)要注意，此函數(shu)僅(jin)支持 INSERT/IMPORT 語(yu)句，如果是 SELECT 等(deng)其(qi)他(ta) SQL 語(yu)句，將返(fan)回錯誤。

• int taos_stmt_execute(TAOS_STMT *stmt)

  執(zhi)行準備好的語句。目前，一條(tiao)語句只能(neng)執(zhi)行一次。

• TAOS_RES* taos_stmt_use_result(TAOS_STMT *stmt)

  獲取語句的結果集。結果集的使用方式與非參數化調用時一致，使用完成后，應對此結果集調用 taos_free_result 以釋放資源。

• int taos_stmt_close(TAOS_STMT *stmt)

  執行完畢，釋放所有資源。

• char * taos_stmt_errstr(TAOS_STMT *stmt)

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

Schemaless 方式寫入接口

除了使用 SQL 方式或者使用參數綁定 API 寫入數據外，還可以使用 Schemaless 的方式完成寫入。Schemaless 可以免于預先創建超級表/數據子表的數據結構，而是可以直接寫入數據，TDengine 系統會根據寫入的數據內容自動創建和維護所需要的表結構。Schemaless 的使用方式詳見 Schemaless 寫入 章節，這里(li)介紹(shao)與之配套使用的 C/C++ API。

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

  功能說明
  該接口將行(xing)協(xie)議(yi)的文(wen)本數據寫入到 TDengine 中。

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

  返回值
  TAOS_RES 結構體，應用可以通過使用 taos_errstr 獲得錯誤信息，也可以使用 taos_errno 獲得錯誤碼。
  在某些情況下，返回的 TAOS_RES 為 NULL，此時仍然可以調用 taos_errno 來安全地獲得錯誤碼信息。
  返回的 TAOS_RES 需(xu)要調(diao)用方來負(fu)責釋放，否(fou)則會出現內(nei)存泄漏。

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

  時間戳分辨率的定義，定義在 taos.h 文件中，具體內容如下：
  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

  需要注意的是，時間戳分辨率參數只在協議類型為 SML_LINE_PROTOCOL 的時候生效。
  對于(yu) OpenTSDB 的文本協議(yi)，時間(jian)戳的解析(xi)遵循其官方(fang)解析(xi)規則 — 按(an)照時間(jian)戳包含的字符(fu)的數量(liang)來確認時間(jian)精度(du)。

  支持版本
  該功能接(jie)口從 2.3.0.0 版本開始(shi)支持。

#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);
}

數據訂閱接口

訂閱 API 目(mu)前支持訂閱一張或多(duo)張表，并通過定期(qi)輪詢(xun)的(de)(de)方式(shi)不斷(duan)獲取寫入(ru)表中(zhong)的(de)(de)最新數據。

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

  該函數負責啟動訂閱服務，成功時返回訂閱對象，失敗時返回 NULL，其參數為：

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

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

  異步(bu)模式(shi)下，回調函(han)數的(de)原型，其參(can)數為：

  • tsub：訂閱對象
  • res：查詢結果集，注意結果集中可能沒有記錄
  • param：調用 taos_subscribe 時客戶程序提供的附加參數
  • code：錯誤碼

  注意：在這個回調函數里不可以(yi)做(zuo)耗時過長(chang)的(de)處理，尤其是對于(yu)返(fan)回的(de)結果(guo)(guo)集中數據較多的(de)情(qing)況，否(fou)則有可能導致客戶(hu)端阻塞(sai)等(deng)異常狀態。如果(guo)(guo)必須進行(xing)復雜(za)計算，則建議在另外的(de)線程中進行(xing)處理。

• TAOS_RES *taos_consume(TAOS_SUB *tsub)

  同步模式下，該函數用來獲取訂閱的結果。 用戶應用程序將其置于一個循環之中。 如兩次調用 taos_consume() 的間隔小于訂閱的輪詢周期，API將會阻塞，直到時間間隔超過此周期。 如果數據庫有新記錄到達，該API將返回該最新的記錄，否則返回一個沒有記錄的空結果集。 如果返回值為 NULL，說明(ming)系統(tong)出錯。 異步模式下，用(yong)戶程序(xu)不應調用(yong)此(ci) API。

  注意：在調用 taos_consume() 之后，用戶應用應確保盡快調用 taos_fetch_row() 或 taos_fetch_block() 來處(chu)理訂(ding)閱結果(guo)，否則服務(wu)(wu)端(duan)會(hui)(hui)持續緩(huan)存查詢結果(guo)數(shu)據等待客戶(hu)端(duan)讀取，極端(duan)情況下會(hui)(hui)導致服務(wu)(wu)端(duan)內存消耗殆盡，影(ying)響服務(wu)(wu)穩定性。

• void taos_unsubscribe(TAOS_SUB *tsub, int keepProgress)

  取消訂閱。 如參數 keepProgress 不為0，API會保留訂閱的進度信息，后續調用 taos_subscribe() 時可以基(ji)于此進度繼續；否(fou)則將刪(shan)除進度信息，后續只能重新開始(shi)讀取數據。

Python Connector

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

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

安裝

Python 連(lian)接器(qi)支持的系統(tong)有：Linux 64/Windows x64

安裝前準備：

• 已安裝好 TDengine 應用驅動，請參考安裝連接器驅動步驟
• 已安裝 Python 2.7 or >= 3.4
• 已安裝 pip

Python連接器安裝

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

pip install taospy

如果不使用系統默認的 python 和 pip，則需要指定 pip 的版本或路徑：

pip2 install taospy
pip3 install taospy

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

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

示例程序

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

• read_example.py Python示例源程序

用戶可以參考 read_example.py 這個程序來設計(ji)用戶自(zi)己的(de)寫入、查詢程序。

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

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

• 通過 TaosConnection 對象的 .cursor() 方法獲取一個(ge)(ge)新的游(you)標(biao)對(dui)象，這個(ge)(ge)游(you)標(biao)對(dui)象必須(xu)保證每個(ge)(ge)線程(cheng)獨享。

• 通過游標對象的 execute()方(fang)法(fa)，執行寫入或查詢(xun)的 SQL 語句(ju)。

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

• 如果(guo)執(zhi)(zhi)行的是查詢語句(ju)，則 execute 執(zhi)(zhi)行成功后(hou)，需要通(tong)過(guo) fetchall 方法(fa)去(qu)拉取結果(guo)集(ji)。 具體方法(fa)可以參考示例代(dai)碼。

安裝驗證

運行如下指令：

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

驗證通過將打印出(chu)成(cheng)功信息(xi)。

Python 連接器的使用

PEP-249 兼容 API

您可以像(xiang)其他(ta)數據庫一樣，使(shi)用類似 數據庫 API 規范風格的 API：

import taos

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

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

代碼示例

1. 導入 TDengine 客戶端模(mo)塊

   import taos

2. 獲取連接并獲取游標對象

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

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

3. 寫入數據

   import datetime
   
   # 創建數據庫
   c1.execute('create database db')
   c1.execute('use db')
   # 建表
   c1.execute('create table tb (ts timestamp, temperature int, humidity float)')
   # 插入數據
   start_time = datetime.datetime(2019, 11, 1)
   affected_rows = c1.execute('insert into tb values (\'%s\', 0, 0.0)' %start_time)
   # 批量插入數據
   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. 查詢數據

   c1.execute('select * from tb')
   # 拉取查詢結果
   data = c1.fetchall()
   # 返回的結果是一個列表，每一行構成列表的一個元素
   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 循環拉取查詢結果
   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 來操作數據庫。

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 方法會返回一個 TaosResult 對象，并提供了以下(xia)屬性或方法:

屬性:

• fields: TaosFields 集合類，提供返回數據的列信息。
• field_count: 返回數據的列數.
• affected_rows: 插入數據的行數.
• row_count: 查詢數據結果數.
• precision: 當前數據庫的時間精度.

方法:

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

訂閱 API

1. 創建一(yi)個同步訂閱隊列：

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

2. 消費訂閱的數據

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

3. 取消訂閱

   sub.close()

4. 關閉連接

   conn.close()

JSON 類型

從 taospy v2.2.0 開(kai)始(shi)，Python 連接器開(kai)始(shi)支持 JSON 數據類(lei)型(xing)的標簽（TDengine版(ban)本(ben)要求 Beta 版(ban) 2.3.5+， 穩定版(ban) 2.4.0+）。

創建一個使用JSON類型標簽的超(chao)級表及其子表：

# 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\"}')")

查(cha)詢子表標簽(qian)及表名：

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

tags 內容為：

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

獲(huo)取 JSON 中某值(zhi)：

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

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

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

由于目前(qian) Python 對(dui) nanosecond 支(zhi)持的(de)不完善(shan)(參見鏈接(jie) 1. 2. )，目前(qian)的(de)實現方(fang)式(shi)是在 nanosecond 精(jing)度時返回整(zheng)數，而不是 ms 和 us 返回的(de) datetime 類型，應用(yong)開發者需要自行處(chu)理，建議使用(yong) pandas 的(de) to_datetime()。未來如果 Python 正(zheng)式(shi)完整(zheng)支(zhi)持了納秒，濤思數據可(ke)能(neng)會修改相關接(jie)口。

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

幫助信息

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

• TaosConnection 類

  參考 Python 中(zhong) help(taos.TaosConnection)。 這(zhe)個(ge)類對(dui)應客戶端和(he) TDengine 建立(li)的一個(ge)連(lian)接。在客戶端多線程的場(chang)景下(xia)，推薦每(mei)個(ge)線程申請一個(ge)獨立(li)的連(lian)接實例，而不建議(yi)多線程共享(xiang)一個(ge)連(lian)接。

• TaosCursor 類

  參考 Python 中 help(taos.TaosCursor)。 這個類對應客(ke)戶端(duan)(duan)進行的(de)寫入、查詢操作(zuo)。在(zai)客(ke)戶端(duan)(duan)多線程的(de)場景下，這個游標實(shi)例必須保持(chi)線程獨(du)享(xiang)(xiang)，不能跨線程共享(xiang)(xiang)使用，否則(ze)會導(dao)致返回結果(guo)出現錯(cuo)誤。

• connect 方法

  用于生成 taos.TaosConnection 的實例。

RESTful Connector

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

注意：與原生連接器的一個區別是，RESTful 接口是無狀態的，因此 USE db_name 指(zhi)(zhi)令沒有效果，所有對表名、超級表名的引(yin)用(yong)都需要指(zhi)(zhi)定數據(ju)庫名前(qian)綴。（從(cong) 2.2.0.0 版(ban)(ban)本開(kai)始(shi)(shi)，支持(chi)在 RESTful url 中指(zhi)(zhi)定 db_name，這時如果 SQL 語句中沒有指(zhi)(zhi)定數據(ju)庫名前(qian)綴的話(hua)，會(hui)使用(yong) url 中指(zhi)(zhi)定的這個 db_name。從(cong) 2.4.0.0 版(ban)(ban)本開(kai)始(shi)(shi)，RESTful 默認有 taosAdapter 提供(gong)，要求必須在 url 中指(zhi)(zhi)定 db_name。）

安裝

RESTful 接口不(bu)依賴(lai)于任(ren)何 TDengine 的(de)庫，因(yin)此(ci)客戶端不(bu)需(xu)要(yao)(yao)安裝任(ren)何 TDengine 的(de)庫，只要(yao)(yao)客戶端的(de)開發(fa)語(yu)言支持 HTTP 協(xie)議即可。

驗證

在(zai)已(yi)經安裝 TDengine 服務(wu)器端的情(qing)況下，可以按照如下方式進行驗證。

下面以 Ubuntu 環境(jing)中(zhong)使(shi)用(yong) curl 工具(ju)（確(que)認已經(jing)安裝(zhuang)）來驗證 RESTful 接(jie)口(kou)的正常。

下(xia)面(mian)示例是列出所有的(de)數據庫(ku)，請把 h1.yakult-sh.com.cn 和(he) 6041（缺省值）替換為實際運(yun)行的(de) TDengine 服務 fqdn 和(he)端口號(hao)：

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

返(fan)回值結果如下表示驗證通過(guo)：

{
  "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 請求格式

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

參數說明：

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

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

HTTP 請求的(de) Header 里(li)需(xu)帶有身(shen)份認證(zheng)信息(xi)，TDengine 支持 Basic 認證(zheng)與自定義認證(zheng)兩(liang)種機制(zhi)，后(hou)續版本將(jiang)提供標準安全的(de)數字簽(qian)名(ming)機制(zhi)來做身(shen)份驗證(zheng)。

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

Authorization: Taosd <TOKEN>

• Basic身份認證信息如下所示

Authorization: Basic <TOKEN>

HTTP 請求的 BODY 里就是一個完整的 SQL 語句，SQL 語句中的數據表應提供數據庫前綴，例如 \.\。如果表名不帶數據庫前綴，又沒有在 url 中指定數據庫名的話，系統會返回錯誤。因為 HTTP 模塊只是一個簡單的轉發，沒有當前 DB 的概念。

使用 curl 通(tong)過自定義身份認(ren)證方式(shi)來發(fa)起一個 HTTP Request，語法如(ru)下：

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} 經過 Base64 編碼之后的字符串，例如 root:taosdata 編碼后為 cm9vdDp0YW9zZGF0YQ==

HTTP 返回格式

返回值為 JSON 格式，如(ru)下:

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

column_meta 中的列(lie)類型說(shuo)明：

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

自定義授權碼

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

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

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

• status：請求結(jie)果(guo)的(de)標志位

• code：返回值(zhi)代碼

• desc：授權碼

獲取授權碼示例：

curl //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
}

• 創建庫 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
}

其他用法

結果集采用 Unix 時間戳

HTTP 請求 URL 采用 sqlt 時(shi)，返回結(jie)果集的(de)時(shi)間戳將采用 Unix 時(shi)間戳格式表示，例如

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
}

結果集采用 UTC 時間字符串

HTTP 請求 URL 采用 sqlutc 時(shi)，返回結(jie)果集的(de)時(shi)間(jian)戳將采用 UTC 時(shi)間(jian)字(zi)符串表示，例如

  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
}

重要配置項

下面僅(jin)列出一些與 RESTful 接口有關的配(pei)置(zhi)參數，其他系統參數請看(kan)配(pei)置(zhi)文(wen)件(jian)里的說明。（注意：配(pei)置(zhi)修(xiu)改后，需要(yao)重啟(qi) taosd 服務才能生(sheng)效）

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

CSharp Connector

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

• C# 連接器現(xian)在也支持從

• 在 Windows 系統(tong)上，C# 應用程序可以使(shi)用 TDengine 的(de)原生 C 接口來(lai)執行所有(you)數據庫操作，后續版(ban)本將提供 ORM（Dapper）框架驅動(dong)。

安裝準備

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

示例程序

示例程序源碼位于

• {client_install_directory}/examples/C#

注意: TDengineTest.cs C# 示例源程序，包含了(le)數據庫連接(jie)參(can)數，以及如何(he)執行數據插(cha)入(ru)、查詢等操作(zuo)。

安裝驗證

需要先安裝 .NET SDK

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

C#連接器的使用

在(zai) Windows 系統上，C# 應用(yong)程(cheng)序可以使(shi)用(yong) TDengine 的 C# 連接(jie)器接(jie)口來(lai)執行(xing)所(suo)有數據庫的操作(zuo)。使(shi)用(yong)的具體步驟如下所(suo)示：

• 創建一個 C# project（需要 .NET SDK）.

mkdir test
cd test 
dotnet new console

• 通過 Nuget 引用 TDengineDriver 包

dotnet add package TDengine.Connector

• 在項目中需要用到 TDengineConnector 的地方引用 TDengineDriver namespace。

using TDengineDriver;

• 用戶可以參考來定義數據庫連接參數，以及如何執行數據插入、查詢等操作。

注意：

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

第三方驅動

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

//接口下載
//github.com/maikebing/Maikebing.EntityFrameworkCore.Taos   
//用法說明    
//www.yakult-sh.com.cn/blog/2020/11/02/1901.html                    

Go Connector

安裝準備

Go 連接器(qi)支(zhi)持的(de)系統有：

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

安裝前準備：

• 已安裝好 TDengine 應用驅動，參考安裝連接器驅動步驟。

示例程序

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

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

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

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

在(zai) taosdemo.go 所在(zai)目錄下進行編譯和執(zhi)行：

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驅動程序包taosSql。taosSql 實現了 GO 語言的內置接口 database/sql/driver。用(yong)戶(hu)只需按如下方式引(yin)入包就(jiu)可以在應(ying)用(yong)程序中訪問 TDengine。

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

提示：下劃線(xian)與雙(shuang)引號之間必須有一(yi)個(ge)空格。

taosSql 的 v2 版本進行了重構，分離出內置數據庫操作接口 database/sql/driver 到目錄 taosSql；訂閱、 stmt 等其他功能放到目錄 af。

常用 API

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

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

  注意： 該(gai) API 成功創建的(de)時候，并沒(mei)有(you)做權限等檢查，只有(you)在真正執(zhi)行 Query 或者 Exec 的(de)時候才能真正的(de)去(qu)創建連(lian)接，并同(tong)時檢查 user/password/host/port 是不(bu)是合(he)法(fa)。另外，由于整個(ge)驅動(dong)程序大部分實現都下(xia)沉(chen)到(dao) taosSql 所依賴(lai)的(de) libtaos 動(dong)態庫中。所以，sql.Open 本身特別(bie)輕(qing)量(liang)。

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

  sql.Open 內置的(de)方法，用來執行非(fei)查詢相關 SQL

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

  sql.Open 內置(zhi)的方法，用(yong)來執(zhi)行(xing)查(cha)詢語句

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

  sql.Open 內置的方法，Prepare creates a prepared statement for later queries or executions.

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

  sql.Open 內置的方法，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 內置的方法(fa)，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 內置的(de)方法，Close closes the statement.

其他代碼示例

是一個通(tong)過(guo) Go 語言(yan)實(shi)現消(xiao)費 Kafka 隊列(lie)寫入 TDengine 的示例程序，也可(ke)以作(zuo)為通(tong)過(guo) Go 連接(jie) TDengine 的寫法(fa)參(can)考(kao)。

Go RESTful的使用

引入

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

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

sql.Open?的driverName 為?taosRestful

DSN

格式為：

數(shu)(shu)據庫用戶名:數(shu)(shu)據庫密碼@連接方(fang)式(域名或(huo)ip:端(duan)口)/[數(shu)(shu)據庫][?參數(shu)(shu)]

樣例：

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

參數：

disableCompression 是否(fou)接受壓(ya)縮(suo)數據(ju)，默認為 true 不接受壓(ya)縮(suo)數據(ju)，如果(guo)傳輸數據(ju)使(shi)用 gzip 壓(ya)縮(suo)設置為 false。

readBufferSize 讀取數(shu)據的緩存區大(da)小默認為(wei) 4K(4096)，當(dang)查詢結(jie)果數(shu)據量多時可(ke)以適當(dang)調大(da)該值。

使用限制

由于 RESTful 接口無狀態所以 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)否則將報錯[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 開始支持。當指定的 db 不存在時執行 create database 語句不會報錯(cuo)(cuo)，而(er)執行針對該 db 的其他查詢或寫(xie)入操(cao)作(zuo)會報錯(cuo)(cuo)。完整(zheng)示(shi)例如下：

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，之后執行 go mod tidy。

• stmt 相關接口崩潰

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

• 使用 use db 語句后執行其他語句報錯 [0x217] Database not specified or available

  在 RESTful 接口中 SQL 語句的執行無上下文關聯，使用 use db 語句(ju)不會生效(xiao)，解決辦法見(jian)上方使用限制章節。

• 使用 taosSql 不報錯使用 taosRestful 報錯 [0x217] Database not specified or available

  因為 RESTful 接口無狀態，使用 use db 語(yu)句不會生效，解決辦法(fa)見上方使用限制章節(jie)。

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

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

• readBufferSize 參數調大后無明顯效果

  readBufferSize 調(diao)大(da)后會減少獲取結(jie)果(guo)(guo)(guo)時 syscall 的(de)調(diao)用。如(ru)果(guo)(guo)(guo)查詢(xun)結(jie)果(guo)(guo)(guo)的(de)數(shu)據(ju)量不大(da)，修改該(gai)參數(shu)不會帶來(lai)明顯提(ti)升(sheng)，如(ru)果(guo)(guo)(guo)該(gai)參數(shu)修改過大(da)，瓶頸會在(zai)解析(xi) JSON 數(shu)據(ju)。如(ru)果(guo)(guo)(guo)需要優化(hua)查詢(xun)速度，需要根據(ju)實際(ji)情況(kuang)調(diao)整(zheng)該(gai)值來(lai)達到查詢(xun)效(xiao)果(guo)(guo)(guo)最優。

• disableCompression 參(can)數設置為 false 時(shi)查詢效率(lv)降(jiang)低(di)

  當(dang) disableCompression 參數設置為 false 時(shi)查(cha)詢結果會 gzip 壓縮(suo)后(hou)傳輸，拿到數據(ju)后(hou)要先進行 gzip 解壓。

Node.js Connector

Node.js 連接器支持的(de)系統有：

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

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

安裝準備

• 應用驅動安裝請參考安裝連接器驅動步驟。

安裝Node.js連接器

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

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

npm install td2.0-connector

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

我們使用 和 TDengine 服務端進行交互(hu)。安裝 Node.js 連接器(qi)之前，還需要(yao)根據具體操作系(xi)統來安裝下文提到的一些依(yi)賴工具。

Linux

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

Windows

安裝方法1

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

安裝方法2

手動安裝以下工具：

• 安裝 Visual Studio 相關： 或者
• 安裝 2.7(v3.x.x 暫不支持) 并執行 npm config set python python2.7
• 進入cmd命令行界面，npm config set msvs_version 2017

如果以上步驟不能(neng)成功執(zhi)行(xing)，可以參(can)考微(wei)軟的(de) Node.js 用(yong)戶手冊 。

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

示例程序

示(shi)例程序源碼位(wei)于 install_directory/examples/nodejs，有：

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

安裝驗證

在(zai)安裝好 TDengine 客戶端后，使用 nodejsChecker.js 程序(xu)能夠驗(yan)證當前環境(jing)是(shi)否支持 Node.js 方式訪問 TDengine。

驗證方法：

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

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

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

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

Node.js連接器的使用

以下(xia)是 Node.js 連接器的一(yi)些基本使用方法，詳(xiang)細的使用方法可(ke)參考。

建立連接

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

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

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

執行 SQL 和插入數據

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

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

以上代碼創建了一個名稱為 test 的(de)數據(ju)庫(ku)。對(dui)于(yu) DDL 語句(ju)，一般沒有返(fan)回值，cursor 的(de) execute 返(fan)回值為 0。

對于 Insert 語(yu)句(ju)，代碼如下：

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

execute 方法的(de)(de)返(fan)(fan)回(hui)值(zhi)為該(gai)語句影(ying)響的(de)(de)行數(shu)，上面的(de)(de) SQL 向 test 庫的(de)(de) weather 表(biao)中，插入了一條數(shu)據，則返(fan)(fan)回(hui)值(zhi) affectRows 為 1。

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

查詢

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

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

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

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

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

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

如果在query語句里提供第二個參數并設為true也可以立即獲取查詢結果。如下：

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

關閉連接

在完(wan)成插入、查詢等操(cao)作后(hou)，要(yao)關(guan)閉連(lian)接。代碼如(ru)下：

conn.close();

異步函數

異步查詢數據庫的操作和上面類似，只需要在cursor.execute, TaosQuery.execute等函數后面加上_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();
})

示例

提供了(le)一(yi)個(ge)使(shi)用 Node.js 連(lian)接(jie)器建表(biao)，插入天(tian)氣數(shu)據并查詢插入的數(shu)據的代碼示例。

同樣是一個使用 Node.js 連接器建表，插入天氣數據并查詢插入的數據的代碼示例，但和上面不同的是，該示例只使用 cursor。