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

Tablestore:JDBC を使用して Tablestore にアクセスする

最終更新日:Dec 28, 2024

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 ユーザーのアクセスキー ID とアクセスキーシークレットを指定します。

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

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

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

    user

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

    Alibaba Cloud アカウントまたは RAM ユーザーのアクセスキー ID。

    password

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

    Alibaba Cloud アカウントまたは RAM ユーザーのアクセスキーシークレット。

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

    • URL を使用してアクセスキーペアと設定項目を渡す

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

      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 データ型への自動変換のルールについて説明しています。

上記Integer型と同様です。上記Integer型と同様です。

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

関連情報