Time Series Database:JDBC ベースの TSQL クエリ

TSDB の SQL クエリエンジンは、Java Database Connectivity（JDBC）プロトコルをサポートしています。JDBC をサポートする一般的なクライアントから TSDB にアクセスしたり、Java アプリケーションで TSQL を使用して JDBC プロトコルを介して TSDB の時系列データをクエリしたりできます。

特定の TSDB バージョンでは、TSDB インスタンスの [インスタンスの詳細] ページで、JDBC を介して TSDB にアクセスするために必要な URL を表示できます。

このトピックでは、Java アプリケーションで TSQL を使用して JDBC プロトコルを介して TSDB の時系列データをクエリする方法について説明します。

I. JDBC 接続例

1. JDBC ドライバーの依存関係を追加する

次の要件が満たされていることを確認してください。

• Java ランタイム環境 1.8 が使用されている。
• TSDB インスタンスへの JDBC ベースのアクセスが構成されており、アクセスの URL が取得されている。
• アプリケーションクライアントが TSDB インスタンスにアクセスできるように、TSDB インスタンスのブラックリストまたはホワイトリストが構成されている。

TSQL の JDBC ドライバーの依存関係は、Maven リポジトリに公開されています。次の例では、Maven リポジトリを使用して tsql_jdbc_app プロジェクトを管理します。pom.xml ファイルに次のコンテンツを追加する必要があります。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.alibaba.tsdb.tsql</groupId>
    <artifactId>tsql_jdbc_app</artifactId>
    <version>1.0-SNAPSHOT</version>

    <dependencies>
        <!-- https://mvnrepository.com/artifact/org.apache.drill.exec/drill-jdbc -->
        <dependency>
            <groupId>org.apache.drill.exec</groupId>
            <artifactId>drill-jdbc-all</artifactId>
            <version>1.15.0</version>
            <exclusions>
                <exclusion>
                    <groupId>org.slf4j</groupId>
                    <artifactId>log4j-over-slf4j</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <configuration>
                    <archive>
                        <manifest>
                            <mainClass>com.alibaba.tsdb.tsql.TsqlJdbcSampleApp</mainClass>
                        </manifest>
                    </archive>
                    <descriptorRefs>
                        <descriptorRef>jar-with-dependencies</descriptorRef>
                    </descriptorRefs>
                </configuration>
                <executions>
                    <execution>
                        <id>make-assembly</id> <!-- 継承のマージに使用されます -->
                        <phase>package</phase> <!-- パッケージングフェーズにバインド -->
                        <goals>
                            <goal>single</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

2. JDBC 接続のサンプルコード

以下に参考例を示します。次のパラメーター設定を変更する必要があります。

• host: TSDB インスタンスのホスト名または IP アドレスを指定します。
• port: JDBC ポートを指定します。Alibaba Cloud TSDB では、デフォルトの JDBC ポートは 3306 です。
• sql: 実行する TSQL クエリステートメントを指定します。

Java アプリケーションプロジェクトで、com.alibaba.tsdb.tsql パッケージと TsqlJdbcSampleApp Java ソースファイルを作成します。

サンプルコードは次のとおりです。

package com.alibaba.tsdb.tsql;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class TsqlJdbcSampleApp {
    public static void main(String[] args) throws Exception {
        Connection connection = null;
        Statement stmt = null;

        try {
            // ステップ 1: JDBC ドライバーを登録する
            Class.forName("org.apache.drill.jdbc.Driver");

            // TSDB インスタンスのホスト名またはアドレス
            String host = "ts-uf64t3199j58j8251.tsql.hitsdb.rds.aliyuncs.com";
            // TSQL JDBC サービスのポート
            int port = 3306;

            String jdbcUrl = String.format("jdbc:drill:drillbit=%s:%s", host, port);

            // ステップ 2: 接続を開く
            System.out.println("データベースに接続しています @ " + jdbcUrl + "  ...");
            connection = DriverManager.getConnection(jdbcUrl);

            // ステップ 3: ステートメントを作成する
            System.out.println("ステートメントを作成しています...");
            stmt = connection.createStatement();


            // ステップ 4: ステートメントを使用してクエリを実行する。
            String sql = "select hostname, `timestamp`, `value` " +
                "from tsdb.`cpu.usage_system` " +
                "where `timestamp` between '2019-03-01' and '2019-03-01 00:05:00'";

            ResultSet rs = stmt.executeQuery(sql);

            // ステップ 5: ResultSet からデータを抽出する。
            int row = 0;
            System.out.println("hostname\ttimestamp\tvalue");
            System.out.println("-----------------------------------------------------");
            while (rs.next()) {
                row++;
                System.out.println(rs.getString("hostname") + "\t" + rs.getTimestamp("timestamp") + "\t" +rs.getDouble("value"));
            }
            System.out.println("-----------------------------------------------------");
            System.out.println( row + " 行が返されました");

        } catch(SQLException se){
            // JDBC のエラーを処理する
            se.printStackTrace();
        }catch(Exception e){
            // Class.forName のエラーを処理する
            e.printStackTrace();
        }finally{
            // リソースを閉じるために finally ブロックを使用する
            try{
                if(stmt!=null)
                    stmt.close();
            }catch(SQLException se2){
            }// 何もできない
            try{
                if(connection!=null)
                    connection.close();
            }catch(SQLException se){
                se.printStackTrace();
            }// finally try の終了
        }// try の終了
        System.out.println("Goodbye!");
    }
}

3. コンパイルと実行

プロジェクトのルートディレクトリで、次の Maven コマンドを実行します。maven clean install

コマンドが実行されると、プロジェクトの /targets ディレクトリに tsql_jdbc_app-1.0-SNAPSHOT-jar-with-dependencies.jar という名前の実行可能ファイルが取得されます。

JAR ファイルを実行します。

java -jar target/tsql_jdbc_app-1.0-SNAPSHOT-jar-with-dependencies.jar

次の図は、クエリ結果の一部を示しています。

II. JDBC の使用に関する制限

JDBC プロトコルを使用して TSDB インスタンスにアクセスする前に、次の制限事項を認識していることを確認してください。

1. TSQL は時系列データとメタデータのクエリをサポートしますが、データの書き込み、変更、または削除は許可しません。
2. TSDB はトランザクションをサポートしていません。

次の表に、JDBC API の呼び出しに関する制限事項を示します。

API	メソッド	TSDB の制限
Connection	setAutoCommit(boolean)	入力パラメーターとして true 値のみを許可します。
Connection	getAutoCommit()	true 値を返します。
Connection	commit()	このメソッドを呼び出すと、次のエラーメッセージが表示されます: SQLFeatureNotSupportedException。
Connection	rollback()	このメソッドを呼び出すと、次のエラーメッセージが表示されます: SQLFeatureNotSupportedException。
Connection	setTransactionIsolation(int level)	入力パラメーターとして TRANSACTION_NONE のみ許可します。
Connection	getTransactionIsolation()	入力パラメーターとして TRANSACTION_NONE のみ許可します。
Connection	setSavePoint()	このメソッドを呼び出すと、次のエラーメッセージが表示されます: SQLFeatureNotSupportedException。
Connection	setSavePoint(String name)	このメソッドを呼び出すと、次のエラーメッセージが表示されます: SQLFeatureNotSupportedException。
Connection	rollback(Savepoint savepoint)	このメソッドを呼び出すと、次のエラーメッセージが表示されます: SQLFeatureNotSupportedException。
Connection	releaseSavePoint(Savepoint savepoint)	このメソッドを呼び出すと、次のエラーメッセージが表示されます: SQLFeatureNotSupportedException。
Connection	setNetworkTimeout()	このメソッドを呼び出すと、次のエラーメッセージが表示されます: SQLFeatureNotSupportedException。
Connection	getNetworkTimeout()	このメソッドを呼び出すと、次のエラーメッセージが表示されます: SQLFeatureNotSupportedException。