小 T 導讀：雖然 [TDengine ]( https://www.taosdata.com/"TDengine ")已經提供了非常多的常用計算函式，但是在具體實踐中，企業的開發團隊往往會因為自己特殊的業務需求，需要特有的計算函式，這時候，支援自定義函式功能就特別重要了。本文將介紹 TDengine 3.0 支援的 UDF 機制。

在使用 TDengine 這款[時序資料庫]( https://www.taosdata.com/"時序資料庫")（Time Series Database, TSDB）的時候，我們經常會用到各種內建函式，透過在資料庫中完成很多計算，可以大大簡化資料庫應用層的開發工作。

TDengine 提供了大量的內建函式，可以分為幾個大類：

**◆ 單行函式：單行函式為查詢結果中的每一行返回一個結果行**
- 數學函式：如 ABS、SIN、COS、LOG、POW 等
- 字串函式：如 CHAR_LENGTH、CONCAT、LOWER、SUBSTR、UPPER 等
- 轉換函式：如 CAST、TO_JSON、TO_UNIXTIMESTAMP 等
- 時間和日期函式：NOW、TIMEDIFF、TIMEZONE、TODAY 等

**◆ 聚合函式：聚合函式為查詢結果集的每一個分組返回單個結果行**
- 如 AVG、COUNT、STDDEV、SUM 等

**◆ 選擇函式
◆ 時序資料特有函式
◆ 系統資訊函式**
雖然 TDengine 已經提供了這麼多常用的計算函式，但是在具體實踐中，企業的開發團隊往往會因為自己特殊的業務需求，需要特有的計算函式，這時候，支援自定義函式功能就特別重要了。

本文將具體介紹如何在 TDengine 中定義並使用自定義函式。

利用 UDF(User Defined Function) 功能，TDengine 可以插入使用者編寫的處理程式碼並在查詢中使用它們，這樣就能很方便地解決特殊應用場景中的使用需求。 UDF 通常以資料表中的一列資料做為輸入，同時支援以巢狀子查詢的結果作為輸入。

TDengine 支援透過 C/C++ 語言來定義 UDF。TDengine 3.0 最佳化了相關機制，所以本文描述的特性適用於 3.0 及以上版本。

**基本概念**
使用者可以透過 UDF 實現兩類函式：標量函式和聚合函式。標量函式對每行資料輸出一個值，如求絕對值 abs，正弦函式 sin，字串拼接函式 concat 等。聚合函式對多行資料進行輸出一個值，如求平均數 avg，最大值 max 等。

實現 UDF 時，需要實現規定的介面函式
- 標量函式需要實現標量介面函式 scalarfn
- 聚合函式需要實現聚合介面函式 aggfn_start、aggfn、aggfn_finish
- 如果需要初始化，實現 udf_init；如果需要清理工作，實現 udf_destroy

介面函式的名稱是 UDF 名稱，或者是 UDF 名稱和特定字尾（_start, _finish, _init, _destroy)的連線。列表中的scalarfn、aggfn、udf需要替換成udf函式名。

**標量介面函式**
int32_t scalarfn(SUdfDataBlock* inputDataBlock, SUdfColumn *resultColumn)

其中 scalarFn 是函式名的佔位符。這個函式對資料塊進行標量計算，透過設定resultColumn結構體中的變數設定值。

引數的具體含義是：
- inputDataBlock: 輸入的資料塊
- resultColumn: 輸出列

**聚合介面函式**
int32_t aggfn_start(SUdfInterBuf *interBuf)
int32_t aggfn(SUdfDataBlock* inputBlock, SUdfInterBuf *interBuf, SUdfInterBuf *newInterBuf)
int32_t aggfn_finish(SUdfInterBuf* interBuf, SUdfInterBuf *result)
其中 aggfn 是函式名的佔位符。首先呼叫aggfn_start生成結果buffer，然後相關的資料會被分為多個行資料塊，對每個資料塊呼叫 aggfn 用資料塊更新中間結果，最後再呼叫 aggfn_finish 從中間結果產生最終結果，最終結果只能含 0 或 1 條結果資料。

引數的具體含義是：
- interBuf：中間結果 buffer。
- inputBlock：輸入的資料塊。
- newInterBuf：新的中間結果buffer。
- result：最終結果。

**UDF 初始化和銷燬**
int32_t udf_init()
int32_t udf_destroy()
其中 udf 是函式名的佔位符。udf_init 完成初始化工作。 udf_destroy 完成清理工作。如果沒有初始化工作，無需定義udf_init函式。
如果沒有清理工作，無需定義udf_destroy函式。 篇幅所限，相關資料結構的定義可以參考 UDF 文件。

**編譯 UDF**
使用者定義函式的 C 語言原始碼無法直接被 TDengine 系統所使用，而是需要先編譯為 動態連結庫，之後才能載入 TDengine 系統。
假設我們編寫了自定義函式，儲存在 add_one.c 檔案中，在 Linux 上可以這樣編譯：
```cpp
gcc -g -O0 -fPIC -shared add_one.c -o add_one.so
```

**建立 UDF**
使用者可以透過 SQL 指令在系統中載入客戶端所在主機上的 UDF 函式庫。一旦建立成功，則當前 TDengine 叢集的所有使用者都可以在 SQL 指令中使用這些函式。UDF 儲存在系統的 MNode 節點上，因此即使重啟 TDengine 系統，已經建立的 UDF 也仍然可用。
在建立 UDF 時，需要區分標量函式和聚合函式。
- 建立標量函式

```cpp
CREATE FUNCTION function_name AS library_path OUTPUTTYPE output_type;
```

例如，如下語句可以把 libbitand.so 建立為系統中可用的 UDF：

```cpp
CREATE FUNCTION bit_and AS "/home/taos/udf_example/libbitand.so" OUTPUTTYPE INT;
```

- 建立聚合函式：

```cpp
CREATE AGGREGATE FUNCTION function_name AS library_path OUTPUTTYPE output_type [ BUFSIZE buffer_size ];
```

例如，如下語句可以把 libl2norm.so 建立為系統中可用的 UDF：

```cpp
CREATE AGGREGATE FUNCTION l2norm AS "/home/taos/udf_example/libl2norm.so" OUTPUTTYPE DOUBLE bufsize 8;
```

如果不再需要，可以透過 DROP 指令刪除所建立的 UDF。

```cpp
DROP FUNCTION function_name;
```

**使用 UDF**
在 SQL 指令中，可以直接以在系統中建立 UDF 時賦予的函式名來呼叫使用者定義函式。例如：
```cpp
SELECT X(c1,c2) FROM table/stable;
```

表示對名為 c1、c2 的資料列呼叫名為 X 的使用者定義函式。SQL 指令中使用者定義函式可以配合 WHERE 等查詢特性來使用。
歡迎下載試用 TDengine 3.0，並嘗試編寫一個自定義函式。

歡迎新增小T：tdengine，加入物聯網技術討論群，第一時間瞭解 TDengine 官方資訊，與關注前沿技術的同學們共同探討新技術、新玩法。

------------

想了解更多 TDengine Database的具體細節，歡迎大家在[GitHub]( https://github.com/taosdata/grafanaplugin"GitHub")上檢視相關原始碼。
[![](http://img.blog.itpub.net/blog/2022/05/11/0fd59db1207fc97f.jpeg?x-oss-process=style/bb)](https://www.taosdata.com/?zh "![](http://img.blog.itpub.net/blog/2022/05/11/0fd59db1207fc97f.jpeg?x-oss-process=style/bb)")

TDengine 3.0 中如何編譯、建立和使用自定義函式

相關文章