This topic provides examples to describe how to process data by using the OBKV-HBase client.
Note
For a list of interfaces supported by the OBKV-HBase client, see HBase-compatible interfaces.
Prerequisites
Before you try the following examples, make sure that the following conditions are met:
You have deployed an OceanBase AI Database cluster. For more information about the supported deployment solutions, deployment methods, and deployment procedure, see Deployment overview.
You have created a user tenant. For more information, see Create a tenant.
You have created a database. For more information, see Create a database.
You have created an OBKV-HBase data table. For more information, see OBKV-HBase data model.
In this example, the table group name is htable1. Each table corresponds to a column family, and you can create tables as needed. The following is an example of table creation:
CREATE TABLEGROUP htable1; CREATE TABLE htable1$family1 ( `K` varbinary(1024) NOT NULL, `Q` varbinary(256) NOT NULL, `T` bigint(20) NOT NULL, `V` varbinary(1024) DEFAULT NULL, PRIMARY KEY (`K`, `Q`, `T`) ) TABLEGROUP = htable1 PARTITION BY KEY(`K`) PARTITIONS 3; CREATE TABLE htable1$family2 ( `K` varbinary(1024) NOT NULL, `Q` varbinary(256) NOT NULL, `T` bigint(20) NOT NULL, `V` varbinary(1024) DEFAULT NULL, PRIMARY KEY (`K`, `Q`, `T`) ) TABLEGROUP = htable1 PARTITION BY KEY(`K`) PARTITIONS 3; CREATE TABLE htable1$family3 ( `K` varbinary(1024) NOT NULL, `Q` varbinary(256) NOT NULL, `T` bigint(20) NOT NULL, `V` varbinary(1024) DEFAULT NULL, PRIMARY KEY (`K`, `Q`, `T`) ) TABLEGROUP = htable1 PARTITION BY KEY(`K`) PARTITIONS 3;This example connects to the OBKV-HBase cluster by using OHTable for data processing. Make sure that you have deployed and configured the OBKV-HBase client and connected to the cluster by using OHTable. For more information, see Connect to a cluster by using the OBKV-HBase Java client.
Considerations
- The execution results in the following examples depend on the order of operations. To reproduce the results, perform the operations in sequence.
- To make the results in the database easier to observe, the examples use the MySQL client to connect to OBKV-HBase and query the table status by using SQL.
Notice
The put, delete, get, and scan interfaces of OBKV-HBase support multiple column families.
Put
Notice
To optimize HBase PUT performance, use the new version of the client. The HBase client version must be 1.4.0 or later, or 2.4.0 or later.
Function description:
You can call this function to insert data into a row and specify multiple columns. It supports multiple column families, and writes to multiple column families are atomic.
If no version (timestamp) is specified, the version of the columns written this time is the timestamp obtained by the server at execution time, and the versions of the columns written across multiple column families are consistent.
Function prototype:
- void put(Put put)
- void put(List
puts)
Parameters:
put: A Put object, which indicates that a single record is to be inserted.puts: A list of Put objects, which indicates that multiple records are to be inserted at a time.
Example:
Put put = new Put("testKey0".getBytes());
put.add("family1".getBytes(), "column1".getBytes(), "value1-1".getBytes());
put.add("family1".getBytes(), "column2".getBytes(), "value1-2".getBytes());
put.add("family2".getBytes(), "column3".getBytes(), "value2-3".getBytes());
put.add("family3".getBytes(), "column4".getBytes(), "value3-4".getBytes());
hTable.put(put);
MySQL [test]> SELECT * FROM htable1$family1;
+----------+---------+----------------+---------+
| K | Q | T | V |
+----------+---------+----------------+---------+
| testKey0 | column1 | -1730184389941 | value1-1|
| testKey0 | column2 | -1730184389941 | value1-2|
+----------+---------+----------------+---------+
2 rows in set
MySQL [test]> SELECT * FROM htable1$family2;
+----------+---------+----------------+---------+
| K | Q | T | V |
+----------+---------+----------------+---------+
| testKey0 | column3 | -1730184389941 | value2-3|
+----------+---------+----------------+---------+
1 row in set
MySQL [test]> SELECT * FROM htable1$family3;
+----------+---------+----------------+---------+
| K | Q | T | V |
+----------+---------+----------------+---------+
| testKey0 | column4 | -1730184389941 | value3-4|
+----------+---------+----------------+---------+
1 row in set
Get
Function description:
- You can call this function to obtain the data of a specified row.
Function prototype:
- Result get(final Get get)
- Result[] get(List
gets)
Parameters:
get: A Get object. You must use theaddColumnoraddFamilyfunction to specify the operation target. You can combine and operate on multiple column families in a single-row GET operation. The return values are sorted in lexicographical order by the key column/Q column.addColumn:- Specifies a specific column to retrieve.
- Requires the column family and column qualifier.
- Suitable for scenarios where you need to accurately obtain data from a single column.
- Returns only the value of the specified column.
addFamily:- Specifies an entire column family to retrieve.
- Requires only the name of the column family.
- Suitable for scenarios where you need to retrieve data from all columns in a column family.
- Returns the values of all columns in the specified column family.
gets: A list of Get objects, which is used to store the Get objects.
Example:
// Get Family
int maxVersion = 1;
Get get = new Get("testKey0".getBytes());
get.addColumn("family1".getBytes(), "column1".getBytes());
get.addFamily("family2".getBytes());
Result result = hTable.get(get);
for (Cell cell : result.rawCells()) {
System.out.println(new String(CellUtil.cloneRow(cell)) + " "
+ new String(CellUtil.cloneFamily(cell)) + " "
+ new String(CellUtil.cloneQualifier(cell)) + " "
+ new String(CellUtil.cloneValue(cell)));
}
// The output is as follows:
// testKey0 family1 column1 value1-1
// testKey0 family2 column3 value2-3
-- The preceding GET operation is converted into the following SQL query:
MySQL [test]> SELECT * FROM htable1$family1 WHERE k = "testKey0" AND Q = 'column1';
+----------+---------+----------------+---------+
| K | Q | T | V |
+----------+---------+----------------+---------+
| testKey0 | column1 | -1730184389941 | value1-1|
+----------+---------+----------------+---------+
1 row in set
MySQL [test]> SELECT * FROM htable1$family2 WHERE k = "testKey0";
+----------+---------+----------------+---------+
| K | Q | T | V |
+----------+---------+----------------+---------+
| testKey0 | column3 | -1730184389941 | value2-3|
+----------+---------+----------------+---------+
1 row in set
Scan
Function description:
- Scans a table based on the specified conditions (
scan/family/qualifier).
Function prototype:
- ResultScanner getScanner(byte[] family, byte[] qualifier)
- ResultScanner getScanner(final byte[] family)
- ResultScanner getScanner(final Scan scan)
Parameters:
family: The target column family for filtering.qualifier: The target column name for filtering.scan: A Scan object whose operation target is specified by using theaddFamilyoraddColumnfunction.addColumn:- Specifies a particular column to retrieve.
- Requires both the column family and the qualifier.
- Suitable for scenarios where you need to accurately obtain data from a single column.
- Returns only the value of the specified column.
addFamily:- Specifies an entire column family to retrieve.
- Requires only the name of the column family.
- Suitable for scenarios where you need to obtain data from all columns in the column family.
- Returns the values of all columns in the column family.
Example:
Scan scan = new Scan("testKey0".getBytes());
scan.addColumn("family1".getBytes(), "column1".getBytes());
scan.addFamily("family2".getBytes());
scan.setStartRow("testKey0".getBytes());
ResultScanner scanner = hTable.getScanner(scan);
for (Result r : scanner) {
for (Cell cell : r.rawCells()) {
System.out.println(new String(CellUtil.cloneRow(cell)) + " "
+ new String(CellUtil.cloneFamily(cell)) + " "
+ new String(CellUtil.cloneQualifier(cell)) + " "
+ new String(CellUtil.cloneValue(cell)));
}
}
// The output is as follows:
// testKey0 family1 column1 value1-1
// testKey0 family2 column3 value2-3
-- The preceding SCAN operation is converted into the following SQL query:
MySQL [test]> SELECT *
-> FROM htable1$family2
-> WHERE K >= "testKey0"
-> UNION
-> SELECT *
-> FROM htable1$family1
-> WHERE K >= "testKey0" AND Q = "column1";
+----------+---------+----------------+---------+
| K | Q | T | V |
+----------+---------+----------------+---------+
| testKey0 | column1 | -1730184389941 | value1-1|
| testKey0 | column3 | -1730184389941 | value2-3|
+----------+---------+----------------+---------+
2 rows in set
OBKV-HBase supports reverse scan, which allows you to scan data in a table in reverse order by row key (from largest to smallest), as opposed to the regular forward scan (from smallest to largest).
Notice
Reverse scan supports subpartitions and can be combined with any key/range or K_PREFIX partitioning key for composite queries.
The following is an example of forward scan:
// Forward scan.
String startKey = "testKey";
String endKey = "testKey9";
String family = "family";
String column = "column";
int maxVersion = 1;
Scan scan = new Scan();
scan.addColumn(family.getBytes(), column.getBytes());
scan.setMaxVersions(maxVersion);
scan.setStartRow(startKey.getBytes());
scan.setStopRow(endKey.getBytes());
ResultScanner scanner = hTable.getScanner(scan);
for (Result r : scanner) {
for (KeyValue kv : r.list()) {
System.out.printf("Scan Demo: Rowkey: %s, Column Family: %s, Column Qualifier: %s, Value: %s, Timestamp: %d%n",
Bytes.toString(r.getRow()),
Bytes.toString(kv.getFamily()),
Bytes.toString(kv.getQualifier()),
Bytes.toString(kv.getValue()),
kv.getTimestamp());
}
}
The query result is as follows:
+----------+--------+----------------+----------+
| K | Q | T | V |
+----------+--------+----------------+----------+
| testKey0 | column | -1715961561057 | putValue |
| testKey1 | column | -1715961561132 | putValue |
| testKey2 | column1 | -1715961561132 | putValue |
| testKey2 | column2 | -1715961561132 | putValue |
+----------+--------+----------------+----------+
4 rows in set
The following is an example of reverse scan:
// Reverse scan.
String startKey = "testKey9";
String endKey = "testKey";
String family = "family";
String column = "column";
int maxVersion = 1;
Scan scan = new Scan();
scan.addColumn(family.getBytes(), column.getBytes());
scan.setMaxVersions(maxVersion);
scan.setStartRow(startKey.getBytes());
scan.setStopRow(endKey.getBytes());
// Set to enable reverse scan.
scan.setReversed(true);
ResultScanner scanner = hTable.getScanner(scan);
for (Result r : scanner) {
for (KeyValue kv : r.list()) {
System.out.printf("Scan Demo: Rowkey: %s, Column Family: %s, Column Qualifier: %s, Value: %s, Timestamp: %d%n",
Bytes.toString(r.getRow()),
Bytes.toString(kv.getFamily()),
Bytes.toString(kv.getQualifier()),
Bytes.toString(kv.getValue()),
kv.getTimestamp());
}
}
The query result is as follows:
+----------+--------+----------------+----------+
| K | Q | T | V |
+----------+--------+----------------+----------+
| testKey2 | column1 | -1715961561132 | putValue |
| testKey2 | column2 | -1715961561132 | putValue |
| testKey1 | column | -1715961561132 | putValue |
| testKey0 | column | -1715961561057 | putValue |
+----------+--------+----------------+----------+
4 rows in set
Increment column value
Function description:
- Increments the value of a single column in a row by 1. If the operation succeeds, the incremented value is returned. The cell of the specified column must be of the LONG type (64-bit integer).
Function prototype:
- long incrementColumnValue(byte[] row, byte[] family, byte[] qualifier, long amount, boolean writeToWAL)
Parameters:
row: The row key.family: The target column family, which is specified when the table is created.qualifier: The name of the target column.amount: The increment step, which can be negative.writeToWAL: Specifies whether to write the write-ahead log in advance. This parameter is not required for OBKV-HBase.
Example:
// Increment a single column by 1.
String column = "incrementColumn";
String key = "incrementKey";
String family = "family";
long increment_value = 1L;
long ret = hTable.incrementColumnValue(
key.getBytes(),
family.getBytes(),
column.getBytes(),
increment_value);
System.out.printf("Increment Column Demo: ret: %b%n", ret);
MySQL [test]> select *,hex(v) from htable1$family where k = "incrementKey";
+--------------+-----------------+----------------+----------+------------------+
| K | Q | T | V | hex(v) |
+--------------+-----------------+----------------+----------+------------------+
| incrementKey | incrementColumn | -1715961669857 | | 0000000000000001 |
+--------------+-----------------+----------------+----------+------------------+
Remarks:
- If you use the MySQL client to view an HBase table, the V column of the corresponding cell may be empty. You can use
hex(v)to display the value. - As shown above, if no matching cell is found in the database, Increment creates a cell with the default value
0and then performs the increment operation.
Increment
Function description:
- Increments the value of one or more columns in a specified row. The cells of the specified columns must be of the LONG type (64-bit integers).
Function prototype:
- Result increment(Increment increment)
Parameters:
increment: An Increment object whose attributes are set by using theaddColumnmethod.
Example:
// Increment a single column by 1.
String column = "incrementColumn";
String key = "incrementKey";
String family = "family";
long increment_value = 1L;
Increment increment = new Increment(key.getBytes());
increment.addColumn(family.getBytes(), column.getBytes(), increment_value);
Result r = hTable.increment(increment);
for (KeyValue kv : r.list()) {
System.out.printf("Increment Demo: Rowkey: %s, Value:%s%n",
Bytes.toString(r.getRow()),
Bytes.toLong(kv.getValue()));
}
MySQL [test]> select *,hex(v) from htable1$family where k = "incrementKey";
+--------------+-----------------+----------------+----------+------------------+
| K | Q | T | V | hex(v) |
+--------------+-----------------+----------------+----------+------------------+
| incrementKey | incrementColumn | -1715961734681 | | 0000000000000002 |
| incrementKey | incrementColumn | -1715961669857 | | 0000000000000001 |
+--------------+-----------------+----------------+----------+------------------+
Remarks:
- As shown above, performing multiple increments on a cell generates multiple versions of the cell. HBase does not support the semantics of the UPDATE operation, so a modification to a cell results in multiple versions. You can query a specified version.
Append
Function description:
- Appends data to one or more columns (for character types such as byte and string) in a specified row.
Function prototype:
- Result append(Append append)
Parameters:
append: An Append object whose attributes are set by using theaddfunction.
Example:
String column = "appendColumn";
String key = "appendKey";
String family = "family";
Append append = new Append(key.getBytes());
append.add(family.getBytes(), column.getBytes(), toBytes("_append"));
Result r = hTable.append(append);
for (KeyValue kv : r.list()) {
System.out.printf("Append Demo: Rowkey: %s, Append Value:%s%n",
Bytes.toString(r.getRow()),
Bytes.toString(kv.getValue()));
}
MySQL [test]> select * from htable1$family where k = "appendKey";
+-----------+--------------+----------------+---------+
| K | Q | T | V |
+-----------+--------------+----------------+---------+
| appendKey | appendColumn | -1715961265748 | _append |
+-----------+--------------+----------------+---------+
Remarks:
- As shown above, if no matching cell is found in the database, Append inserts a cell with an empty string as the default value and then performs the append operation.
Delete
Function description:
- Deletes specified cells or rows.
Function prototype:
- void delete(Delete delete)
- void delete(List
deletes)
Parameters:
delete: A Delete object that refers to the rows to be deleted. It is set by using thedeleteColumn,deleteColumns, ordeleteFamilyfunction. You can combine and operate on multiple column families in a single-row DELETE operation.deleteColumn:- Deletes a single column of a specific version.
- Requires the column family, column qualifier, and timestamp.
- Suitable for scenarios where you need to delete data of a specific version.
deleteColumns:- Deletes all versions of a column.
- Requires only the column family and column qualifier.
- Suitable for scenarios where you need to delete all historical data of a column.
deleteFamily:- Deletes all columns and all versions of their data in a specified column family.
- Requires only the name of the column family.
- Suitable for scenarios where you need to clear all data in a column family.
Example:
// Delete all columns from family1 and column3 from family2.
// If you get the data again at this point, only the values of columns other than column3 for families 1 and 2 will be returned.
Delete delete = new Delete(toBytes("testKey0"));
delete.deleteFamily("family1".getBytes());
delete.deleteColumns("family2".getBytes(), "column3".getBytes());
hTable.delete(delete);
// Delete all columns for testKey0. A subsequent Get request will return no results.
Delete delete = new Delete(toBytes("testKey0"));
hTable.delete(delete);
Exists
Function description:
- Checks whether the column family or column specified in a Get object exists. Returns
trueif it exists, andfalseotherwise.
Function prototype:
- boolean exists(Get get)
Parameters:
get: A Get object whose operation target is set by usingaddFamilyoraddColumn.
Example:
String key = "testKey2";
String family = "family";
Get get = new Get(key.getBytes());
get.addFamily(family.getBytes());
boolean ret = hTable.exists(get);
System.out.printf("Exist Demo: ret: %b%n", ret);
MySQL [test]> select * from htable1$family where k = "testKey2";
+----------+--------+----------------+----------+
| K | Q | T | V |
+----------+--------+----------------+----------+
| testKey2 | column | -1715961561132 | putValue |
+----------+--------+----------------+----------+
Remarks:
- The semantics of Exists are equivalent to those of Get.
Check and put
Function description:
- Checks and replaces the data in a specified column. Returns
trueif the condition is met and the replacement succeeds; otherwise, returnsfalse.
Function prototype:
- boolean checkAndPut(byte[] row, byte[] family, byte[] qualifier, byte[] value, Put put)
Parameters:
row: The key of the target row.family: The column family of the target row.qualifier: The name of the target column.value: The value of the target column.put: The new value to set for the column.
Example:
String key = "testKey2";
String family = "family";
String column = "column";
String value = "putValue";
String new_value = "value_new";
Put put = new Put(key.getBytes());
put.add(family.getBytes(), column.getBytes(), new_value.getBytes());
boolean ret = hTable.checkAndPut(
key.getBytes(),
family.getBytes(),
column.getBytes(),
value.getBytes(),
put);
System.out.printf("CheckAndPut Demo: ret: %b%n", ret);
MySQL [test]> select * from htable1$family where k = "testKey2";
+----------+--------+----------------+-----------+
| K | Q | T | V |
+----------+--------+----------------+-----------+
| testKey2 | column | -1715961408587 | value_new |
| testKey2 | column | -1715961035471 | putValue |
+----------+--------+----------------+-----------+
Remarks:
- The cell whose primary key is
testKey2and value isputValueis modified, generating a new version of the cell with the valuevalue_new.
Check and delete
Function description:
- Checks for a matching row and deletes it. Returns
trueif a match is found and the deletion succeeds; otherwise, returnsfalse.
Function prototype:
- boolean checkAndDelete(byte[] row, byte[] family, byte[] qualifier, byte[] value, Delete delete)
Parameters:
row: The key of the target row.family: The column family of the target row. This is the column family specified when the table is created.qualifier: The name of the target column.value: The value of the target column.delete: The column to be deleted.
Example:
String key = "testKey2";
String family = "family";
String column = "column";
String value = "value_new";
Delete delete = new Delete(key.getBytes());
delete.deleteColumn(family.getBytes(), column.getBytes());
boolean ret = hTable.checkAndDelete(
key.getBytes(),
family.getBytes(),
column.getBytes(),
value.getBytes(),
delete);
System.out.printf("CheckAndDelete Demo: ret: %b%n", ret);
MySQL [test]> select * from htable1$family where k = "testKey2";
+----------+--------+----------------+----------+
| K | Q | T | V |
+----------+--------+----------------+----------+
| testKey2 | column | -1715961035471 | putValue |
+----------+--------+----------------+----------+
Remarks:
- The cell whose primary key is
testKey2and value isvalue_newis deleted and no longer exists in the database.
Get configuration
Function description:
- Returns the configuration handle of an operation instance, which can be used to modify attributes during the operation.
Function prototype:
- Configuration getConfiguration()
Parameters:
- None
Example:
hTable.getConfiguration().set("rpc.execute.timeout", "1500");