OBKV-HBaseクライアントを使用してクラスタに接続する

OBKV-HBaseは、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>

ステップ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を取得できます。

  1. OceanBaseクラウドプラットフォームにログインします。
  2. 左側のナビゲーションペインで**クラスタを選択し、下にスクロールしてクラスタリスト**を見つけます。
  3. アクセスしたいクラスタ名をクリックして開きます。
  4. クラスタの詳細ページで**ConfigURL**パラメータを見つけます。このパラメータはクライアントの初期化時に設定する必要があります。

• OBDを使用してConfig Serverをデプロイし、Config URLを取得する

  OCPを使用していない場合は、[コマンドラインを使用してConfig Serverをデプロイする必要があり、ObRootServiceInfoUrlを取得する必要があります。

クラウドモードの設定（パブリッククラウド）

## 現在のクラスタは以下のように仮定します
## DataBaseName: test
## UserName：root

#### 必須項目
Configuration conf = new Configuration();

## データベースの新規ユーザー名、3段階ではなく、usernameを使用します
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は以下の方法で取得できます。OB 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は、テーブルプールモードを提供し、複数のテーブルを管理する操作インスタンスをサポートします。現在、リソースプールにはReusable、RoundRobin、ThreadLocalの3つの方式が含まれています。テーブルプールをインスタンス化する際に、使用するモードを指定できます。

使用方法はHBaseのHTablePoolと同じです。特定のテーブルのHTableが必要な場合は、pool.getTable("xx") を使用して対応するHTableを取得します。注意点は以下の通りです：

• パラメータの優先順位：テーブル専用パラメータ（例：pool.setOdpAddr()など）> Confで設定されたパラメータ > デフォルトパラメータ。
• HTableの使用後はclose()を忘れずに、OHTableをプールに返却してください。try/finallyを使用してHTableを返却することを推奨します。

// configurationの設定は前のセクションをご参照ください。ここでは詳細は記述しません。
Configuration conf = new Configuration(); // 設定パラメータの作成
conf.set(xxx);  // 各種設定パラメータの設定

// maxSizeの初期化。pool内の各テーブルの最大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"); // 対応するテーブルのHTableを取得
// 関連するロジックの実行
hTable.close(); // tableをpoolに返却

OBKV-HBaseクライアントの構成パラメータ

接続パラメータに加えて、Configurationを通じてその他のパラメータを設定することができます。以下の例では、クライアントのRPCタイムアウト時間を3秒に設定しています。

conf.set("rpc.execute.timeout", "3000");

よく使われるパラメータの一覧

OHTableの設定

Configurationに加えて、OHTableのインターフェースを通じて個々のOHTableのパラメータを設定することもできます：

対応するHBase操作

上記の手順でクライアントを初期化した後、操作を開始できます。この記事では、一部のOHTableインターフェース操作について説明します。より詳細なインターフェース情報については、OHTable.javaをご参照ください。

関連するOBKV-HBaseの使用デモは、OBKV-HBase使用デモをご参照ください。

次のステップ

• OBKV-HBaseクライアントをデプロイし、クラスタへの接続を確立したら、データに対する操作を実行できます。具体的なデータ操作の例については、データ操作の例に関するドキュメントをご参照ください。