OBKV-HBaseクライアントは、HTableInterfaceインターフェースを実装しています。本記事では、OBKV-HBaseがオープンソースのHBaseインターフェースに対してどの程度互換性を持つかを説明します。
インターフェースの互換性
修飾子とタイプ |
メソッドと説明 |
互換性 |
|---|---|---|
| Result | append (Append append) 単一の行に1つまたは複数の列の値を追加します。 | サポート |
| Object[] | batch(List<? extends Row> actions) batch(List, Object[])と同じですが、結果パラメータではなく結果配列を返します。 |
サポートなし |
| void | batch(List<? extends Row> actions, Object[] results) Deletes、Gets、Puts、Increments、Appends、およびRowMutationsメソッドを一括呼び出します。 | サポートなし |
| boolean | checkAndDelete (byte[] row, byte[] family, byte[] qualifier, byte[] value,Delete delete) 行・カラムファミリー・列修飾子で指定されるセルの値が期待値と一致するかどうかを原子的にチェックします。 |
サポート |
| boolean | checkAndPut (byte[] row, byte[] family, byte[] qualifier, byte[] value, Put put) 行・カラムファミリー・列修飾子で指定されるセルの値が期待値と一致するかどうかを原子的にチェックします。 |
サポート |
| void | close() 内部バッファ内のリソースや保留中の変更を解放します。 | サポート |
| <T extends CoprocessorProtocol,R>Map<byte[],R> | coprocessorExec(Class<T> protocol, byte[] startKey, byte[] endKey, Batch.Call<T,R> callable) 指定された範囲内で実行されている CoprocessorProtocol インスタンスに対して、渡された Batch.Call を呼び出します。 | サポートなし |
| <T extends CoprocessorProtocol,R> void | coprocessorExec(Class<T> protocol, byte[] startKey, byte[] endKey,Batch.Call<T,R> callable,Batch.Callback<R> callback) 指定された範囲内で実行されている CoprocessorProtocol インスタンスに対して、渡された Batch.Call を呼び出します。 | サポートなし |
| <T extends CoprocessorProtocol > T | coprocessorProxy(Class<T> protocol, byte[] row) 指定された行を含む範囲内で実行される CoprocessorProtocol インスタンスのプロキシを作成して返します。 | サポートなし |
| void | delete(Delete delete) 指定されたセル/行を削除します。 | サポート |
| void | delete(List<Delete> deletes) 指定されたセル/行を一括削除します。 | サポート |
| boolean | exists(Get get) 表にGetで指定された列が存在するかどうかを確認します。 | サポート |
| void | flushCommits() バッファされているすべてのPut操作を実行します。 | サポート |
| Result | get(Get get) 指定された行から特定のセルを抽出します。 | サポート |
| Result[] | get(List<Get> gets) 指定された行から一括で特定のセルを抽出します。 | サポート |
| org.apache.hadoop.conf.Configuration | getConfiguration() このインスタンスで使用されているConfigurationオブジェクトを返します。 | サポート |
| Result | getRowOrBefore(byte[] row, byte[] family) このメソッドはバージョン0.92以降、非推奨となっており、代替メソッドはありません。getRowOrBeforeは.META.内でエントリを検索し、効率を向上させるために、いくつかの仮定(これらの仮定は.META.については正しいが、一般的な場合には当てはまらない)を立てます。 | Deprecated |
| ResultScanner | getScanner(byte[] family) 指定されたカラムファミリーのスキャナーを取得します。 | サポート |
| ResultScanner | getScanner(byte[] family, byte[] qualifier) 指定されたカラムファミリーと列修飾子のスキャナーを取得します。 | サポート |
| ResultScanner | getScanner(Scan scan) Scanオブジェクトの指定に基づいて、現在のテーブル上のスキャナーを返します。 | サポート |
| HTableDescriptor | getTableDescriptor() このテーブルの table descriptorを取得します。 | サポートなし |
| byte[] | getTableName() このテーブルの名前を取得します。 | サポート |
| long | getWriteBufferSize() この HTable の最大書き込みバッファサイズ(バイト単位)を返します。 | サポート |
| Result | increment(Increment increment) 単一行内で1つまたは複数の列の値を増分します。 | サポート |
| long | incrementColumnValue(byte[] row, byte[] family, byte[] qualifier, long amount) 列の値を原子的に増分します。 | サポート |
| long | incrementColumnValue(byte[] row, byte[] family, byte[] qualifier, long amount, Durability durability) 列の値を原子的に増分します。 | サポート |
| boolean | isAutoFlush() '自動フラッシュ'が有効かどうかを確認します。 | サポート |
| RowLock | lockRow(byte[] row) 行ロックを取得します。 | サポートなし |
| void | mutateRow(RowMutations rm) 単一行に対して複数の原子操作を実行します。 | サポートなし |
| void | put(List<Put> puts) データを一括挿入します。 | サポート |
| void | put(Put put) データを挿入します。 | サポート |
| void | setAutoFlush(boolean autoFlush) 自動フラッシュを設定します。 | サポート |
| void | setAutoFlush(boolean autoFlush, boolean clearBufferOnFail) 自動フラッシュを有効にするかどうか、および失敗時にバッファをクリアするかどうかを設定します。 | サポート |
| void | setWriteBufferSize(long writeBufferSize) 書き込みバッファサイズを設定します。 | サポート |
| void | unlockRow(RowLock rl) 行ロックを解除します。 | サポートなし |
| void | setBatch、バッチ処理を設定します。 | サポート |
| void | setCaching、キャッシュを設定します。 | サポート |
| void | setMaxResultSize、最大結果サイズを設定します。 | サポート |
| void | setAllowPartialResults、部分的な結果を許可するかどうかを設定します。 | サポート |
| void | checkExistenceOnly、存在性のみをチェックするかどうかを設定します。 | サポート |
| void | checkAndMutate、チェックして変更するかどうかを設定します。 | サポート |
| void | connection、接続を設定します。 | サポート |
| void | ohBufferedMutatorImpl、バッファ変更子の実装を設定します。 | サポート |
インターフェースの使用上の違い
アーキテクチャ実装の違いにより、オープンソースHBaseのコードをOBKV-HBaseに移行する際は、一部の設定コードを調整する必要があります。
違いの説明
オープンソースHBaseとOBKV-HBaseのデータアクセス部分には互換性があり、データアクセスのコードを変更する必要はありません。主な相違点は次のとおりです。
- Configuration:オープンソースHBaseとOBKV-HBaseのアーキテクチャが異なるため、構成パラメータも異なります。
- OHTableClient:OBKV-HBaseのハンドルを使用してデータにアクセスします。
コード例
オープンソースHBaseのコード:
public class HBaseInsertDemo {
public static void main(String[] args) throws Exception {
// HBaseの設定
Configuration conf = HBaseConfiguration.create();
conf.set("hbase.zookeeper.quorum", "your_zookeeper_quorum"); // ZooKeeperアドレスの設定
conf.set("hbase.zookeeper.property.clientPort", "2181"); // ZooKeeperポートの設定
// Tableハンドルの取得
TableName tableName = TableName.valueOf("your_table_name");
HTable table =new HTable(tableName, conf);
// データ挿入の準備
Put put = new Put(Bytes.toBytes("row_key"));
put.addColumn(Bytes.toBytes("cf"), Bytes.toBytes("qualifier"), Bytes.toBytes("value")); // カラムファミリ、列識別子、値
table.put(put);
// リソースのクローズ
table.close();
System.out.println("データの挿入に成功しました!");
}
}
OBKV-HBaseのコード:
public class OBHBaseInsertDemo {
public static void main(String[] args) throws Exception {
// HBaseの設定
Configuration conf = new Configuration();
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "");
conf.set(HBASE_OCEANBASE_PASSWORD, "");
conf.set(HBASE_OCEANBASE_PARAM_URL, "");
conf.set(HBASE_OCEANBASE_SYS_USER_NAME, "");
conf.set(HBASE_OCEANBASE_SYS_PASSWORD, "");
// Tableハンドルの取得
TableName tableName = TableName.valueOf("your_table_name");
OHTableClient table = new OHTableClient(tableName, conf); // htableオブジェクトの作成
// データ挿入の準備
Put put = new Put(Bytes.toBytes("row_key"));
put.addColumn(Bytes.toBytes("cf"), Bytes.toBytes("qualifier"), Bytes.toBytes("value")); // カラムファミリ、列識別子、値
table.put(put);
// リソースのクローズ
table.close();
System.out.println("データの挿入に成功しました!");
}
}
インターフェースの説明と例
scanクラスのインターフェース説明と例
scanクラスの一部のインターフェースをサポートしています。これには、setBatch、setCaching、setMaxResultSize、setAllowPartialResults、isCacheBlockが含まれます。
setBatch
next() の呼び出しごとに返される最大セル数を設定します。クライアント側でページネーションクエリを実装するために使用されます。
public scan setBatch(int batch);
setCaching
1回のRPCでサーバーが返す行数を制限します。デフォルトでは制限はありません。クライアントは大きな caching 値を設定することで、1回のRPCで取得するデータ量を増やし、クエリの処理速度を向上させることができます。また、小さな caching 値を設定することで、クライアントのメモリ消費を抑え、OOMを回避することができます。
public scan setCaching(int caching);
setMaxResultSize
1回のRPCでサーバーが返すデータの最大バイト数を制限します。デフォルトでは制限はありません。
public scan setMaxResultSize(long maxResultSize);
setAllowPartialResults
ユーザーに対して行の一部を返すことを許可するかどうかを設定します。これにより、単一行のデータが長すぎてクライアントでOOMが発生するのを防ぎます。デフォルトは false です。この場合、ユーザーが setMaxResultSize を設定して返すデータ量を制限しても、サーバーは毎回少なくとも1行分の完全なデータをクライアントに返します。
public scan setAllowPartialResults(final boolean allowPartialResults);
setCacheBlocks
クエリの結果セットをOBのrowCache/BlockCacheにキャッシュするかどうかを設定します。デフォルトは true です。例えば、フルテーブルスキャンを行う際には false に設定することで、キャッシュを汚染するのを避けることができます。
public scan setCacheBlocks(boolean cacheBlocks);
renew
クエリ結果セットの有効期限を設定します。デフォルトは 0 で、有効期限を設定しないことを意味します。
ResultScanner.renewLease() メソッドは、ResultScannerの有効期限(lease)を延長する役割があります。HBaseでは、ResultScannerにはデフォルトで有効期限(60000ms)が設定されており、この期間内にデータを読み取らない場合、スキャナーは自動的に閉じます。renewLease() メソッドを呼び出すことで、ResultScannerの状態を更新し、有効期限を再計算して、スキャナーを開いたままにできる時間を延長することができます。
OBKV-HBaseでは、ResultScannerの有効期限は kv_hbase_client_scanner_timeout_period で調整します。
例:
ResultScanner scanner = hTable.getScanner(scan);
Thread.sleep(5 * 1000);
scanner.next();
Thread.sleep(20 * 1000);
scanner.renewLease();
Thread.sleep(41 * 1000);
scanner.next();
withStartRow/withStopRow
Scan.withStartRow および Scan.withStopRow メソッドは、スキャンの開始行と終了行を指定するために使用され、これらの行キーを含むかどうかも指定できます。これらのメソッドは、スキャン範囲を限定し、特定の行キー範囲内のデータのみをスキャンすることを保証するのに役立ちます。
例:
// Scanオブジェクトの作成
Scan scan = new Scan();
// 開始行と終了行の設定
byte[] startRow = Bytes.toBytes("row1");
byte[] stopRow = Bytes.toBytes("row5");
scan.withStartRow(startRow);
scan.withStopRow(stopRow);
// ResultScannerの取得
ResultScanner scanner = table.getScanner(scan);
setLimit
Scan.setLimit(int limit) メソッドは、スキャンの最大結果数を設定します。このメソッドにより、1回のスキャンで返される結果数を制限し、一度に大量のデータを返すことによるメモリオーバーフローを防ぐことができます。
例:
// Scanオブジェクトを作成
Scan scan = new Scan();
// 最大結果数を設定
int limit = 100;
scan.setLimit(limit);
// ResultScannerを取得
ResultScanner scanner = table.getScanner(scan);
getクラスのインターフェース説明と例
checkExistenceOnly
Get実行で返されるResultに結果セットではなくexistsフラグ(ResultのgetExistsインターフェースで取得)のみを含めるかどうかを設定します。これは、条件を満たすデータが存在するかどうかを確認するために使用されます。
public get setCheckExistenceOnly(boolean checkExistenceOnly);
checkAndMutate
checkAndMutateはtableのインターフェースであり、同一rowに対して一括操作を行うことができます。指定されたcheckAndMutate操作は1回のRPCでRegionServerに送信できます。ネイティブのHBaseとは異なり、いずれか1つの操作が失敗した場合、残りのすべての操作はロールバックされます。
シナリオ:検証と挿入が原子操作である必要がある場合。例えば、まずその人のウォレット残高が100より大きいかどうかを検証し、大きい場合はその残高を変更してtrueを返し、100以下の場合は変更せずにfalseを返します。
パラメータ:
- row:操作する行。
- family、qualifier、value:検証が必要なセル。
- compareOp:比較演算子。
- rowMutations:その行が一致する場合に実行する操作。
戻り値:
trueまたはfalse。一致に成功したかどうかを示します。
connection
この機能は、ユーザーがデータベースに接続するためのハンドルを提供し、接続から各テーブルのハンドルを取得してデータを操作できるようにするものです。また、adminやbufferMutateなどの接続レベルのインターフェースも提供します。
TableとBufferMutator
以下は、HBaseでよく使われる接続の使い方のコードです:
Configuration conf = HBaseConfiguration.create();
conf.set(HConstants.ZOOKEEPER_QUORUM, "zk1, zk2, zk3");
conf.setInt(HConstants.ZOOKEEPER_CLIENT_PORT, 2181);
conf.set(HConstants.ZOOKEEPER_ZNODE_PARENT, "/hbase");
//Connectionはスレッドセーフなオブジェクトなので、プログラムのライフサイクル全体を通じて、Connectionオブジェクトは1つだけ作成すれば済みます。
//プログラム終了時にはConnectionオブジェクトを閉じる必要があります。そうしないと接続リークが発生します。try finallyを使用してリークを防ぐことができます。
Connection connection = ConnectionFactory.createConnection(conf);
TableName tableName = TableName.valueOf("tablename");
// Tableハンドルを取得する
Table table = connection.getTable(tableName);
// BufferMutatorを取得する
BufferedMutator ohBufferMutator = connection.getBufferedMutator(TableName);
HBaseでは、ConnectionFactoryにconfigを渡してConnectionを作成し、そのConnectionを通じて対応するテーブルを取り出して操作します。
- 方法1:Configurationを直接設定する
conf.set(ClusterConnection.HBASE_CLIENT_CONNECTION_IMPL,
"com.alipay.oceanbase.hbase.util.OHConnectionImpl");
- 方法2:設定ファイルを変更する
hbase-site.xml および hbase-default.xml にこのパラメータを追加します。優先順位は hbase-site.xml > hbase-default.xml です。
<property>
<name>hbase.client.connection.impl</name>
<value>com.alipay.oceanbase.hbase.util.OHConnectionImpl</value>
</property>
TableBuilder
TableBuilderは、HBase 2.xで導入された、HTableを定義して取得するための新しい仕組みです。ユーザーはTableBuilderに TableName、ConnectionConfiguration、rpcTimeout などを設定することで、対応するHTableを取得できます。
例:
tableBuilderを取得する
public TableBuilder getTableBuilder(TableName tableName, ExecutorService pool);注意:getTableBuilderを呼び出す前にpoolを定義している場合は、poolを手動で閉じる必要があります。HTableを閉じても、ユーザー定義のpoolは自動的には閉じません。
tableBuilderを使用してOHTableを取得する
Configuration conf = ObHTableTestUtil.newConfiguration(); conf.set(...); connection = ConnectionFactory.createConnection(conf); ExecutorService pool = ...; TableName tableName = TableName.valueOf("table_name"); TableBuilder builder = connection.getTableBuilder(tableName, pool);
接続タイムアウト時間の設定
tableClientのrpcConnectTimeoutパラメータとObTableのobTableConnectTimeoutパラメータは、Tableクライアントが初期化時および現在のテナントが存在するobserverと接続を確立する際の接続タイムアウト時間を制御します。tableClientの接続タイムアウト時間の最小値は1秒です。
OBKV-HBaseクライアントの設計:
OBKV-HBaseのTableクライアントの両方のパラメータは、ObTableClientの設定インターフェースを通じて設定できます。そのため、HBaseクライアントでTableClientオブジェクトをinitする前に設定する必要があります。
/*
* Set rpc connect timeout.
*/
public void setRpcConnectTimeout(int rpcConnectTimeout) {
this.properties.put(RPC_CONNECT_TIMEOUT.getKey(), String.valueOf(rpcConnectTimeout));
this.rpcConnectTimeout = rpcConnectTimeout;
}
旧バージョンのパラメータipc.socket.timeoutとの互換性のため、ユーザーは引き続きこのパラメータを使用して接続タイムアウト時間を設定できます。ただし、新しいパラメータhbase.ipc.client.socket.timeout.connectの優先順位が古いパラメータよりも高くなります。つまり、ユーザーが古いパラメータのみを設定し、新しいパラメータを設定していない場合にのみ、Tableクライアントは古いパラメータの設定時間を使用します。それ以外の場合は、新しいパラメータのデフォルト値または設定値が使用されます。
// SOCKET_TIMEOUT_CONNECT = "hbase. ipc. client. socket. timeout. connect"、デフォルト値は10秒
// SOCKET_TIMEOUT = "ipc. socket. timeout"、デフォルト値は20秒
int rpcConnectTimeout = -1;
// 新しいパラメータが設定されている場合、その値を直接使用します。
if (conf.get(SOCKET_TIMEOUT_CONNECT) != null) {
rpcConnectTimeout = conf
.getInt(SOCKET_TIMEOUT_CONNECT, DEFAULT_SOCKET_TIMEOUT_CONNECT);
} else {
// 新しいパラメータが設定されていないが、古いパラメータが設定されている場合は、古いパラメータを使用します。
if (conf.get(SOCKET_TIMEOUT) != null) {
rpcConnectTimeout = conf.getInt(SOCKET_TIMEOUT, DEFAULT_SOCKET_TIMEOUT);
} else { // どちらも設定されていない場合、新しいパラメータのデフォルト値を使用します。
rpcConnectTimeout = conf
.getInt(SOCKET_TIMEOUT_CONNECT, DEFAULT_SOCKET_TIMEOUT_CONNECT);
}
}
this.rpcConnectTimeout = rpcConnectTimeout;
RpcConnectTimeoutをObTableClientを作成する関数に渡して、init前に設定します。
public static ObTableClient getOrCreateObTableClient(ObTableClientKey obTableClientKey,
int rpcConnectTimeout) throws IOException {
// other code...
obTableClient.setFullUserName(obTableClientKey.getFullUserName());
obTableClient.setPassword(obTableClientKey.getPassword());
obTableClient.setRpcConnectTimeout(rpcConnectTimeout);
obTableClient.init();
OB_TABLE_CLIENT_INSTANCE.put(obTableClientKey, obTableClient);
}
} catch (Exception e) {
throw new IOException(e);
} finally {
lock.unlock();
}
}
return OB_TABLE_CLIENT_INSTANCE.get(obTableClientKey);
}
OBKV-HBaseクライアントは、既に作成されたObTableClientオブジェクトを保持し、再初期化しません。そのため、ユーザーが後からObTableClientの接続タイムアウト時間を設定したい場合、Configuration.setの方法は使用できず、対応するObTableClientオブジェクトのsetRpcConnectTimeoutインターフェースを直接使用する必要があります。
不互換インターフェース
現在の不互換インターフェースに関する説明
- getAdminは現在不互換です。
- getRegionServerなどもすべて不互換です。
- 現在、connectionはgetTable、getBufferdMutator、TableBuilderの3つのインターフェースのみを提供しています。
tableクラスのインターフェース説明と例
setRpcTimeout、getRpcTimeout:1回のRPC呼び出しのタイムアウト時間
setOperationTimeout、getOperationTimeout:1回の操作のタイムアウト時間。リトライやそれに伴う複数回のRPC呼び出しが含まれる場合があります。
BufferedMutatorインターフェースの説明と例
HBaseのBufferedMutatorと同様に、変更(mutation)操作を累積してから一括実行するために使用されます。ユーザーはバッチ処理を手動でコミットするか、OBKV BufferedMutatorが設定された累積しきい値に達したときに自動的にコミットするように選択できます。ohBufferedMutatorImplは、OBKV-HBaseにおけるBufferedMutatorの実装クラスです。
現在、OBKV-HBaseのBufferedMutatorは削除と追加操作のみをサポートしており、作成されたOBKV-HBaseのBufferedMutatorオブジェクトは1種類の変更に対してのみ一括操作を実行できます。BufferedMutator内の操作では、並行処理の順序を保証することはできず、失敗した操作がある場合でも実行順序や原子性を保証することはできません。
1.x互換性
OBKV-HBaseのBufferedMutatorは、HBaseのBufferedMutator 1.xバージョンと互換性があります。OHBufferedMutatorImpl 1.xは、OHTable 1.xのbatchインターフェースに依存しています。
機能の説明は以下の通りです:
- 同一のBufferedMutatorオブジェクトで、PutとDeleteの混合操作を実行できます。
- BufferedMutatorのPutおよびDelete操作は、複数のカラムファミリーをサポートします。
- BufferedMutator内のMutation操作数がしきい値に達すると、バッチ処理操作を実行します。自動バッチ処理操作には実行上限があり、この上限はネイティブHBaseと同じで、バッチ処理しきい値の2倍です。
- 失敗したMutation操作については、システムが回収処理を行います。
2.x互換性
OBKV-HBaseのBufferedMutatorは、HBaseのBufferedMutator 2.xバージョンと互換性があります。OHBufferedMutatorImpl 2.xは、OHTable 2.xのbatchインターフェースに依存しています。
機能の説明は以下の通りです:
- 同一のBufferedMutatorオブジェクトで、PutとDeleteの混合操作を実行できます。
- BufferedMutatorのPutおよびDelete操作は、複数のカラムファミリーをサポートします。
- BufferedMutator内部にはタイマーがあり、定期的にバッチ処理操作を実行します。バッチ処理操作ごとに、累積されたすべての操作がコミットされます。
- 失敗したMutation操作については、システムが回収処理を行います。
2.xで追加されたインターフェース:
setWriteBufferPeriodicFlushインターフェースが追加されました。これは自動コミッターを設定するために使用されます。
timeoutMsは2回の実行間隔を制御し、timerTickMsはコミッターがトリガーする間隔を制御します。例:public synchronized void setWriteBufferPeriodicFlush(long timeoutMs, long timerTickMs);disableWriteBufferPeriodicFlushインターフェースが追加されました。これは自動コミッターを無効にするために使用されます。例:
public void disableWriteBufferPeriodicFlush();
BufferedMutatorの取得方法
BufferedMutatorを取得する方法は2つあります:
- TableNameを指定してテーブル名を指定し、他はデフォルトパラメータを使用します。
public BufferedMutator getBufferedMutator(TableName tableName) throws IOException {
return getBufferedMutator(new BufferedMutatorParams(tableName));
}
- BufferedMutatorParamsを指定してカスタムパラメータを使用します。
public BufferedMutator getBufferedMutator(BufferedMutatorParams params) throws IOException {
if (params.getTableName() == null) {
throw new IllegalArgumentException("TableName cannot be null.");
}
if (params.getPool() == null) {
params.pool(HTable.getDefaultExecutor(getConfiguration()));
}
if (params.getWriteBufferSize() == BUFFERED_PARAM_UNSET) {
params.writeBufferSize(connectionConfig.getWriteBufferSize());
}
if (params.getMaxKeyValueSize() == BUFFERED_PARAM_UNSET) {
params.maxKeyValueSize(connectionConfig.getMaxKeyValueSize());
}
return new OHBufferedMutatorImpl(this, params);
}
mutation操作を追加します:
- 単一mutation操作
public void mutate(Mutation mutation) throws IOException {
mutate(Collections.singletonList(mutation));
}
- 複数mutation操作インターフェース
public void mutate(List<? extends Mutation> mutations) throws IOException {
// ...
}
closeを呼び出した後でも、既存の操作を手動でflushしてコミットすることは可能ですが、新しいmutation操作を追加することはできません。
public void flush() throws IOException {
asyncExecute(true);
}
CheckAndMutateBuilderインターフェースの説明と例
CheckAndMutateBuilderは、HBase 2.xのHTableにおける新しい構造であり、CheckAndxxx操作を実行するために使用されます。ユーザーは、row、family、qualifier、value、timeRange、CompareOpなどのパラメータを設定することで、put、delete、mutate操作を実行できます。CheckAndMutateBuilderは、ユーザーが設定したCompareOpやfamilyなどのパラメータをデータベース内のデータと比較し、一致した場合に対応する操作を実行します。
インターフェースの説明は以下のとおりです:
メソッド |
機能 |
|---|---|
| CheckAndMutateBuilder qualifier(byte[] qualifier) | qualifierを設定します |
| CheckAndMutateBuilder timeRange(TimeRange timeRange) | TimeRangeを設定します |
| CheckAndMutateBuilder ifNotExists(); | qualifierが存在しないかどうかを確認するために使用されます |
| CheckAndMutateBuilder ifEquals(byte[] value) | valueが存在するかどうかを確認するために使用されます |
| CheckAndMutateBuilder ifMatches(CompareOperator compareOp, byte[] value) | 比較子とvalueを設定します |
| boolean thenPut(Put put) | put操作を実行します |
| boolean thenDelete(Delete delete) | delete操作を実行します |
| boolean thenMutate(RowMutations mutation) | putとdeleteの混合操作を実行します |
使用例は以下のとおりです:
keyがputKey、familyがfamily_group、qualifierがcolumn1、valueがvalue1のデータに対してput操作を実行する場合:
OHTable hTable;
Put put = new Put(toBytes("putKey"));
put.addColumn(toBytes("family_group"), toBytes("column1"), toBytes("value2"));
boolean ret = hTable.checkAndMutate(toBytes("putKey"), toBytes("family_group"))
.qualifier(toBytes("column1")
.ifEqual("value1")
.thenPut(put);
batchインターフェースの説明と例
batch(List<Row> actions, Object[] results) メソッドは、複数の操作(put、get、deleteなど)を一括実行し、結果を指定された配列に格納するために使用されます。このメソッドを使用することで、一度に複数の操作を実行し、効率を向上させることができます。
現在、putとdeleteの操作のみがサポートされています。putとdeleteの混合操作、および複数のカラムファミリーに対する操作もサポートされています。
インターフェースの説明
// 1.x と 2.x 両方でこのインターフェースが利用可能です
public void batch(final List<? extends Row> actions, final Object[] results)
// 2.x ではこのインターフェースは削除されました
public void batch(final List<? extends Row> actions)
使用例
List<Row> batchLsit = new LinkedList<>();
for (int i = 0; i < rows; ++i) {
Put put = new Put(toBytes("Key" + i));
Delete delete = new Delete(toBytes("Key" + i));
batchLsit.add(delete);
put.addColumn(family1, family1_column1, family1_value);
put.addColumn(family1, family1_column2, family1_value);
put.addColumn(family1, family1_column3, family1_value);
put.addColumn(family2, family2_column1, family2_value);
put.addColumn(family2, family2_column2, family2_value);
put.addColumn(family3, family3_column1, family3_value);
batchLsit.add(put);
}
// f1c1 f1c2 f1c3 f2c1 f2c2 f3c1
Delete delete = new Delete(toBytes("Key1"));
delete.addColumns(family1, family1_column1);
delete.addColumns(family2, family2_column1);
batchLsit.add(delete);
Object[] results = new Object[batchLsit.size()];
multiCfHTable.batch(batchLsit, results);
batchCallback インターフェースの説明と例
Table.batch(List<Row> actions, Batch.Callback<R> callback) メソッドは、複数の操作をバッチ処理し、各操作が完了するたびにコールバック関数を実行します。これにより、すべての操作が終了するのを待たずに、各操作の結果をその都度処理できます。
インターフェースの説明
// このインターフェースは1.x系と2.x系に共通しています
public <R> void batchCallback(final List<? extends Row> actions,
final Object[] results,
final Batch.Callback<R> callback)
// 2.x系ではこのインターフェースは削除されました
public <R> void batchCallback(final List<? extends Row> actions,
final Batch.Callback<R> callback)
使用例
List<Row> batchLsit = new LinkedList<>();
for (int i = 0; i < rows; ++i) {
Put put = new Put(toBytes("Key" + i));
Delete delete = new Delete(toBytes("Key" + i));
batchLsit.add(delete);
put.addColumn(family1, family1_column1, family1_value);
put.addColumn(family1, family1_column2, family1_value);
put.addColumn(family1, family1_column3, family1_value);
put.addColumn(family2, family2_column1, family2_value);
put.addColumn(family2, family2_column2, family2_value);
put.addColumn(family3, family3_column1, family3_value);
batchLsit.add(put);
}
// f1c1 f1c2 f1c3 f2c1 f2c2 f3c1
Delete delete = new Delete(toBytes("Key1"));
delete.addColumns(family1, family1_column1);
delete.addColumns(family2, family2_column1);
batchLsit.add(delete);
Object[] results = new Object[batchLsit.size()];
multiCfHTable.batchCallback(batchLsit, results, new Batch.Callback<Result>() {
@Override
public void update(byte[] region, byte[] row, Result result) {
updateCounter[0]++;
}
});
Adminインターフェースの説明と例
OBKV-HBaseのAdminインターフェースは、HBaseのAdminインターフェースの一部と互換性があります。
前提条件
OBKV-HBaseのAdminインターフェース機能は、テナントレベルの隠し構成パラメータ _enable_kv_hbase_admin_ddl によって有効にする必要があります。この構成パラメータのデフォルト値は false であり、この機能はデフォルトで無効です。有効化コマンドは以下のとおりです:
ALTER SYSTEM SET _enable_kv_hbase_admin_ddl = true;
createTable
createTable はHBaseテーブルを作成するために使用されます。
OBKV-HBaseの基盤実装では、指定された名前のテーブルグループ(Tablegroup)を作成し、そのテーブルグループ内に TableDescriptor パラメータで指定されたカラムファミリーを作成します。また、各カラムファミリーに対応するTTLおよびMaxVersionパラメータも設定します。各カラムファミリーには、テーブル名$カラムファミリー名 の形式で物理テーブルが対応します。テーブルグループと物理テーブルの作成は2つの必須ステップであり、システムはこれら2つのステップが同時に成功するか、同時に失敗することを保証します。
インターフェース定義は以下のとおりです:
void createTable(TableDescriptor desc) throws IOException
例では、test テーブルを作成しています。このテーブルには2つのカラムファミリー (cf1 と cf2) があり、cf1 のMaxVersionは 2、データ生存時間は 86400 秒(1日)です。cf2 のMaxVersionは 1、データ生存時間は 86400 秒(1日)です。詳細は以下のとおりです:
Connection connection = ConnectionFactory.createConnection(conf);
Admin admin = connection.getAdmin();
// 1. htable記述とカラムファミリー記述を構築する
HColumnDescriptor hcd1 = new HColumnDescriptor(Bytes.toBytes("cf1"));
hcd1.setMaxVersions(2);
hcd1.setTimeToLive(86400);
HColumnDescriptor hcd2 = new HColumnDescriptor(Bytes.toBytes("cf2"));
hcd2.setMaxVersions(1);
hcd2.setTimeToLive(86400);
// 2. テーブル作成操作を実行する
HTableDescriptor htd = new HTableDescriptor(TableName.valueOf("test"));
htd.addFamily(hcd1);
htd.addFamily(hcd2);
admin.createTable(htd);
注意事項は以下のとおりです:
- 現在、
void createTable(TableDescriptor desc)インターフェースのみをサポートしています。 - 現在、カラムファミリーではTTLとMaxVersionの設定のみをサポートしています。
- セルレベルのTTLはサポートされていません。
tableExists
tableExists は、指定されたHBaseテーブルが存在するかどうかを確認するために使用されます。存在すれば true を返し、存在しなければ false を返します。HBaseテーブルにnamespaceが付いている場合は、namespace:tableName の形式でnamespaceを指定する必要があります。このnamespaceはOceanBaseクラスタ内でdatabaseを表します。
インターフェース定義は以下のとおりです:
public boolean tableExists(TableName tableName) throws IOException;
例では、tableExists インターフェースを使用して test テーブルが存在するかどうかを確認します。
Configuration conf = ObHTableTestUtil.newConfiguration();
Connection connection = ConnectionFactory.createConnection(conf);
Admin admin = connection.getAdmin();
if (admin.tableExists(TableName.valueOf("test"))) {
...
}
getTableDescriptor
getTableDescriptorはHBaseテーブルのデスクリプターを取得するためのメソッドであり、OBKV-HBaseではテーブルのメタデータ情報を検索するために使用されます。メタデータ情報にはテーブル名やカラムファミリーレベルの設定HColumnDescriptorが含まれ、現在主にカラムファミリー名、MaxVersion、TTL、テーブルの状態(enable/disable)を対象としています。
インターフェースの定義は以下の通りです:
HTableDescriptor getTableDescriptor(TableName tableName) throws TableNotFoundException, IOException;
例では、getTableDescriptorインターフェースを使用してtestテーブルのデスクリプターを取得し、テーブルのカラムファミリー情報を出力します。
Configuration conf = ObHTableTestUtil.newConfiguration();
Connection connection = ConnectionFactory.createConnection(conf);
Admin admin = connection.getAdmin();
HTableDescriptor descriptor = admin.getTableDescriptor(TableName.valueOf("test"));
if (descriptor.hasFamily("cf1".getBytes())) {
ColumnFamilyDescriptor family1Desc = descriptor.getColumnFamily("cf1".getBytes());
int ttl = family1Desc.getTimeToLive();
int maxVersions = family1Desc.getMaxVersions();
}
isTableDisabled
isTableDisabledは、指定されたHBaseテーブルが無効化されているかどうかをチェックするために使用されます。無効な場合はtrueを返し、有効な場合はfalseを返します。通常はenableTableやその他の操作の前に使用されます。
インターフェースの定義は以下の通りです:
public boolean isTableDisabled(TableName tableName);
例では、isTableDisabledインターフェースを使用してtestテーブルが無効化されているかどうかをチェックし、その後enableTableインターフェースを使用してtestテーブルを有効化します。
Configuration conf = ObHTableTestUtil.newConfiguration();
Connection connection = ConnectionFactory.createConnection(conf);
Admin admin = connection.getAdmin();
TableName tableName = TableName.valueOf("test");
if (admin.isTableDisabled(tableName)) {
admin.enableTable(tableName);
}
isTableEnabled
isTableEnabledは、指定されたHBaseテーブルが有効化されているかどうかをチェックするために使用されます。有効な場合はtrueを返し、無効な場合はfalseを返します。通常はdisableTableやその他の操作の前に使用されます。
インターフェースの定義は以下の通りです:
public boolean isTableEnabled(TableName tableName);
例では、isTableEnabledインターフェースを使用してtestテーブルが有効化されているかどうかをチェックし、その後disableTableインターフェースを使用してtestテーブルを無効化します。
Configuration conf = ObHTableTestUtil.newConfiguration();
Connection connection = ConnectionFactory.createConnection(conf);
Admin admin = connection.getAdmin();
TableName tableName = TableName.valueOf("test");
if (admin.isTableEnabled(tableName)) {
admin.disableTable(tableName);
}
disableTable
disableTableは指定されたHBaseテーブルを無効にするために使用します。このインターフェースを呼び出した後、HBaseテーブルは使用できない状態になります。disableTableインターフェースは通常、HBaseテーブルのメンテナンスに使用されます。例えば、データのクリアやテーブル構造の変更などの操作の前に、disableTableを使用してHBaseテーブルを無効にします。
インターフェースの定義は以下のとおりです:
public void disableTable(TableName tableName);
例では、まずisTableEnabledインターフェースを使用してtestテーブルがenabled状態かどうかを判断し、次にdisableTableインターフェースを使用してテーブルを無効にします。最後にisTableDisabledインターフェースを使用してテーブルがdisabled状態かどうかを確認します。
Configuration conf = ObHTableTestUtil.newConfiguration();
Connection connection = ConnectionFactory.createConnection(conf);
Admin admin = connection.getAdmin();
TableName tableName = TableName.valueOf("test");
if (admin.isTableEnabled(tableName)) {
admin.disableTable(tableName);
Assert.assertTrue(admin.isTableDisabled(tableName));
}
deleteTable
deleteTableは指定されたHBaseテーブルを削除するために使用します。このインターフェースを呼び出した後、テーブルは使用できない状態になります。
インターフェースの定義は以下のとおりです:
void deleteTable(TableName tableName) throws IOException
例では、まずdisableTableインターフェースを使用してtestテーブルを無効にし、次にdeleteTableインターフェースを使用してtestテーブルを削除します。
Configuration conf = ObHTableTestUtil.newConfiguration();
Connection connection = ConnectionFactory.createConnection(conf);
Admin admin = connection.getAdmin();
TableName tableName = TableName.valueOf("test");
try {
admin.disableTable(tableName);
admin.deleteTable(tableName);
}
注意事項は以下のとおりです:
- HBaseテーブルにnamespaceが存在する場合は、
namespace:tableNameの形式でnamespaceを指定する必要があります。namespaceが存在しない場合は、NamespaceNotFoundException例外がスローされます。namespaceはOceanBaseクラスタ内でデータベースを表します。 - HBaseテーブルが存在しない場合、
TableNotFoundExceptionエラーが発生します。 - 削除する前に、まず
disableTableインターフェースを使用してテーブルを無効にする必要があります。そうでない場合、TableNotDisabledExceptionエラーが発生します。