The OBKV-HBase client implements the HTableInterface interface of HBase. This topic describes the compatibility of OBKV-HBase with the open-source HBase interfaces.
API compatibility
Modifier and type |
Method and description |
Compatibility |
|---|---|---|
| Result | append (Append Appends values to one or more columns within a single row. | Supported |
| Object[] | batch(List<? extends Row> actions) This method is the same as batch(List, Object[]), but returns an array of results instead of using the results parameter for reference. |
Not supported |
| void | batch(List<? extends Row> actions, Object[] results) Performs a batch call on deletes, gets, puts, increments, appends, and row mutations. | Not supported |
| boolean | checkAndDelete (byte[] row, byte[] family, byte[] qualifier, byte[] value,Delete delete) Atomically checks whether the row/family/qualifier value matches the expected value. |
Supported |
| boolean | checkAndPut (byte[] row, byte[] family, byte[] qualifier, byte[] value, Put put) Atomically checks whether the row/family/qualifier value matches the expected value. |
Supported |
| void | close() Releases any resources in the internal buffer or pending changes. | Supported |
| <T extends CoprocessorProtocol,R>Map<byte[],R> | coprocessorExec(Class |
Not supported |
| <T extends CoprocessorProtocol,R> void | coprocessorExec(Class |
Not supported |
| <T extends CoprocessorProtocol > T | coprocessorProxy(Class |
Not supported |
| void | delete (Delete delete) Deletes a specified cell or row. | Supported |
| void | delete (List<Delete deletes) Deletes the specified cells or rows in batches. | Supported |
| boolean | exists (Get) Checks whether the specified column exists in the table. | Supported |
| void | flushCommits Executes all buffered Put operations. | Supported |
| Result | get (Get get) Retrieves a specific cell from the given row. | Supported |
| Result[] | get (List<Get> gets) Retrieves specific cells from the given rows in batches. | Supported |
| org.apache.hadoop.conf.Configuration | getConfiguration() Returns the Configuration object used by this instance. | Supported |
| Result | rowOrBefore(byte[] row, byte[] family) Deprecated. As of version 0.92, this method is deprecated and has no replacement. getRowOrBefore is used internally to find entries in .META. and makes various assumptions about the table (which are true for .META. but not in general) to be efficient. | Deprecated |
| ResultScanner | getScanner(byte[] family) Gets a scanner on the current table for the specified column family. | Supported |
| ResultScanner | getScanner(byte[] family, byte[] qualifier) Gets a scanner on the current table for the specified column family and qualifier. | Supported |
| ResultScanner | getScanner (Scan scan) Returns a scanner on the current table as specified by the Scan object. | Supported |
| HTableDescriptor | getTableDescriptor() Gets the table descriptor for this table. | Not supported |
| byte[] | getTableName() Gets the name of this table. | Supported |
| long | getWriteBufferSize() Returns the maximum size in bytes of the write buffer for this HTable. | Supported |
| Result | increment (Increment increment) Increments one or more columns within a single row. | Supported |
| long | incrementColumnValue(byte[] row, byte[] family, byte[] qualifier, long amount) Atomically increments a column value. | Supported |
| long | incrementColumnValue(byte[] row, byte[] family, byte[] qualifier, long amount, Durability durability) Atomically increments a column value. | Supported |
| boolean | isAutoFlush Tells whether auto-flush is enabled. | Supported |
| RowLock | lockRow(byte[] row) Acquires a row lock. | Not supported |
| void | mutateRow (RowMutations rm) Performs multiple mutations atomically on a single row. | Not supported |
| void | put (List<Put> puts) Inserts data in batches. | Supported |
| void | put (Put put) Inserts data into the table. | Supported |
| void | setAutoFlush(boolean autoFlush) Specifies whether to automatically flush data. | Supported |
| void | setAutoFlush (boolean autoFlush, boolean clearBufferOnFail) Specifies whether to automatically flush data and whether to clear the buffer on failure. | Supported |
| void | setWriteBufferSize(long writeBufferSize) Sets the size of the write buffer. | Supported |
| void | unlockRow (RowLock rl) Releases a row lock. | Not supported |
| void | setBatch: Sets the batch size. | Supported |
| void | setCaching: Sets the caching value. | Supported |
| void | setMaxResultSize: Sets the maximum result size. | Supported |
| void | setAllowPartialResults: Specifies whether to allow partial results. | Supported |
| void | checkExistenceOnly: Specifies whether to check only for existence. | Supported |
| void | checkAndMutate: Specifies whether to check and modify. | Supported |
| void | connection: Sets the connection. | Supported |
| void | ohBufferedMutatorImpl: Sets the BufferedMutator implementation. | Supported |
Differences in API usage
Due to architectural differences, some configuration code needs to be adjusted when migrating code from open-source HBase to OBKV-HBase.
Description of differences
The data access code for open-source HBase and OBKV-HBase remains unchanged, ensuring compatibility in the data access part. The main differences lie in:
- Configuration: The architecture and configuration settings differ between open-source HBase and OBKV-HBase.
- OHTableClient: Data access requires a handle based on OBKV-HBase.
Code example
Open-source HBase code:
public class HBaseInsertDemo {
public static void main(String[] args) throws Exception {
// Configure HBase
Configuration conf = HBaseConfiguration.create();
conf.set("hbase.zookeeper.quorum", "your_zookeeper_quorum"); // Set the ZooKeeper address.
conf.set("hbase.zookeeper.property.clientPort", "2181"); // Set the ZooKeeper port.
// Obtain a Table handle
TableName tableName = TableName.valueOf("your_table_name");
HTable table = new HTable(tableName, conf);
// Prepare data for insertion
Put put = new Put(Bytes.toBytes("row_key"));
put.addColumn(Bytes.toBytes("cf"), Bytes.toBytes("qualifier"), Bytes.toBytes("value")); // Column family, column qualifier, value.
table.put(put);
// Close resources
table.close();
System.out.println("Data inserted successfully!");
}
}
OBKV-HBase code:
public class OBHBaseInsertDemo {
public static void main(String[] args) throws Exception {
// Configure 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, "");
// Obtain a Table handle
TableName tableName = TableName.valueOf("your_table_name");
OHTableClient table = new OHTableClient(tableName, conf); // Create an HTable object.
// Prepare data for insertion.
Put put = new Put(Bytes.toBytes("row_key"));
put.addColumn(Bytes.toBytes("cf"), Bytes.toBytes("qualifier"), Bytes.toBytes("value")); // Column family, column qualifier, value.
table.put(put);
// Close resources.
table.close();
System.out.println("Data inserted successfully!");
}
}
API details and examples
API description and examples for the Scan class
Some APIs of the Scan class are supported, including setBatch, setCaching, setMaxResultSize, setAllowPartialResults, and setCacheBlocks.
setBatch
Sets the maximum number of cells returned by each next() call. This is used to implement pagination queries on the client side.
public Scan setBatch(int batch);
setCaching
Limits the number of rows returned by the server in a single RPC. By default, there is no limit. You can set a large caching value to retrieve more data per RPC and speed up queries, or set a small caching value to reduce client-side memory consumption and avoid Out-of-Memory (OOM).
public Scan setCaching(int caching);
setMaxResultSize
Limits the maximum number of bytes of data that can be returned by the server in a single RPC. By default, there is no limit.
public Scan setMaxResultSize(long maxResultSize);
setAllowPartialResults
Determines whether partial rows can be returned to the user to avoid client-side OOM caused by excessively long single-row data. The default value is false. In this case, even if you set setMaxResultSize to limit the amount of returned data, the server returns at least one complete row of data to the client each time.
public Scan setAllowPartialResults(final boolean allowPartialResults);
setCacheBlocks
Determines whether the query result set is cached in OceanBase AI Database's row cache or BlockCache. The default value is true. For example, you can set it to false when you perform a full table scan to avoid contaminating the cache.
public Scan setCacheBlocks(boolean cacheBlocks);
renew
Sets the expiration time of the query result set. The default value is 0, which indicates that no expiration time is set.
The ResultScanner.renewLease() method extends the validity period (lease) of a ResultScanner. In HBase, a ResultScanner has a default validity period of 60,000 ms. If no data is read within this period, the scanner closes automatically. By calling renewLease(), you can refresh the status of the ResultScanner so that the validity period is reset and the scanner remains open longer.
In OBKV-HBase, the validity period of a ResultScanner is adjusted by using kv_hbase_client_scanner_timeout_period.
Here is an example:
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
The Scan.withStartRow and Scan.withStopRow methods specify the start row and the stop row of the scan, and whether the row keys are inclusive. These methods help you define the scan range so that only data in the specified row key range is scanned.
Example:
// Create a Scan object
Scan scan = new Scan();
// Set the start row and the stop row
byte[] startRow = Bytes.toBytes("row1");
byte[] stopRow = Bytes.toBytes("row5");
scan.withStartRow(startRow);
scan.withStopRow(stopRow);
// Get ResultScanner
ResultScanner scanner = table.getScanner(scan);
setLimit
The Scan.setLimit(int limit) method sets the maximum number of results to scan. This method limits the number of results returned per scan to prevent memory overflow caused by returning a large amount of data at once.
Example:
// Create a Scan object
Scan scan = new Scan();
// Set the maximum number of results
int limit = 100;
scan.setLimit(limit);
// Get ResultScanner
ResultScanner scanner = table.getScanner(scan);
Get class interfaces and examples
checkExistenceOnly
Sets whether the result returned by a Get operation contains only the exists flag (obtained through the getExists interface of Result) rather than a result set, for checking whether data that meets the conditions exists.
public Get setCheckExistenceOnly(boolean checkExistenceOnly);
checkAndMutate
checkAndMutate is an interface of Table that allows batch operations on the same row. The specified checkAndMutate operations can be sent to the RegionServer in one RPC. Unlike in native HBase, if any one operation fails, all other operations are rolled back.
Scenario: You need to make verification and insertion an atomic operation. For example, first verify whether a person's wallet balance is greater than 100. If it is, modify the balance and return true. If not, do not modify the balance and return false.
The parameters are described as follows:
row: The row to operate on.family,qualifier,value: The cells to verify.compareOp: The comparison operator.rowMutations: The operations to perform if the row matches.
Return value:
true or false, indicating whether the match was successful.
connection
This feature provides a handle for connecting to a database, making it convenient to obtain handles for various tables from the connection to operate on data. It also provides some connection-level interfaces, such as admin and bufferMutate operations.
Table and BufferMutator
The following code snippet demonstrates a common HBase connection usage:
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 is a thread-safe object. Only one Connection object needs to be constructed during the lifetime of the program.
// After the program ends, you must close the Connection object to prevent connection leaks. You can use a try-finally block to ensure that the connection is closed.
Connection connection = ConnectionFactory.createConnection(conf);
TableName tableName = TableName.valueOf("tablename");
// Get a table handle
Table table = connection.getTable(tableName);
// Get a BufferedMutator
BufferedMutator ohBufferMutator = connection.getBufferedMutator(tableName);
HBase creates a Connection by passing a configuration to ConnectionFactory and then retrieves the corresponding table from the Connection for operations.
- Method 1: Set the configuration directly.
conf.set(ClusterConnection.HBASE_CLIENT_CONNECTION_IMPL,
"com.alipay.oceanbase.hbase.util.OHConnectionImpl");
- Method 2: Modify the configuration file.
Add this parameter to hbase-site.xml and hbase-default.xml. The priority is hbase-site.xml > hbase-default.xml.
<property>
<name>hbase.client.connection.impl</name>
<value>com.alipay.oceanbase.hbase.util.OHConnectionImpl</value>
</property>
TableBuilder
TableBuilder is used in HBase 2.x to define and obtain the new structure of an HTable. You can set parameters such as TableName, ConnectionConfiguration, and rpcTimeout for TableBuilder to obtain the corresponding HTable.
Example:
Obtain a TableBuilder.
public TableBuilder getTableBuilder(TableName tableName, ExecutorService pool);Note: If you have defined a pool before you call
getTableBuilder, you must close it manually. Closing an HTable does not automatically close a user-defined pool.Obtain an OHTable through TableBuilder.
Configuration conf = ObHTableTestUtil.newConfiguration(); conf.set(...); connection = ConnectionFactory.createConnection(conf); ExecutorService pool = ...; TableName tableName = TableName.valueOf("table_name"); TableBuilder builder = connection.getTableBuilder(tableName, pool);
Set connection timeout
The rpcConnectTimeout parameter in tableClient and the obTableConnectTimeout parameter in ObTable control the connection timeout when the Table client initializes and establishes a connection with the OBServer node of the current tenant. The minimum connection timeout for tableClient is 1 second.
Design of the OBKV-HBase client:
Both parameters for the Table client in OBKV-HBase can be set by using the configuration interface in ObTableClient. Therefore, they must be set before the TableClient object in the HBase client is initialized.
/*
* Set rpc connect timeout.
*/
public void setRpcConnectTimeout(int rpcConnectTimeout) {
this.properties.put(RPC_CONNECT_TIMEOUT.getKey(), String.valueOf(rpcConnectTimeout));
this.rpcConnectTimeout = rpcConnectTimeout;
}
For compatibility with the earlier ipc.socket.timeout parameter, you can still set the connection timeout by using this parameter. However, the new hbase.ipc.client.socket.timeout.connect parameter takes precedence over the old one. The Table client uses the setting of the old parameter only if you set only that parameter and do not set the new one. In all other cases, it uses the default or specified value of the new parameter.
// SOCKET_TIMEOUT_CONNECT = "hbase.ipc.client.socket.timeout.connect", default value: 10s
// SOCKET_TIMEOUT = "ipc.socket.timeout", default value: 20s
int rpcConnectTimeout = -1;
// If a new parameter is set, use it directly.
if (conf.get(SOCKET_TIMEOUT_CONNECT) != null) {
rpcConnectTimeout = conf
.getInt(SOCKET_TIMEOUT_CONNECT, DEFAULT_SOCKET_TIMEOUT_CONNECT);
} else {
// If no new parameter is set but an old one is, the old parameter is used.
if (conf.get(SOCKET_TIMEOUT) != null) {
rpcConnectTimeout = conf.getInt(SOCKET_TIMEOUT, DEFAULT_SOCKET_TIMEOUT);
} else { // Neither parameter is set, use the default value of the new parameter.
rpcConnectTimeout = conf
.getInt(SOCKET_TIMEOUT_CONNECT, DEFAULT_SOCKET_TIMEOUT_CONNECT);
}
}
this.rpcConnectTimeout = rpcConnectTimeout;
Pass rpcConnectTimeout to the function that creates ObTableClient so that the timeout is set before initialization.
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);
}
The OBKV-HBase client caches created ObTableClient objects and does not reinitialize them. Therefore, if you later want to set the connection timeout for an ObTableClient, you cannot use the Configuration.set method. Instead, you must directly use the setRpcConnectTimeout interface of the corresponding ObTableClient object.
Incompatible interfaces
Some interfaces are currently incompatible:
getAdminis currently incompatible.- Methods such as
getRegionServerare incompatible. - Currently, the connection provides only three interfaces:
getTable,getBufferdMutator, andTableBuilder.
API description and examples of the table class
setRpcTimeout,getRpcTimeout: The timeout duration of an RPC call.setOperationTimeout,getOperationTimeout: The timeout duration of an operation, which may involve multiple RPC calls due to retries or other reasons.
BufferedMutator API description and examples
Similar to the BufferedMutator of HBase, it is used to accumulate mutation operations for batch execution. You can choose to manually commit batch operations or have the OBKV BufferedMutator automatically commit them when the accumulation threshold is reached. ohBufferedMutatorImpl is the BufferedMutator implementation class in OBKV-HBase.
Currently, the BufferedMutator of OBKV-HBase supports only delete and add operations, and a created OBKV-HBase BufferedMutator object can perform batch operations on only one type of mutation. Operations within a BufferedMutator cannot guarantee concurrent order, execution order, or atomicity when an operation fails.
1.x compatibility
The BufferedMutator of OBKV-HBase is compatible with HBase BufferedMutator 1.x. OHBufferedMutatorImpl 1.x depends on the batch interface in OHTable 1.x.
The features are described as follows:
- The same BufferedMutator object can perform mixed put and delete operations.
- Both put and delete operations in a BufferedMutator support multiple column families.
- When the number of mutation operations in a BufferedMutator reaches the threshold, it executes batch operations. Automatic batch processing has an upper limit, which is consistent with native HBase and equals twice the batch processing threshold.
- For failed mutation operations, the system recycles them.
2.x compatibility
The BufferedMutator of OBKV-HBase is compatible with HBase BufferedMutator 2.x. OHBufferedMutatorImpl 2.x depends on the batch interface in OHTable 2.x.
The features are described as follows:
- The same BufferedMutator object can perform mixed put and delete operations.
- Both put and delete operations in a BufferedMutator support multiple column families.
- A BufferedMutator has an internal timer that periodically executes batch processing operations. Each batch processing operation commits all accumulated operations.
- For failed mutation operations, the system recycles them.
New interfaces in 2.x:
Added the
setWriteBufferPeriodicFlushinterface to configure the auto-committer.timeoutMscontrols the interval between two executions, andtimerTickMscontrols the interval of the committer trigger. Example:public synchronized void setWriteBufferPeriodicFlush(long timeoutMs, long timerTickMs);Added the
disableWriteBufferPeriodicFlushinterface to disable the auto-committer. Example:public void disableWriteBufferPeriodicFlush();
How to obtain a BufferedMutator
There are two ways to obtain a BufferedMutator:
- Pass in
TableNameto specify the table name and use default parameters for the others.
public BufferedMutator getBufferedMutator(TableName tableName) throws IOException {
return getBufferedMutator(new BufferedMutatorParams(tableName));
}
- Pass in
BufferedMutatorParamsto use custom parameters.
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);
}
Add a mutation operation:
- Single mutation operation
public void mutate(Mutation mutation) throws IOException {
mutate(Collections.singletonList(mutation));
}
- Multiple mutation operations interface
public void mutate(List<? extends Mutation> mutations) throws IOException {
// ...
}
After you call close, you can also manually flush to commit existing operations, but you cannot add new mutation operations.
public void flush() throws IOException {
asyncExecute(true);
}
CheckAndMutateBuilder interface description and example
CheckAndMutateBuilder is a new structure in HBase 2.x HTable for performing CheckAndxxx operations. You can set parameters such as the row, column family, column qualifier, value, time range, and comparison operator (CompareOp) to perform put, delete, and mutate operations. CheckAndMutateBuilder compares your settings with the data in the database based on parameters such as CompareOp and family. If a match is found, the corresponding operation is executed.
The interface is described as follows:
Method |
Purpose |
|---|---|
CheckAndMutateBuilder qualifier(byte[] qualifier) |
Sets the qualifier. |
CheckAndMutateBuilder timeRange(TimeRange timeRange) |
Sets the TimeRange. |
CheckAndMutateBuilder ifNotExists() |
Checks whether the qualifier does not exist. |
CheckAndMutateBuilder ifEquals(byte[] value) |
Checks whether a value exists. |
CheckAndMutateBuilder ifMatches(CompareOperator compareOp, byte[] value) |
Sets the comparator and value. |
boolean thenPut(Put put) |
Performs a put operation. |
boolean thenDelete(Delete delete) |
Performs a delete operation. |
boolean thenMutate(RowMutations mutation) |
Performs mixed put and delete operations. |
An example is as follows:
Perform a put operation on data whose key is putKey, family is family_group, qualifier is column1, and value is value1:
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 interface description and example
The batch(List<Row> actions, Object[] results) method is used to batch execute multiple operations (such as put, get, and delete) and store the results in a specified array. This method allows you to execute multiple operations at once, improving efficiency.
Currently, only put and delete operations are supported. Mixed put and delete operations, as well as multi-column family operations, are also supported.
Interface description
// This API is available in both 1.x and 2.x.
public void batch(final List<? extends Row> actions, final Object[] results)
// This API is removed in 2.x.
public void batch(final List<? extends Row> actions)
Usage example
List<Row> batchList = new LinkedList<>();
for (int i = 0; i < rows; ++i) {
Put put = new Put(toBytes("Key" + i));
Delete delete = new Delete(toBytes("Key" + i));
batchList.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);
batchList.add(put);
}
// f1c1 f1c2 f1c3 f2c1 f2c2 f3c1
Delete delete = new Delete(toBytes("Key1"));
delete.addColumns(family1, family1_column1);
delete.addColumns(family2, family2_column1);
batchList.add(delete);
Object[] results = new Object[batchList.size()];
multiCfHTable.batch(batchList, results);
batchCallback interface description and example
The Table.batch(List<Row> actions, BatchCallBack<R> callback) method can batch execute multiple operations and call back the callback function after each operation is completed. This way, results can be processed immediately after each operation finishes, rather than waiting until all operations are complete.
Interface description
// This API is available in both 1.x and 2.x.
public <R> void batchCallback(final List<? extends Row> actions,
final Object[] results,
final Batch.Callback<R> callback)
// This API is removed in 2.x.
public <R> void batchCallback(final List<? extends Row> actions,
final Batch.Callback<R> callback)
Usage example
List<Row> batchList = new LinkedList<>();
for (int i = 0; i < rows; ++i) {
Put put = new Put(toBytes("Key" + i));
Delete delete = new Delete(toBytes("Key" + i));
batchList.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);
batchList.add(put);
}
// f1c1 f1c2 f1c3 f2c1 f2c2 f3c1
Delete delete = new Delete(toBytes("Key1"));
delete.addColumns(family1, family1_column1);
delete.addColumns(family2, family2_column1);
batchList.add(delete);
Object[] results = new Object[batchList.size()];
multiCfHTable.batchCallback(batchList, results, new Batch.Callback<Result>() {
@Override
public void update(byte[] region, byte[] row, Result result) {
updateCounter[0]++;
}
});
Admin API details and examples
The Admin API of OBKV-HBase is compatible with some APIs of the HBase Admin module.
Prerequisites
To use the Admin API of OBKV-HBase, you must enable the _enable_kv_hbase_admin_ddl tenant-level hidden parameter. The default value of this parameter is false, which disables this feature. The enabling command is as follows:
ALTER SYSTEM SET _enable_kv_hbase_admin_ddl = true;
createTable
createTable creates an HBase table.
In the underlying implementation of OBKV-HBase, a table group with the specified name is created. Then, the column families specified by the TableDescriptor parameter are created under this table group, along with the corresponding TTL and MaxVersion parameters for each column family. Each column family also corresponds to an entity table. The entity table name is in the table name$column family name format. Creating a table group and an entity table are two necessary steps. The system ensures that both steps succeed or fail simultaneously.
The interface definition is as follows:
void createTable(TableDescriptor desc) throws IOException
The following example creates a test table with two column families (cf1 and cf2). The MaxVersion of cf1 is 2, and the data retention time is 86400 seconds (1 day). The MaxVersion of cf2 is 1, and the data retention time is 86400 seconds (1 day). The details are as follows:
Connection connection = ConnectionFactory.createConnection(conf);
Admin admin = connection.getAdmin();
// 1. Construct the HTable description and column family description
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. Perform the table creation operation
HTableDescriptor htd = new HTableDescriptor(TableName.valueOf("test"));
htd.addFamily(hcd1);
htd.addFamily(hcd2);
admin.createTable(htd);
Consider the following points:
- Currently, only the
void createTable(TableDescriptor desc)interface is supported. - Currently, only setting TTL and MaxVersion are supported for a column family.
- Cell-level TTL is not supported.
tableExists
tableExists checks whether a specified HBase table exists. If it exists, true is returned. If not, false is returned. If the HBase table has a namespace, you must specify the namespace in the namespace:tableName format. In an OceanBase AI Database cluster, a namespace maps to a database.
The interface definition is as follows:
public boolean tableExists(TableName tableName) throws IOException;
The following example checks whether the test table exists using the tableExists interface.
Configuration conf = ObHTableTestUtil.newConfiguration();
Connection connection = ConnectionFactory.createConnection(conf);
Admin admin = connection.getAdmin();
if (admin.tableExists(TableName.valueOf("test"))) {
...
}
getTableDescriptor
getTableDescriptor obtains an HBase table descriptor. In OBKV-HBase, it is used to retrieve metadata about a table. The metadata includes the table name and the configuration at the column family level, such as HColumnDescriptor, which currently mainly includes the column family name, MaxVersion, TTL, and table status (enabled or disabled).
The interface definition is as follows:
HTableDescriptor getTableDescriptor(TableName tableName) throws TableNotFoundException, IOException;
The following example uses the getTableDescriptor interface to obtain the descriptor of the test table and print its column family information.
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 checks whether the specified HBase table is disabled. If it is disabled, true is returned. Otherwise, false is returned. This method is typically used before operations such as enableTable.
The interface definition is as follows:
public boolean isTableDisabled(TableName tableName);
The following example uses the isTableDisabled interface to check whether the test table is disabled, and then uses the enableTable interface to enable the test table.
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 checks whether the specified HBase table is enabled. If it is enabled, true is returned. Otherwise, false is returned. This method is typically used before operations such as disableTable.
The interface definition is as follows:
public boolean isTableEnabled(TableName tableName);
The following example uses the isTableEnabled interface to check whether the test table is enabled, and then uses the disableTable interface to disable the test table.
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 disables the specified HBase table. After this interface is called, the HBase table becomes unavailable. disableTable is generally used for HBase table maintenance, for example, to disable an HBase table before you clear data or modify the table structure.
The interface definition is as follows:
public void disableTable(TableName tableName);
The following example first uses the isTableEnabled interface to check whether the test table is in the enabled state, then uses the disableTable interface to disable the table, and finally uses the isTableDisabled interface to check whether the table is in the disabled state.
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 deletes the specified HBase table. After this interface is called, the table becomes unavailable.
The interface definition is as follows:
void deleteTable(TableName tableName) throws IOException
The following example first uses the disableTable interface to disable the test table, and then uses the deleteTable interface to delete the test table.
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);
}
Consider the following points:
- If an HBase table has a namespace, specify it in the
namespace:tableNameformat. If the namespace does not exist, aNamespaceNotFoundExceptionis thrown. In OceanBase AI Database clusters, a namespace maps to a database. - If the HBase table does not exist, a
TableNotFoundExceptionis thrown. - Before dropping a table, disable it by calling the
disableTableAPI. Otherwise, aTableNotDisabledExceptionis thrown.