すべてのプロダクト
Search
ドキュメントセンター

Tablestore:SQL 文を実行して Tablestore にアクセスする JDBC を使用する

最終更新日:Jan 27, 2025

Tablestore は、SQL 文を実行して Tablestore にアクセスするために使用できる Java Database Connectivity(JDBC)ドライバを提供します。このトピックでは、JDBC を使用して Tablestore にアクセスする方法について説明します。

注意事項

SQL クエリ機能は、中国(杭州)、中国(上海)、中国(北京)、中国(張家口)、中国(ウランチャブ)、中国(深圳)、中国(成都)、中国(香港)、日本(東京)、シンガポール、マレーシア(クアラルンプール)、英国(ロンドン)、米国(シリコンバレー)、インドネシア(ジャカルタ)、ドイツ(フランクフルト)、SAU(リヤド - パートナーリージョン)、および米国(バージニア)の各リージョンでご利用いただけます。

前提条件

手順

ステップ 1: JDBC ドライバをインストールする

JDBC ドライバは、次のいずれかの方法でインストールできます。

  • Tablestore 用の JDBC ドライバをダウンロードし、プロジェクトにインポートします。ダウンロードパスについては、「Tablestore 用 JDBC ドライバ」をご参照ください。

  • Maven プロジェクトに依存関係を追加します。

    Maven で Tablestore 用 JDBC ドライバを使用するには、対応する依存関係を pom.xml ファイルに追加するだけです。この例では、JDBC ドライバ 5.17.0 を使用しています。<dependencies> に次の内容を追加します。

    <dependency>
      <groupId>com.aliyun.openservices</groupId>
      <artifactId>tablestore-jdbc</artifactId>
      <version>5.17.0</version>
    </dependency>

ステップ 2: JDBC を使用して Tablestore にアクセスする

  1. Class.forName() を使用して、Tablestore 用の JDBC ドライバを読み込みます。

    Tablestore 用 JDBC ドライバの名前は、com.alicloud.openservices.tablestore.jdbc.OTSDriver です。

    Class.forName("com.alicloud.openservices.tablestore.jdbc.OTSDriver");
  2. JDBC を使用して Tablestore インスタンスにアクセスします。

    String url = "jdbc:ots:https://myinstance.cn-hangzhou.ots.aliyuncs.com/myinstance";
    String user = "************************";
    String password = "********************************";
    Connection conn = DriverManager.getConnection(url, user, password);

    次の表に、JDBC を使用して Tablestore インスタンスにアクセスするために設定する必要があるパラメータを示します。

    パラメータ

    説明

    url

    jdbc:ots:https://myinstance.cn-hangzhou.ots.aliyuncs.com/myinstance

    jdbc:ots:schema://[accessKeyId:accessKeySecret@]endpoint/instanceName[?param1=value1&...&paramN=valueN] の形式の Tablestore 用 JDBC ドライバの URL です。URL には、次のフィールドが含まれています。

    • schema:このフィールドは必須であり、Tablestore 用 JDBC ドライバが使用するプロトコルを指定します。ほとんどの場合、このフィールドは https に設定されます。

    • accessKeyId:accessKeySecret:このフィールドはオプションであり、Alibaba Cloud アカウントまたは RAM ユーザーの AccessKey ID と AccessKey シークレットを指定します。

    • endpoint:このフィールドは必須であり、インスタンスのエンドポイントを指定します。詳細については、「エンドポイント」をご参照ください。

    • instanceName:このフィールドは必須であり、インスタンスの名前を指定します。

    その他の設定項目については、「設定項目」をご参照ください。

    user

    ************************

    Alibaba Cloud アカウントまたは RAM ユーザーの AccessKey ID です。

    password

    ********************************

    Alibaba Cloud アカウントまたは RAM ユーザーの AccessKey シークレットです。

    URL または Properties パラメータを使用して、AccessKey ペアと設定項目を渡すことができます。次の例は、インターネット経由で中国(杭州)リージョンの myinstance インスタンスにアクセスする方法を示しています。

    • URL を使用して AccessKey ペアと設定項目を渡す

      DriverManager.getConnection("jdbc:ots:https://************************:********************************@myinstance.cn-hangzhou.ots.aliyuncs.com/myinstance?enableRequestCompression=true");
    • Properties パラメータを使用して AccessKey ペアと設定項目を渡す

      Properties info = new Properties();
      info.setProperty("user", "************************");
      info.setProperty("password", "********************************");
      info.setProperty("enableRequestCompression", "true");
      DriverManager.getConnection("jdbc:ots:https://myinstance.cn-hangzhou.ots.aliyuncs.com/myinstance", info);
  3. SQL 文を実行します。

    createStatement メソッドまたは prepareStatement メソッドを使用して、SQL 文を作成できます。

    説明

    サポートされている SQL 文については、「SQL 機能」をご参照ください。

    createStatement メソッドを使用して SQL 文を作成する

    // ビジネス要件に基づいて SQL 文を作成します。次のサンプルコードは、test_table テーブルの id 列と name 列のデータをクエリする方法を示しています。
    String sql = "SELECT id,name FROM test_table";
    
    Statement stmt = conn.createStatement();
    ResultSet resultSet = stmt.executeQuery(sql);
    while (resultSet.next()) {
        String id = resultSet.getString("id");       
        String name = resultSet.getString("name");                 
        System.out.println(id);
        System.out.println(name);
    }
    
    resultSet.close();
    stmt.close();

    prepareStatement メソッドを使用して SQL 文を作成する

    // ビジネス要件に基づいて SQL 文を作成します。次のサンプルコードは、test_table テーブルで指定されたプライマリキーを持つデータをクエリする方法を示しています。
    String sql = "SELECT * FROM test_table WHERE pk = ?";
    
    PreparedStatement stmt = connection.prepareStatement(sql);
    stmt.setLong(1, 1);
    ResultSet resultSet = stmt.executeQuery();
    ResultSetMetaData metaData = resultSet.getMetaData();
    while (resultSet.next()) {
        int columnCount = metaData.getColumnCount();
        for (int i=0; i< columnCount;i++) {
            String columnName = metaData.getColumnName(i+1);
            String columnValue = resultSet.getString(columnName);
            System.out.println(columnName);
            System.out.println(columnValue);
        }
    }
    
    resultSet.close();
    stmt.close();

完全なサンプルコード

次のサンプルコードは、中国(杭州)リージョンの myinstance インスタンスの test_table テーブルのすべてのデータをクエリする方法を示しています。

public class Demo {
    public static void main(String[] args) throws SQLException, ClassNotFoundException {

        Class.forName("com.alicloud.openservices.tablestore.jdbc.OTSDriver");

        String url = "jdbc:ots:https://myinstance.cn-hangzhou.ots.aliyuncs.com/myinstance";
        String user = "************************";
        String password = "********************************";
        Connection conn = DriverManager.getConnection(url, user, password);

        String sql = "SELECT * FROM test_table";
        Statement stmt = conn.createStatement();
        ResultSet resultSet = stmt.executeQuery(sql);
        ResultSetMetaData metaData = resultSet.getMetaData();
        while (resultSet.next()) {
            int columnCount = metaData.getColumnCount();
            for (int i=0; i< columnCount;i++) {
                String columnName = metaData.getColumnName(i+1);
                String columnValue = resultSet.getString(columnName);
                System.out.println(columnName);
                System.out.println(columnValue);
            }
        }
        resultSet.close();
        stmt.close();
        conn.close();    // 接続を閉じます。閉じないと、プログラムが終了できません。
    }
}           

設定項目

Tablestore 用 JDBC ドライバは、Java 用 Tablestore SDK に基づいて実装されています。 JDBC を使用して、Java 用 Tablestore SDK の設定項目を変更できます。次の表に、一般的な設定項目を示します。

重要

SQL リクエストの時間が 30 秒を超えると、サーバーはタイムアウトエラーを返します。タイムアウト時間を短く設定する場合は、syncClientWaitFutureTimeoutInMillis 項目を 30,000 ミリ秒より小さい値に設定します。setQueryTimeout メソッドを使用して、文ごとに個別のタイムアウト時間を指定できます。

設定項目

説明

enableRequestCompression

false

リクエストデータを圧縮するかどうかを指定します。デフォルト値:false。有効な値:

  • true:リクエストデータを圧縮します。

  • false:リクエストデータを圧縮しません。

enableResponseCompression

false

レスポンスデータを圧縮するかどうかを指定します。デフォルト値:false。有効な値:

  • true:レスポンスデータを圧縮します。

  • false:レスポンスデータを圧縮しません。

ioThreadCount

2

HttpAsyncClient の IOReactor スレッド数。デフォルト値は vCPU の数と同じです。

maxConnections

300

許可される HTTP 接続の最大数。

socketTimeoutInMillisecond

30000

ソケット層でのデータ送信のタイムアウト時間。単位:ミリ秒。値 0 は無期限の待機を示します。

connectionTimeoutInMillisecond

30000

接続設定のタイムアウト時間。単位:ミリ秒。値 0 は無期限の待機を示します。

retryThreadCount

1

スレッドプールでリトライを実行するために使用されるスレッドの数。

syncClientWaitFutureTimeoutInMillis

-1

非同期待機のタイムアウト時間。単位:ミリ秒。

connectionRequestTimeoutInMillisecond

60000

リクエストを送信するためのタイムアウト時間。単位:ミリ秒。

retryStrategy

default

リトライポリシー。有効な値:

  • disable:リクエストをリトライしません。

  • default:OTSNotEnoughCapacityUnit、OTSTableNotReady、OTSPartitionUnavailable、OTSServerBusy、OTSQuotaExhausted、OTSTimeout、OTSInternalServerError、および OTSServerUnavailable エラーの場合、タイムアウトになるまでリクエストをリトライします。

retryTimeout

10

リトライのタイムアウト時間とタイムアウト時間の単位。タイムアウト時間の単位:

  • seconds

  • milliseconds

  • microseconds

  • nanoseconds

  • minutes

  • hours

retryTimeoutUnit

seconds

データ型の変換

Tablestore は、Integer、Double、String、Binary、Boolean の 5 つのデータ型をサポートしています。 Java 用 Tablestore SDK と JDBC を使用して Tablestore にアクセスする場合、JDBC ドライバは Java と Tablestore 間のデータ型を自動的に変換できます。

Java データ型を Tablestore データ型に変換する

PreparedStatement メソッドを使用して SQL 文のパラメータの値を指定する場合、Java の Byte、Short、Int、Long、BigDecimal、Float、Double、String、CharacterStream、Bytes、および Boolean データ型を Tablestore の SQL エンジンに渡すことができます。

PreparedStatement stmt = connection.prepareStatement("SELECT * FROM t WHERE pk = ?");
stmt.setLong(1, 1);                                // データ型は変換可能です。
stmt.setURL(1, new URL("https://aliyun.com/"));    // データ型は変換できず、システムは例外をスローします。

Tablestore データ型を Java データ型に変換する

ResultSet メソッドを使用して SQL クエリの結果を取得する場合は、次の表の変換ルールに注意してください。次の表に、Tablestore データ型から Java データ型への自動変換のルールを示します。

上記と同じです。上記と同じです。

Tablestore のデータ型

変換ルール

Integer

  • システムがデータ型を整数型に変換する場合、元の値が整数型の値の範囲外であると、システムは例外をスローします。

  • システムがデータ型を浮動小数点型に変換する場合、変換された値の精度は元の値の精度よりも低くなります。

  • システムがデータ型を文字列型またはバイナリ型に変換する場合、変換された値は、元の値を toString()を使用して処理した結果と同じになります。

  • システムがデータ型をブール型に変換し、元の値がゼロ以外の値である場合、変換された値は true になります。

Double

String

  • システムがデータ型を整数型または浮動小数点型に変換する場合、解析に失敗すると、システムは例外をスローします。

  • システムがデータ型をブール型に変換し、元の文字列が true である場合、変換された値は true になります。

Binary

Boolean

  • システムがデータ型を整数型または浮動小数点型に変換し、元の値が true である場合、変換された値は 1 になります。元の値が false の場合、変換された値は 0 になります。

  • システムがデータ型を文字列型またはバイナリ型に変換する場合、変換された値は、元の値を toString()を使用して処理した結果と同じになります。

Statement stmt = conn.createStatement();
ResultSet resultSet = stmt.executeQuery("SELECT count(*) FROM t");
while (resultSet.next()) {
    resultSet.getLong(1);               // データ型は変換可能です。
    resultSet.getCharacterStream(1);    // データ型は変換できず、システムは例外をスローします。
}

Tablestore と Java 間のデータ型変換の詳細については、次の表を参照してください。

説明

次の表では、チェックマーク(✓)は通常の変換を示し、チルダ(〜)は変換中に例外がスローされる可能性があることを示し、クロス(×)は変換を実行できないことを示します。

データ型

Integer

Double

String

Binary

Boolean

Byte

~

~

~

~

Short

~

~

~

~

Int

~

~

~

~

Long

~

~

~

BigDecimal

~

~

Float

~

~

Double

~

~

String

CharacterStream

×

×

×

Bytes

Boolean

関連情報

  • SQL 文を実行してデータクエリと計算を高速化する場合、セカンダリインデックスまたは 多次元インデックス を作成できます。詳細については、「インデックス選択ポリシー」および「計算プッシュダウン」をご参照ください。

  • MaxCompute、Spark、Hive、HadoopMR、Function Compute、Flink、PrestoDB などの計算エンジンを使用して、テーブル内のデータの計算と分析を行うこともできます。詳細については、「概要」をご参照ください。

  • データを視覚化するには、Grafana を使用できます。たとえば、Grafana を使用して Tablestore データをグラフに表示できます。詳細については、「Tablestore を Grafana に接続する」をご参照ください。