本文介紹Lindorm TSDB SDK常用接口的使用方法。
Lindorm TSDB SDK的接口主要分成管理接口、寫入接口以及查詢接口等3類。
管理接口
Lindorm時序引擎支持使用SQL進行DDL、DCL操作，這里管理接口相關的示例是直接通過提交SQL實現對應的DDL和DCL操作。在Lindorm TSDB SDK中，支持以下兩個重載方法向Lindorm時序引擎提交SQL實現DDL和DCL操作。
// 直接提交SQL
Result execute(String sql);
// 在指定的數據庫database下進行DDL等操作，比如在指定的database下創建表
Result execute(String database, String sql);其中，Result對象表示SQL的執行結果，比如提交數據庫的列表語句（"SHOW DATABASES"）后，可以通過Result獲取到已經存在的數據庫列表。Result對象有columns、metadata、rows等3個字段，其中，columns為結果的列名集合，metadata為對應列的數據類型集合，rows為結果的按行返回的集合。
public class Result {
private List<String> columns;
private List<String> metadata;
private List<List<Object>> rows;
....
}數據庫和表管理示例
數據庫和表的DDL操作主要包括創建、刪除、查看等。代碼示例如下：
// 1.查看數據庫列表
String showDatabase = "show databases";
Result result = lindormTSDBClient.execute(showDatabase);
System.out.println("before create, db list: " + result.getRows().stream().map(e -> (String) e.get(0)).collect(Collectors.toList()));
// 2.創建數據庫，此處示例創建了名為demo的數據庫
String createDatabase = "create database demo";
result = lindormTSDBClient.execute(createDatabase);
System.out.println("create database:" + result.isSuccessful());
// 3.查看數據庫列表
result = lindormTSDBClient.execute(showDatabase);
System.out.println("after create, db list: " + result.getRows().stream().map(e -> (String) e.get(0)).collect(Collectors.toList()));
String database = "demo";
// 4.查看所有表
String showTables = "show tables";
result = lindormTSDBClient.execute(database, showTables);
System.out.println("before create, table list: " + result.getRows().stream().map(e -> (String) e.get(0)).collect(Collectors.toList()));
// 5.創建表
String createTable = "CREATE TABLE sensor (device_id VARCHAR TAG,region VARCHAR TAG,time BIGINT,temperature DOUBLE,humidity DOUBLE,PRIMARY KEY(device_id))";
result = lindormTSDBClient.execute(database, createTable);
System.out.println("create table: " + result.isSuccessful());
// 6.查看所有表，驗證是否成功創建了表sensor
result = lindormTSDBClient.execute(database, showTables);
System.out.println("after create, table list: " + result.getRows().stream().map(e -> (String) e.get(0)).collect(Collectors.toList()));
// 7.描述表詳情
String describeTable = "describe table sensor";
result = lindormTSDBClient.execute(database, describeTable);
System.out.println("------------ describe table -------------------");
List<String> columns = result.getColumns();
System.out.println("columns: " + columns);
List<String> metadata = result.getMetadata();
System.out.println("metadata: " + metadata);
List<List<Object>> rows = result.getRows();
for (int i = 0, size = rows.size(); i < size; i++) {
List<Object> row = rows.get(i);
System.out.println("column #" + i + " : " + row);
}
System.out.println("------------ describe table -------------------");
// 8.刪除表
String dropTable = "drop table sensor";
result = lindormTSDBClient.execute(database, dropTable);
System.out.println("drop table: " + result.isSuccessful());
// 9.查看表列表，驗證是否成功刪除
result = lindormTSDBClient.execute(database, showTables);
System.out.println("after drop, table list: " + result.getRows().stream().map(e -> (String) e.get(0)).collect(Collectors.toList()));
// 10.刪除指定數據庫
String dropDatabase = "drop database demo";
result = lindormTSDBClient.execute(dropDatabase);
System.out.println("drop database:" + result.isSuccessful());
// 11.查看數據庫列表，驗證指定數據庫是否刪除成功
result = lindormTSDBClient.execute(showDatabase);
System.out.println("after drop, db list : " + result.getRows().stream().map(e -> (String) e.get(0)).collect(Collectors.toList()));運行結果示例：
before create, db list: [default]
create database:true
after create, db list: [default, demo]
before create, table list: []
create table: true
after create, table list: [sensor]
------------ describe table -------------------
columns: [columnName, typeName, columnKind]
metadata: [VARCHAR, VARCHAR, VARCHAR]
column #0 : [device_id, VARCHAR, TAG]
column #1 : [region, VARCHAR, TAG]
column #2 : [time, TIMESTAMP, TIMESTAMP]
column #3 : [temperature, DOUBLE, FIELD]
column #4 : [humidity, DOUBLE, FIELD]
------------ describe table -------------------
drop table: true
after drop, table list: []
drop database:true
after drop, db list : [default]對于這里沒有列舉的其他管理相關的操作，比如連續查詢的創建、刪除等DDL操作，都可以根據Lindorm時序引擎的對應的SQL語法說明構造對應的SQL語句來實現。關于Lindorm時序引擎的SQL語句說明，可以參考SQL語法參考。
寫入接口
Lindom TSDB SDK的寫入接口為多個相同名稱但參數不同的write方法，但根據處理寫入結果方式，可以分成兩類，分別為使用CompletableFuture<WriteResult>處理寫入結果的接口和使用回調函數Callback處理異步寫入結果的接口。
默認情況下，LindormTSDBClient為提高寫入性能，使用異步攢批的方式進行數據寫入。若需要同步寫入，只需要調用下write方法返回的CompletableFuture<WriteResult>的join方法即可。
寫入記錄
Lindorm TSDB SDK使用Record對象表示表中的一行寫入記錄。Record需要指定表名、時間戳、標簽和量測值。其中，時間戳和標簽將用于構建索引。
默認構建Record會進行字符合法性校驗，可以通過在build中添加參數'false'關閉校驗。
Record record = Record
// 指定表名
.table("sensor")
// 指定時間戳，單位為毫秒
.time(currentTime)
// 指定標簽
.tag("device_id", "F07A1260")
.tag("region", "north-cn")
// 指定量測值
.addField("temperature", 12.1)
.addField("humidity", 45.0)
.build();使用CompletableFuture處理寫入結果的接口
每次只提交一行記錄。
// 寫入默認數據庫
CompletableFuture<WriteResult> future = lindormTSDBClient.write(record);
// 寫入指定的數據庫
String database = "demo";
CompletableFuture<WriteResult> future = lindormTSDBClient.write(database, record);每次提交多行記錄（推薦）。這種方式提交方式，可減少提交時的SDK異步隊列鎖競爭，效率較高。
List<Record> records;
// 寫入默認數據庫
CompletableFuture<WriteResult> future = lindormTSDBClient.write(records);
// 寫入指定的數據庫
String database = "demo";
CompletableFuture<WriteResult> future = lindormTSDBClient.write(database, records);處理CompletableFuture<WriteResult>完成時的結果。這里僅是一個示例，業務上可以結合實際情況，調用CompletableFuture的其他方法進行結果處理。
CompletableFuture<WriteResult> future = lindormTSDBClient.write(records);
// 處理異步寫入結果
future.whenComplete((r, ex) -> {
if (ex != null) { // 發送異常，一般都是寫入失敗
System.out.println("Failed to write.");
Throwable throwable = ExceptionUtils.getRootCause(ex);
if (throwable instanceof LindormTSDBException) {
LindormTSDBException e = (LindormTSDBException) throwable;
System.out.println("Caught an LindormTSDBException, which means your request made it to Lindorm TSDB, "
+ "but was rejected with an error response for some reason.");
System.out.println("Error Code: " + e.getCode());
System.out.println("SQL State: " + e.getSqlstate());
System.out.println("Error Message: " + e.getMessage());
} else {
throwable.printStackTrace();
}
} else { // 一般都是寫入成功
if (r.isSuccessful()) {
System.out.println("Write successfully.");
} else {
System.out.println("Write failure.");
}
}
});不要在CompletableFuture的whenComplete等方法中做復雜耗時的計算，否則可能會阻塞寫入；若確實需要做復雜的耗時計算，請將計算邏輯提交到其他獨立現場池中。關于錯誤碼的取值和含義，請參見常見錯誤碼參考。
使用回調函數Callback處理異步寫入結果的接口
寫入回調接口Callback的定義如下所示。onCompletion方法上的result表示寫入結果，records表示這個回調函數關聯的寫入記錄，異常e表示寫入失敗時的異常。
public interface Callback {
void onCompletion(WriteResult result, List<Record> records, Throwable e);
}下面是使用Callback接口處理寫入結果的一個示例。
Callback callback = new Callback() {
@Override
public void onCompletion(WriteResult result, List<Record> list,
Throwable throwable) {
if (throwable != null) { // 寫入失敗
if (throwable instanceof LindormTSDBException) {
LindormTSDBException ex = (LindormTSDBException) throwable;
System.out.println("errorCode: " + ex.getCode());
System.out.println("sqlstate: " + ex.getSqlstate());
System.out.println("message: " + ex.getMessage());
} else {
// 其他錯誤
throwable.printStackTrace();
}
} else {
if (result.isSuccessful()) {
System.out.println("Write successfully.");
} else {
System.out.println("Write failure.");
}
}
}
};不要在Callback的onCompletion中做復雜耗時的計算，否則可能會阻塞寫入；若確實需要做復雜的耗時計算，請將計算邏輯提交到其他獨立現場池中。關于錯誤碼的取值和含義，請參見常見錯誤碼參考。
每次提交一行記錄。
// 寫入默認數據庫
lindormTSDBClient.write(record, callback);
// 寫入指定的數據庫
String database = "demo";
lindormTSDBClient.write(database, record, callback);每次提交多行記錄（推薦）。這種方式提交方式，可減少提交時的SDK異步隊列鎖競爭，效率較高。
List<Record> records;
// 寫入默認數據庫
lindormTSDBClient.write(records, callback);
// 寫入指定的數據庫
String database = "demo";
lindormTSDBClient.write(database, records, callback);查詢接口
Lindorm TSDB SDK的查詢接口是通過SQL查詢數據的，關于SQL語句說明可以參考SQL語法參考。
Lindorm TSDB SDK的查詢接口如下所示，其中，入參有要查詢的數據庫database, 查詢語句sql，查詢結果每批返回的行數大小chunkSize。
ResultSet query(String database, String sql, int chunkSize);Lindorm TSDB SDK 使用ResultSet接口表示SQL查詢結果，其定義如下所示。
public interface ResultSet extends Closeable {
QueryResult next();
void close();
}在處理查詢結果時，可以循環調用ResultSet的next方法獲取查詢結果，當next方法返回的QueryResult對象為null時，表示已經讀取完全部查詢結果。 當查詢結束時，調用ResultSet的close方法釋放對應的IO資源。
QueryResult表示每批返回的查詢結果，該對象有columns、metadata、rows等3個字段，其中，columns為查詢結果的查詢的列名集合，metadata為對應列的數據類型集合，rows為查詢結果的按行返回的集合。其中，關于Lindorm時序引擎查詢支持的數據類型集合，請參考數據類型。下面是處理查詢結果ResultSet的示例。
String sql = "select * from sensor";
int chunkSize = 100;
ResultSet resultSet = lindormTSDBClient.query("demo", sql, chunkSize);
// 處理查詢結果
try {
QueryResult result = null;
// 當resultSet的next()方法返回為null，表示已經讀取完所有的查詢結果
while ((result = resultSet.next()) != null) {
List<String> columns = result.getColumns();
System.out.println("columns: " + columns);
List<String> metadata = result.getMetadata();
System.out.println("metadata: " + metadata);
List<List<Object>> rows = result.getRows();
for (int i = 0, size = rows.size(); i < size; i++) {
List<Object> row = rows.get(i);
System.out.println("row #" + i + " : " + row);
}
}
} finally {
// 查詢結束后，需確保調用ResultSet的close方法，以釋放IO資源
resultSet.close();
}不管查詢是否成功，在查詢結束時，都需顯式調用ResultSet的close方法，以釋放IO資源，否則會造成網絡連接泄露。
另外，Lindorm TSDB SDK也提供了幾個查詢接口重載實現，如下所示，業務上可以根據實際情況選擇使用不同實現。
// SQL查詢語句
String sql = "xxxx";
// 1.使用SQL語句，查詢默認數據庫, 默認每批返回1000行數據
ResultSet resultSet = lindormTSDBClient.query(sql);
String database = "demo";
// 2.使用SQL語句，查詢指定數據庫，默認每批返回1000行數據
ResultSet resultSet = lindormTSDBClient.query(database, sql);