想要流暢體驗 TDengine 3.0 資料訂閱功能？要點都在這裡

眾所周知，在 TDengine 3.0 中，我們對資料訂閱功能進行了全面升級，以便大家可以更加便捷地實時訂閱和獲取資料的更新，完成實時監控、資料分析和有效報警等工作。在本文中，TDengine 資/深研發將以 TDengine 3.0 為物件，為大家介紹資料訂閱功能的正確開啟方式，給到有需要的人作參考指南，避免走入應用誤區。

本文將從 Java Developer 的視角來介紹如何使用 TDengine 3.0 的資料訂閱功能。

TDengine 3.0 的版本迭代很快，可能有些配置引數或細節在之後的版本會發生變化，本文對應 TDengine 版本為 3.0.3.0。

寫在前面

在官方檔案裡已經有介紹，TDengine 的資料訂閱是什麼以及如何使用，有需要的朋友可以進入官網檢視相關介紹：

1. 開發指南
2. SQL
3. Java 使用資料訂閱

總結一下，我理解的資料訂閱功能是以“訂閱”的方式獲取存在於 TDengine 中的資料。一般情況下，“訂閱”意味著的業務需求是訂閱資料庫中的最新資料。“訂閱”的流程很簡單：（1）在資料庫中建立 topic；（2）在應用中消費 topic 的資料。

基本操作：建立

在資料庫中建立 topic，使用 SQL 語句 create topic 即可。create topic 這個 SQL 如何寫，實際上定義了 topic 對應的資料粒度，包括哪些資料庫、超級表、子表、列、行。值得一提的是，TDengine 的 SQL 支援訂閱 database、 supertable、subquery 這 3 種模式。 CREATE TOPIC topic_name [WITH META] AS DATABASE db_name; 這種 SQL 可以直接訂閱整個 database； CREATE TOPIC topic_name AS STABLE stb_name 這種 SQL 可以訂閱某個超級表；訂閱子查詢是最普遍的場景。例如：

CREATE TOPIC topic_name AS SELECT ts,voltage,location FROM testdb.meters WHERE voltage > 220.0 and location in ('北京','天津');

上面這個 SQL，訂閱了 testdb 資料庫中的 meters 超級表，透過 where 子句過濾滿足以下條件：location（tag 列）為“北京”或“天津”的子表，且 voltage 超過 220.0 的 ts、voltage、location 的資料。

黃金搭檔：流式計算 + 資料訂閱

以智慧電錶的場景為例，如果我想每 10 分鐘計算一次電壓的平均值，並在平均電壓高於 220V 就進行上報。對於這種需求，單純用 TDengine 的資料訂閱功能是不行的，因為 create topic 的子查詢不支援聚合查詢。這個時候，就需要用 TDengine 的流式計算 + 資料訂閱這對黃金搭檔了。如下：

CREATE STREAM stream_name TRIGGER WINDOW_CLOSE IGNORE EXPIRED 1 
INTO stb_name 
AS SELECT _wend as ts, avg(voltage) as voltage, last_row(location) as location
FROM testdb.meters 
WHERE location in ('北京', '天津') 
PARTITION BY location 
INTERVAL(10m);
CREATE TOPIC topic_name AS SELECT * FROM stream_name where voltage > 220.0;

上面的 2 條 SQL 中，第一條 SQL 建立了一個 stream：以 location 分組，計算每 10 分鐘的“北京”、“天津”的平均電壓；用時間視窗的結束 _wend 作為時間戳 ts；avg(voltage) 計算 voltage 平均值；時間視窗的最後一條 last_row(location) 作為標籤。同時，這個 stream 以 WINDOW_CLOSE 作為計算視窗的觸發模式，過期策略為 IGNORE EXPIRED 1。

第二條 SQL 建立了子查詢訂閱，用於過濾每 10 分鐘平均電壓高於 220V 的資料。這樣我們就建立了一個可以被消費的 topic，消費到的資料為高於 220V 的 10 分鐘平均電壓，滿足了前面所說的監控場景的需求。

消費 topic：很像 Kafka

在應用中消費 topic 的資料，需要按照各種聯結器的 API 來使用，具體使用方式請參考官方檔案。在這裡，我只對 TDengine 和訂閱消費 topic 的一些配置引數進行梳理。

1. 連線相關的引數，java connector 中使用  bootstrap.servers 一個引數代替了  td.connect.ip 和  td.connect.port，使用了和 Kafka 一樣的引數名。 td.connect.user 和  td.connect.pass 仍然需要設定。
2. group.id：和 Kafka 一樣，多個執行緒可以共同消費同一個 topic，只要它們使用同一個 group.id。TDengine 的 vgroup 與 Kafka 的 partition 在概念上是對應的。同一個 group.id 中，一個 vgroup 最多隻對應一個 consumer。如果 consumer 數量大於 vgroup 的數量，則有些 consumer 消費不到資料。
3. auto.offset.reset：這個引數和 Kafka 的行為不一樣。如果 group.id 為新值，在設定 earliest 時，訂閱從頭消費資料；設定為 latest 時，從最新資料開始訂閱。當 group.id 為已存在的值時，不管  auto.offset.reset 為何值，都會從最後一個 offset 開始，繼續消費。
4. enable.auto.commit：建議設定為 false。開啟自動提交 offset，TDengine 的 commit 自動提交機制是輪詢提交。
5. auto.commit.interval.ms：建議不設定。如果  enable.auto.commit 為 true，自動提交 commit 的間隔為  auto.commit.interval.ms 設定的值。
6. enable.heartbeat.background：建議設定為 true，預設值為 true。如果設定為 false，在應用長時間不主動 poll 資料時，可能會造成當前 consumer 的離線。在 TDengine 的實現上，heartbeat 的 interval 被設定成了 1 秒。
7. msg.with.table.name：建議設定成 true。在訂閱超級表和資料庫時新增了 WITH META，應該開啟這個設定。例如：訂閱為  CREATE TOPIC topic_name WITH META AS STABLE stb 時，配置  msg.with.table.name 為 true，則消費時可以獲取到 tableName。

Show U The Code

到此，本文介紹了有關 TDengine3.0 的資料訂閱功能的諸多細節。我相信，上面的內容應該可以為你使用資料訂閱功能提供一些思路和幫助。但是，對程式設計師來說，“Talk is cheap. Show me the code”。下面，我列舉了一些 Java 的示例程式碼，供你參考。

• subscribeDemo-java

這個 java 工程實現了一個最簡單的訂閱功能，從 TDengine 中訂閱一個 topic ，並將消費到的資料寫到檔案中。值得一提的是，程式碼使用 bytebuddy 動態生成了 Java POJO 類和對應的 Deserializer 類。因此，你只需要在 schema.txt 內寫好 topic 對應的欄位，就可以不寫程式碼，直接訂閱不同 topic 的資料了。

• SubscribeDemo

這個頁面展示了一段最基本的資料訂閱的程式碼。main 方法中，包括了在 TDengine 中建立資料庫、表、topic 的操作，並從 topic 中消費資料進行列印。

• WebsocketSubscribeDemo

這個頁面的程式碼和 SubscribeDemo 相比，僅有的區別是其配置了 td.connect.type 引數為 ws，即：使用 websocket 連線 taosadapter，這樣的好處是不用安裝客戶端。

結語

相信藉助本篇文章，你一定能夠流暢體驗到 TDengine 的資料訂閱功能，有需要的讀者可以收藏備用。對於更為複雜的應用問題，也歡迎大家加入 TDengine 的開發者交流群（新增 小T vx：tdengine），直接向社群技術支援人員尋求幫助。關於 TDengine 3.0 的更多示例程式碼，請參考官方檔案。