Tablestore は、SQL 文を実行して Tablestore にアクセスするために使用できる Java Database Connectivity(JDBC)ドライバを提供します。このトピックでは、JDBC を使用して Tablestore にアクセスする方法について説明します。
注意事項
SQL クエリ機能は、中国(杭州)、中国(上海)、中国(北京)、中国(張家口)、中国(ウランチャブ)、中国(深圳)、中国(成都)、中国(香港)、日本(東京)、シンガポール、マレーシア(クアラルンプール)、英国(ロンドン)、米国(シリコンバレー)、インドネシア(ジャカルタ)、ドイツ(フランクフルト)、SAU(リヤド - パートナーリージョン)、および米国(バージニア)の各リージョンでご利用いただけます。
前提条件
RAM ユーザーとしてデータをクエリする場合、RAM ユーザーが作成され、すべての SQL 操作権限が RAM ユーザーに付与されます。 RAM ユーザーにすべての SQL 操作権限を付与するには、RAM ユーザーにアタッチされているカスタムポリシーで
"Action": "ots:SQL*"を設定します。詳細については、「RAM ポリシーを使用して RAM ユーザーに権限を付与する」をご参照ください。AccessKey ID と AccessKey シークレットで構成される AccessKey ペアを取得します。詳細については、「AccessKey ペアを作成する」をご参照ください。
データテーブルを作成し、データテーブルのマッピングテーブルを作成します。詳細については、「ステップ 3:データテーブルを作成する」および「テーブルのマッピングテーブルを作成する」をご参照ください。
手順
ステップ 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 にアクセスする
Class.forName()を使用して、Tablestore 用の JDBC ドライバを読み込みます。Tablestore 用 JDBC ドライバの名前は、
com.alicloud.openservices.tablestore.jdbc.OTSDriverです。Class.forName("com.alicloud.openservices.tablestore.jdbc.OTSDriver");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&...¶mN=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);
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。有効な値:
|
enableResponseCompression | false | レスポンスデータを圧縮するかどうかを指定します。デフォルト値:false。有効な値:
|
ioThreadCount | 2 | HttpAsyncClient の IOReactor スレッド数。デフォルト値は vCPU の数と同じです。 |
maxConnections | 300 | 許可される HTTP 接続の最大数。 |
socketTimeoutInMillisecond | 30000 | ソケット層でのデータ送信のタイムアウト時間。単位:ミリ秒。値 0 は無期限の待機を示します。 |
connectionTimeoutInMillisecond | 30000 | 接続設定のタイムアウト時間。単位:ミリ秒。値 0 は無期限の待機を示します。 |
retryThreadCount | 1 | スレッドプールでリトライを実行するために使用されるスレッドの数。 |
syncClientWaitFutureTimeoutInMillis | -1 | 非同期待機のタイムアウト時間。単位:ミリ秒。 |
connectionRequestTimeoutInMillisecond | 60000 | リクエストを送信するためのタイムアウト時間。単位:ミリ秒。 |
retryStrategy | default | リトライポリシー。有効な値:
|
retryTimeout | 10 | リトライのタイムアウト時間とタイムアウト時間の単位。タイムアウト時間の単位:
|
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 |
|
Double | 上記と同じです。|
String |
|
Binary | 上記と同じです。|
Boolean |
|
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 に接続する」をご参照ください。