Lindorm JDBC ドライバーを使用して LindormTSDB に接続し、利用する方法 - Lindorm

Lindorm JDBC ドライバーを使用して、Java アプリケーションから LindormTSDB に接続します。このチュートリアルでは、ドライバーのインストール、接続、および基本的なテーブル作成、データ挿入、クエリ操作の実行方法を説明します。

前提条件

開始する前に、次の準備が整っていることを確認してください。

JDK V1.8 以降がインストールされていること
クライアント IP アドレスが Lindorm インスタンスのホワイトリストに追加されていること — 詳細については、「ホワイトリストの設定」をご参照ください
LindormTSDB エンドポイントを取得していること — 詳細については、「エンドポイントの確認」をご参照ください

ステップ1：ドライバーのインストール

次のいずれかのインストール方法を選択してください。

JAR ファイルを手動でダウンロード

Maven Central からlindorm-all-client JAR パッケージをダウンロードします。要件に合ったバージョンを選択してください。例えば、バージョン 2.1.5 をインストールする場合は、lindorm-all-client-2.1.5.jar をダウンロードし、プロジェクトのクラスパスに追加します。

Maven 依存関係の追加 (推奨)

pom.xml に次の依存関係を追加します。

<dependency>
    <groupId>com.aliyun.lindorm</groupId>
    <artifactId>lindorm-all-client</artifactId>
    <version>2.2.1.3</version>
</dependency>

要件に応じてバージョンを指定してください。

ステップ2：LindormTSDB への接続

LindormTSDB の JDBC URL 形式は次のとおりです：

jdbc:lindorm:tsdb:url=http://<endpoint>:<port>

パラメーター	説明	例
`<endpoint>`	Lindorm コンソールから取得した LindormTSDB エンドポイント	`ld-bp12pt80qr38p****-proxy-tsdb-pub.lindorm.rds.aliyuncs.com`
`<port>`	LindormTSDB ポート	`8242`

URL パラメーターの完全なリストについては、「JDBC ドライバーの URL」をご参照ください。

ステップ3：テーブルの作成、データの挿入、クエリの実行

次の例では、LindormTSDB に接続し、デフォルトデータベースに時系列テーブルを作成し、バッチで行を挿入し、時間範囲を指定してデータをクエリします。

import java.sql.*;

class Test {
    public static void main(String[] args) {
        // お使いの LindormTSDB エンドポイントとポートに置き換えてください。
        String url = "jdbc:lindorm:tsdb:url=http://ld-bp12pt80qr38p****-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242";
        Connection conn = null;

        try {
            conn = DriverManager.getConnection(url);
            try (Statement stmt = conn.createStatement()) {
                // デフォルトデータベースに時系列テーブルを作成します。
                // device_id と region は TAG 列 (フィルタリング用のディメンション) です。
                stmt.execute("CREATE TABLE sensor1 (device_id VARCHAR TAG, region VARCHAR TAG, time TIMESTAMP, temperature DOUBLE, humidity DOUBLE, PRIMARY KEY(device_id, region))");

                // ラウンドトリップを削減するため、複数の行を 1 つのバッチで挿入します。
                stmt.addBatch("INSERT INTO sensor1(device_id, region, time, temperature, humidity) values('F07A1260','north-cn','2021-04-22 15:33:00',12.1,45)");
                stmt.addBatch("INSERT INTO sensor1(device_id, region, time, temperature, humidity) values('F07A1260','north-cn','2021-04-22 15:33:10',13.2,47)");
                stmt.addBatch("INSERT INTO sensor1(device_id, region, time, temperature, humidity) values('F07A1260','north-cn','2021-04-22 15:33:20',10.6,46)");
                stmt.addBatch("INSERT INTO sensor1(device_id, region, time, temperature, humidity) values('F07A1261','south-cn','2021-04-22 15:33:00',18.1,44)");
                stmt.addBatch("INSERT INTO sensor1(device_id, region, time, temperature, humidity) values('F07A1261','south-cn','2021-04-22 15:33:10',19.7,44)");
                stmt.executeBatch();
                stmt.clearBatch();
            }

            // スキャンするデータ量を制限するため、常に時間範囲を指定してください。
            try (PreparedStatement pstmt = conn.prepareStatement(
                    "SELECT device_id, region, time, temperature, humidity FROM sensor1 WHERE time >= ? AND time <= ?")) {
                pstmt.setTimestamp(1, Timestamp.valueOf("2021-04-22 15:33:00"));
                pstmt.setTimestamp(2, Timestamp.valueOf("2021-04-22 15:33:20"));
                try (ResultSet rs = pstmt.executeQuery()) {
                    while (rs.next()) {
                        String device_id  = rs.getString("device_id");
                        String region      = rs.getString("region");
                        Timestamp time     = rs.getTimestamp("time");
                        Double temperature = rs.getDouble("temperature");
                        Double humidity    = rs.getDouble("humidity");
                        System.out.printf("%s %s %s %f %f\n", device_id, region, time, temperature, humidity);
                    }
                }
            }
        } catch (SQLException e) {
            e.printStackTrace();
        } finally {
            try {
                if (conn != null) conn.close();
            } catch (SQLException e) {
                e.printStackTrace();
            }
        }
    }
}

クエリが成功すると、次のような出力が表示されます：

F07A1261 south-cn 2021-04-22 15:33:00.0 18.100000 44.000000
F07A1261 south-cn 2021-04-22 15:33:10.0 19.700000 44.000000
F07A1260 north-cn 2021-04-22 15:33:00.0 12.100000 45.000000
F07A1260 north-cn 2021-04-22 15:33:10.0 13.200000 47.000000
F07A1260 north-cn 2021-04-22 15:33:20.0 10.600000 46.000000

データ型マッピング

LindormTSDB の SQL 型は、次のように Java の型に対応します：

LindormTSDB の型	Java の型	JDBC ゲッター
`VARCHAR`	`java.lang.String`	`rs.getString()`
`VARCHAR TAG`	`java.lang.String`	`rs.getString()`
`DOUBLE`	`java.lang.Double`	`rs.getDouble()`
`TIMESTAMP`	`java.sql.Timestamp`	`rs.getTimestamp()`

トラブルシューティング

接続に失敗する場合

1. クライアント IP がインスタンスのホワイトリストに含まれていることを確認してください。
2. JDBC URL のエンドポイントとポートが正しいことを確認してください。
3. Lindorm インスタンスが実行中で、時系列エンジンが有効になっていることを確認してください。

クエリがデータを返さない場合

1. WHERE 句の時間範囲が、挿入されたデータのタイムスタンプと一致していることを確認してください。
2. テーブル名と列名が正しいことを確認してください。

executeBatch() が遅い場合

ワークロードとデータ量に応じて、バッチサイズを調整してください。

次のステップ

JDBC ドライバーの URL — JDBC URL パラメーターの全リスト
サポートされている API 操作とメソッド — LindormTSDB の JDBC API カバレッジ
SQL リファレンス — LindormTSDB の全 SQL 構文