OBKV-HBaseクライアントを使用すると、OBKV-HBaseクラスタに接続し、HBase互換のAPIでデータを処理できます。既存の業務でネイティブHBaseのデータ操作ロジックを使用している場合、OceanBaseデータベースクラスタをデプロイし、OBServer側にHBaseテーブルを作成し、OBKV-HBaseクライアントを通じてデータ操作を実行できます。本記事では、クライアントの設定、OBServerへの接続、および基本的な追加・削除・変更・検索操作の方法について説明します。
OBKV-HBaseクライアント
OBKV-HBaseクライアントは、OBKV-HBaseが提供する基本インターフェースに基づき、クライアント側でHBase互換のAPIを提供します。現在、HBase 0.94の機能と互換性があります。
前提条件
OBKV-HBaseクライアントを使用してOBKV-HBaseクラスタに接続し、データ処理を行う前に、以下の準備作業を完了していることを確認してください:
- OBKVクラスタを作成済みであること。サポートされているデプロイメントプラン、デプロイ方法、および詳細なデプロイ操作については、クラスタの作成を参照してください。
- OBKVテナントを作成済みであること。テナント作成の詳細な操作については、テナントの作成を参照してください。
- データベースを作成済みであること。
- OBKV-HBaseデータテーブルを作成済みであること。OBKV-HBaseデータテーブルの作成手順の詳細については、データベーススキーマ設計を参照してください。
テーブル作成例:
-- まず、テーブルグループ htable1 を作成します
CREATE TABLEGROUP htable1;
-- htable1 テーブルグループにバインドされたテストテーブル htable1$family1 を作成します
CREATE TABLE htable1$family1 (
K varbinary(1024),
Q varbinary(256),
T bigint,
V varbinary(1048576) NOT NULL,
PRIMARY KEY(K, Q, T))
TABLEGROUP = htable1;
ステップ1:クライアント依存関係の追加
OBKV-HBaseクライアントのJARパッケージ依存関係をローカルJavaプロジェクトのpom.xmlファイルに追加します(または OBKV-HBase使用デモを参照してください)。
<dependency>
<groupId>com.oceanbase</groupId>
<artifactId>obkv-hbase-client</artifactId>
<version>0.1.4</version>
</dependency>
注意
- 可能な限り最新バージョンのJARパッケージを使用してください。古いバージョンのJARパッケージは新しいサーバーバージョンと互換性がない場合があります。
- ここでのバージョン番号は最新ではない場合があります。中央リポジトリで公開されているOBKV-HBaseのバージョンを参照し、バージョン番号を最新の公開バージョン番号に置き換えてください。
ステップ2:クライアント接続パラメータの設定
OBKV-HBaseはパブリッククラウドとプライベートデプロイメント方式で異なり、設定が必要なクライアント接続パラメータも異なります。OceanBaseクラスタをプライベートデプロイメントしている場合は、直接接続モードの設定を参照してください。パブリッククラウドのOBKVサービスを使用している場合は、クラウドモードの設定を参照してください。
直接接続モードの設定 (プライベートデプロイメント)
## 現在のクラスタは以下のように仮定します
## ClusterName:obkvcluster
## TenantName:obkv
## DataBaseName: test
## UserName:root
## SYS_USER_NAME : sysroot
#### 必須項目
Configuration conf = new Configuration();
## フォーマットはuserName@tenantName#clusterNameです
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root@obkv#obkvcluster");
## fullUserName内のuserNameでOceanBaseに接続するためのパスワード
conf.set(HBASE_OCEANBASE_PASSWORD, "");
## obconfig serverからRSlistを取得するURL。詳細はConfig URLの取得を参照してください
conf.set(HBASE_OCEANBASE_PARAM_URL, "");
## システムテナント内のユーザー名。ルーティングテーブルにアクセスできるのはシステムテナント内のユーザーのみです
conf.set(HBASE_OCEANBASE_SYS_USER_NAME, "sysroot");
## システムテナント内のユーザーパスワード
conf.set(HBASE_OCEANBASE_SYS_PASSWORD, "");
#### オプション
## リクエストの実行タイムアウト時間(業務特性に基づいて選択)。単位はmsです。以下はタイムアウト時間1秒を示します
conf.set("rpc.execute.timeout", "1000");
以下の方法でConfig URLを取得できます。
OCPからConfig URLを取得する
OCPを使用している場合、OCPからConfig URLを取得できます。
- OceanBase Cloud Platform(OCP)にログインします。
- 左側のナビゲーションバーで クラスタ を選択し、下にスクロールして クラスタリスト を見つけます。
- アクセスしたいクラスタ名をクリックします。
- クラスタの詳細ページで ConfigURL パラメータを見つけます。このパラメータはクライアントの初期化時に設定する必要があります。
OBDを使用してConfig Serverをデプロイし、Config URLを取得する
OCPを使用していない場合は、コマンドラインを使用してConfig Serverをデプロイする必要があり、ObRootServiceInfoUrlを取得する必要があります。
クラウドモードの設定(パブリッククラウド)
## 現在のクラスタの設定を次のように仮定します
## DataBaseName: test
## UserName:root
#### 必須項目
Configuration conf = new Configuration();
## データベースで作成したユーザー名のみを指定します。テナント名とクラスタ名は含めません。
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root");
## ユーザーのパスワード
conf.set(HBASE_OCEANBASE_PASSWORD, "");
## ODP Addressの備考を参照してください
conf.set(HBASE_OCEANBASE_ODP_ADDR, "");
## OBKVのポートは3307です(固定)
conf.setInt(HBASE_OCEANBASE_ODP_PORT, "3307");
## クラウドでODPモードを使用する場合(固定)
conf.setBoolean(HBASE_OCEANBASE_ODP_MODE, true);
## データベース名
conf.set(HBASE_OCEANBASE_DATABASE, "test");
#### オプション
## リクエストの実行タイムアウト時間(業務特性に応じて設定)
conf.set("rpc.execute.timeout", "1000");
ODP Addressは以下の方法で取得できます。OceanBase Cloudテナントのダッシュボードにアクセスし、デプロイメント関係図を確認します。
OceanBaseクラスタへの接続
クライアント接続パラメータの設定が完了したら、クライアントの初期化を開始します。現在、OHTableClientとOHTablePoolの2つの方法がサポートされています。その違いは以下のとおりです:
- OHTableClient:スレッドセーフではありません。内部には1つのOHTableハンドルしかなく、複数のスレッドが同じOHTableに同時にアクセスすると予測不可能な問題が発生する可能性があります(単一スレッドシナリオで使用)。
- OHTablePool:OHTableプールです。必要に応じてプールから対応するテーブルのOHTableインスタンスを取得して使用します(マルチスレッドシナリオで使用)。
OHTableを介した接続
// configurationの設定は前のセクションを参照してください。ここでは詳述しません。
Configuration conf = new Configuration(); // 設定パラメータの作成
conf.set(xxx); // 各種設定パラメータの設定
OHTableClient hTable = new OHTableClient("test1", conf); // hTableオブジェクトの作成
hTable.init(); // hTableの初期化
// 関連するロジックの実行
hTable.close(); // hTableオブジェクトのクローズ
OHTablePoolによる接続
OBKV-HBaseは、複数のTableの操作インスタンスを管理するためのテーブルプール方式を提供しています。現在、リソースプールにはReusable、RoundRobin、ThreadLocalの3つの方式が含まれています。Table poolをインスタンス化する際に、使用するモードを指定できます。
HBaseのHTablePoolと同じ方法で使用します。特定のTableのHTableが必要な場合は、pool.getTable("xx") を使用して対応するHTableを取得します。注意点は以下の通りです:
- パラメータの使用優先順位:Table専用パラメータ(例:pool.setOdpAddr()など)> Confで設定されたパラメータ > デフォルトパラメータ。
- HTableの使用後は必ずclose()を行い、OHTableをPoolに返却してください。try/finallyを使用してHTableを返却することを推奨します。
// configurationの設定は前のセクションを参照してください。ここでは詳述しません。
Configuration conf = new Configuration(); // 設定パラメータの作成
conf.set(xxx); // 各種設定パラメータの設定
// maxSizeの初期化。pool内の各Tableの最大HTable参照数を表すために使用されます。
int maxSize = 100;
// poolTypeの初期化。Reusable、ThreadLocal、RoundRobinの3種類があります。ThreadLocalの使用を推奨します。
PoolMap.PoolType poolType = PoolMap.PoolType.ThreadLocal;
OHTablePool pool = new OHTablePool(conf, maxSize, poolType);
HTableInterface hTable = pool.getTable("test"); // 対応するTableのHTableを取得
// 関連するロジックの実行
hTable.close(); // tableをpoolに返却
OBKV-HBaseクライアントの構成パラメータ
接続パラメータに加えて、Configurationを通じてその他の構成パラメータを設定できます。以下の例では、クライアントのRPCタイムアウト時間を3秒に設定しています。
conf.set("rpc.execute.timeout", "3000");
よく使われる構成パラメータ
構成パラメータ |
説明 |
デフォルト値 |
|---|---|---|
| HBASE_OCEANBASE_FULL_USER_NAME | ユーザー名。接続モード別の指定方法はステップ2:クライアント接続パラメータの設定を参照してください | 空 |
| HBASE_OCEANBASE_PASSWORD | ユーザーパスワード | 空 |
| HBASE_OCEANBASE_PARAM_URL | obconfig serverからRSlistを取得するURL | 空 |
| HBASE_OCEANBASE_SYS_USER_NAME | システムテナント内のユーザー名 | 空 |
| HBASE_OCEANBASE_SYS_PASSWORD | システムテナント内のユーザーパスワード | 空 |
| HBASE_OCEANBASE_ODP_MODE | クラウド上の設定を使用するかどうか | False |
| HBASE_OCEANBASE_ODP_ADDR | ODP Address。詳細はステップ2:クライアント接続パラメータの設定を参照してください | 空 |
| HBASE_OCEANBASE_ODP_PORT | ODP Port。詳細はステップ2:クライアント接続パラメータの設定を参照してください | 空 |
| HBASE_OCEANBASE_DATABASE | クラウド上で使用するデータベースの名前 | 空 |
rpc.connect.timeout |
RPC接続確立のタイムアウト時間、単位ms | 1000ms |
rpc.execute.timeout |
RPCリクエスト実行のソケットタイムアウト時間、単位ms | 3000ms |
rpc.operation.timeout |
OceanBase内部でのRPCリクエスト実行タイムアウト時間、単位ms。rpc.execute.timeoutと同じ値に設定することを推奨します | 10000ms |
metadata.refresh.interval |
METADATAのリフレッシュ時間間隔、単位ms | 60000ms |
runtime.continuous.failure.ceiling |
連続運用失敗の上限。この値に達するとTABLE情報がリフレッシュされます | 100 |
bolt.netty.buffer.low.watermark |
Netty書き込みバッファの下限しきい値 | 512*1024(512K) |
bolt.netty.buffer.high.watermark |
Netty書き込みバッファの上限しきい値 | 1024*1024(1M) |
runtime.retry.interval |
実行エラー時のリトライ時間間隔 | 1 |
runtime.retry.times |
実行エラー時のリトライ回数 | 1 |
OHTableの設定
Configurationに加えて、OHTableのインターフェースを通じて個々のOHTableの構成パラメータを設定することもできます。
メソッド |
説明 |
デフォルト値 |
|---|---|---|
setAutoFlush() |
auto-flushを設定します | True |
setWriteBufferSize() |
書き込みバッファサイズを設定します | 2097152 Byte |
対応するHBase操作
上記の手順でクライアントを初期化した後、操作を開始できます。この章では、一部のOHTableインターフェース操作について説明します。より詳細なインターフェース情報については、OHTable.javaを参照してください。
関連するOBKV-HBaseの使用デモについては、OBKV-HBase使用デモを参照してください。
次のステップ
- OBKV-HBaseクライアントをデプロイし、クラスタへの接続を確立したら、データに対する操作を実行できます。具体的なデータ操作の例については、データ操作の例を参照してください。