Data operation examples|V4.2.1| docs|Distributed Database

Data operation examples

Last Updated：2024-08-13 01:52:31 Updated

This topic provides examples to describe how to process data on the OBKV-HBase client.

Note

For the list of APIs supported by the OBKV-HBase client, see "Compatibility with HBase".

Preparations

Before you perform data operations on the client, make sure that the following conditions are met:

You have deployed an OceanBase cluster. For more information about the supported deployment solutions, deployment methods, and deployment procedure, see Deployment.
You have created a MySQL 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 Data model design.

The table used by examples in this topic is htable1$family. You can create the table by referring to the following statements:
```
CREATE TABLEGROUP htable1;

CREATE TABLE htable1$family (
  K varbinary(1024),
  Q varbinary(256),
  T bigint,
  V varbinary(1048576) NOT NULL,
  PRIMARY KEY(K, Q, T))
  TABLEGROUP =  htable1 ;
```
You have deployed and configured the OBKV-HBase client and connected to the cluster by using an OHTable. For more information, see Connect to a cluster by using the OBKV-HBase client.

Considerations

The execution results in the following examples depend on the operation sequence. To reproduce the execution results, follow the operation sequence.
To vividly observe the operation results in the database, the examples use the MySQL client to connect to OBKV-HBase and query status of the htable1$family table by using SQL statements.

Put

Function description:

You can call this function to insert data.

Function prototype:

void put(Put put)
void put(List puts)

Parameters:

put: a Put object, which means to insert a single record.
puts: a list of Put objects, which means to insert multiple records at a time.

Example:

// Insert a single record.
String key = "testKey0";
String family = "family";
String column = "column";
String value = "putValue";
Put put = new Put(key.getBytes());
put.add(family.getBytes(), column.getBytes(), value.getBytes());
hTable.put(put);

// Insert multiple records.
Put put1 = new Put(Bytes.toBytes("testKey1"));
put1.add(toBytes(family), toBytes(column), toBytes(value));
//put1.add(toBytes(family), toBytes(column), System.currentTimeMillis(), toBytes(value));

Put put2 = new Put(Bytes.toBytes("testKey2"));
put2.add(toBytes(family), toBytes(column), toBytes(value));
//put2.add(toBytes(family), toBytes(column), System.currentTimeMillis(), toBytes(value));
List<Put> puts = new ArrayList<Put>();
puts.add(put1);
puts.add(put2);
hTable.put(puts);

MySQL [test]> select * from htable1$family;
+----------+--------+----------------+----------+
| K        | Q      | T              | V        |
+----------+--------+----------------+----------+
| testKey0 | column | -1715961035391 | putValue |
| testKey1 | column | -1715961035471 | putValue |
| testKey2 | column | -1715961035471 | putValue |
+----------+--------+----------------+----------+

Remarks:

In the preceding example, three cells are inserted into the database.

Get

Function description:

You can call this function to obtain the data of the specified row.

Function prototype:

Result get(final Get get)
Result[] get(List gets)

Parameters:

get: a Get object, which is specified by using the addColumn or addFamily function.
gets: a list of Get objects.

Example:

// Obtain one family.
String key = "testKey0";
String family = "family";
int maxVersion = 1;
Get get = new Get(key.getBytes());
get.addFamily(family.getBytes());
get.setMaxVersions(maxVersion);
Result result = hTable.get(get);
if (result.list() != null) {
    System.out.printf("Get Demo: get cnt:%d%n", result.list().size());
}

String key = "testKey0";
Get get = new Get(key.getBytes());
Result result = hTable.get(get);
if (result.list() != null) {
    System.out.printf("Get Demo: get cnt:%d%n", result.list().size());
}

MySQL [test]> select * from htable1$family where k = "testKey0";
+----------+--------+----------------+----------+
| K        | Q      | T              | V        |
+----------+--------+----------------+----------+
| testKey0 | column | -1715961561057 | putValue |
+----------+--------+----------------+----------+

Remarks:

In the example, the semantics of Get are equivalent to those of the preceding SQL statement when only one data version exists in HBase.
The get operation is performed following the put operation. Therefore, the database has a cell whose primary key is testKey0.

Scan

Function description:

You can call this function to scan 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, which is specified by using the addFamily or addColumn function.

Example:

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());
    }
}

MySQL [test]> select * from htable1$family where k >= "testKey" && k < "testKey9";
+----------+--------+----------------+----------+
| K        | Q      | T              | V        |
+----------+--------+----------------+----------+
| testKey0 | column | -1715961561057 | putValue |
| testKey1 | column | -1715961561132 | putValue |
| testKey2 | column | -1715961561132 | putValue |
+----------+--------+----------------+----------+

Remarks:

In the example, the semantics of Scan are equivalent to those of the preceding SQL statement when only one data version exists in HBase.
In HBase 0.94, the range defined by startKey and endKey is left-closed and right-open. In other words, data of endKey cannot be scanned.
The scan operation is performed following the put operation. Therefore, the database has three cells that meet the conditions.

Increment Column Value

Function description:

You can call this function to increment a single column in the specified row. If the function is successfully executed, the new value of the column is returned. The cell of the column must be of the long type, which is used to store a 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 pre-write logs. This parameter is not required in 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, you may notice that no value is displayed in the V column of a cell. In this case, the value that should have been displayed in the V column can be displayed in the hex(v) column.
If the Increment Column Value function fails to query a cell that meets the conditions from the database, it will generate a cell where the default value is 0 and proceed with the increment.

Increment

Function description:

You can call this function to increment one or more columns in the specified row. The cell of the column or columns must be of the long type, which is used to store a 64-bit integer.

Function prototype:

Result increment(Increment increment)

Parameters:

increment: an Increment object, whose attributes are specified by using the addColumn function.

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:

Calling the Increment function on a cell multiple times will generate cells of multiple versions. The semantics of the update operation are not supported in HBase. Therefore, a modification of a cell will generate a cell of a new version. You can specify the version for query.

Append

Function description:

You can call this function to append data to one or more columns of a character type, such as byte or string, in the specified row.

Function prototype:

Result append(Append append)

Parameters:

append: an Append object, whose attributes are specified by using the add function.

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("Appand 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:

If the Append function fails to query a cell that meets the conditions from the database, it will insert a corresponding cell where the default value is an empty string and append data to the cell.

Delete

Function description:

You can call this function to delete the specified cells or rows.

Function prototype:

void delete(Delete delete)
void delete(List deletes)

Parameters:

deletes: a Delete object, which refers to the cells or rows to be deleted here. It is specified by using the deleteColumn or deleteFamily function.

Example:

// Delete a row with the specified key, family, and column.
String key = "testKey1";
String family = "family";
String column = "column";
Delete delete = new Delete(key.getBytes());
delete.deleteColumn(family.getBytes(),column.getBytes());
hTable.delete(delete);

MySQL [test]> select * from htable1$family;
+--------------+-----------------+----------------+----------+
| K            | Q               | T              | V        |
+--------------+-----------------+----------------+----------+
| appendKey    | appendColumn    | -1715961265748 | _append  |
| incrementKey | incrementColumn | -1715961228139 |          |
| incrementKey | incrementColumn | -1715961188112 |          |
| testKey0     | column          | -1715961035391 | putValue |
| testKey2     | column          | -1715961035471 | putValue |
+--------------+-----------------+----------------+----------+

Remarks:

The preceding query results show that the cells whose primary key is testKey1 are all deleted.

Exists

Function description:

You can call this function to determine whether the column family or column specified in a Get object exists. If it exists, true is returned. Otherwise, false is returned.

Function prototype:

boolean exists(Get get)

Parameters:

get: a Get object, which is specified by using the addFamily or addColumn function.

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:

You can call this function to check and replace the data of the specified column. It returns true if the column exists and its data is replaced, and returns false otherwise.

Function prototype:

boolean checkAndPut(byte[] row, byte[] family, byte[] qualifier, byte[] value, Put put)

Parameters:

row: the target row key.
family: the target column family.
qualifier: the name of the target column.
value: the value of the target column.
put: the new column value.

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 testKey2 and value is putValue is modified to generate a cell of a new version whose value is value_new.

Check And Delete

Function description:

You can call this function to delete the specified column. It returns true if the specified column exists and is deleted, and returns false otherwise.

Function prototype:

boolean checkAndDelete(byte[] row, byte[] family, byte[] qualifier, byte[] value, Delete delete)

Parameters:

row: the target row key.
family: the target column family, which is specified when the table is created.
qualifier: the name of the target column.
value: the value of the target column.
delete: the column to delete.

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 testKey2 and value is value_new is deleted.

Get Configuration

Function description:

You can call this function to return the config handle of an operation instance. It can be used to change attributes for an operation.

Function prototype:

Configuration getConfiguration()

Parameters:

None

Example:

hTable.getConfiguration().set("rpc.execute.timeout", "1500");