This topic describes how to use the HBaseAPI client in OceanBase Database, including configuring the client, connecting to an OBServer node, and performing basic addition, deletion, modification, and query operations.
Background
Based on the basic APIs provided by TableAPI, the HBaseAPI client encapsulates the APIs compatible with HBase. Currently, the features of HBase 0.94 are supported. Before using the HBaseAPI client, learn the following basic knowledge about OceanBase Database:
- HBaseAPI solution introduction
- Get started with OceanBase Database
- Connect to OceanBase Database by using a MySQL client
HBaseAPI deployment
Add client dependencies
Add the jar dependency package of the HBaseAPI client to the pom.xml file of the local Java project, or use a demo project. For more information, see Simple HBase demo.
<dependency>
<groupId>com.oceanbase</groupId>
<artifactId>obkv-hbase-client</artifactId>
<version>0.1.0</version>
</dependency>
<dependency>
<groupId>com.oceanbase</groupId>
<artifactId>obkv-table-client</artifactId>
<version>0.1.0</version>
</dependency>
Create HBase tables
For more information about how to connect to an OceanBase cluster by using OBClient or a MySQL client and create HBase tables, see HBaseAPI storage model.
Client initialization
Obtain ConfigURL
Obtain the configuration URL from the cluster deployed in OCP
- Log on to the OceanBase Cloud Platform (OCP) console.
- In the left-side navigation pane, select Cluster and then find the Clusters list.
- Click the name of the cluster to be accessed to open it.
- On the cluster details page, find the ConfigURL parameter, which must be configured when the client is initialized.
Set the username and password for logon to an OBServer node from the client
To connect to an OceanBase cluster from OBClient or a MySQL client, specify SYS_USER_NAME and SYS_PASSWORD.
The following sections take the proxyro user as an example. You must specify a password for the proxyro user. Sample statement:
GRANT SELECT ON oceanbase.* TO proxyro IDENTIFIED BY 'your password';
Set client parameters
The following sections describe two methods for setting client parameters. For more information, see Property.java. OHTable is not thread-safe. When multiple threads use OHTable at the same time, we recommend that you use OHTablePool to apply for OHTable.
Settings for using OHTable
import static com.alipay.oceanbase.rpc.property.Property.*
public class OHTableTest extends HTableTestBase {
public void test() throws IOException {
Configuration conf = new Configuration();
// <Required parameters>
conf.set("hbase.oceanbase.paramURL","your paramURL");
// The ConfigURL.
// The logon username. For example, you can set the logon username as root@sys#obcluster, in which root is the username, sys is the tenant name, and obcluster is the cluster name.
conf.set("hbase.oceanbase.fullUserName", "your fullUserName");
// The logon password. If no logon password is set, leave this field empty.
conf.set("hbase.oceanbase.password", "your logon passwd");
// The system username in the user@tenant format. For example, you can set the system username as proxyro@sys, in which proxyro is a system user inherent in the OceanBase cluster.
conf.set("hbase.oceanbase.sysUserName", "your sysUserName");
// The logon password of the system user.
conf.set("hbase.oceanbase.sysPassword", "your sysPassword");
// <Optional parameters>
c.set("rs.list.acquire.read.timeout", "10000");
// The timeout period for reading the Root Service list.
c.set("rs.list.acquire.connect.timeout", "10000");
// The timeout period for establishing a connection to retrieve the Root Service list.
c.set("rpc.connect.timeout", "1000"); // The timeout period for establishing an RPC connection.
c.set("rpc.execute.timeout", "1000"); // The socket timeout period for executing an RPC request.
hTable = new OHTable(conf, "your tablename");
}
}
Settings for using OHTablePool
import static com.alipay.oceanbase.rpc.property.Property.*;
import org.apache.hadoop.hbase.util.PoolMap;
public class OHTablePoolTest extends HTableTestBase {
private OHTablePool ohTablePool;
@Before
public void setup() throws IOException {
int poolSize=10;
PoolMap.PoolType poolType = PoolMap.PoolType.ThreadLocal; // for example
Configuration conf = new Configuration();
// <Optional parameters>
conf.set("rs.list.acquire.read.timeout", "10000"); // Same as above
conf.set("rs.list.acquire.connect.timeout", "10000");
conf.set("rpc.connect.timeout", "1000");
conf.set("rpc.execute.timeout", "1000");
ohTablePool = new OHTablePool(conf, poolSize, PoolType);
// <Required parameters>
ohTablePool.setParamUrl("tablename", "your ParamUrl");
ohTablePool.setFullUserName("tablename", "your FullUserName");
ohTablePool.setPassword("tablename", "your Password");
ohTablePool.setSysUserName("tablename", "your setSysUserName";
ohTablePool.setSysPassword("tablename", "your SysPassword";
hTable = ohTablePool.getTable("tablename");
}
}
Supported HBase operations
This section describes how to use the OHTable API. For more information, see OHTable.java. For the demo project of HBaseAPI, see Simple HBase demo.
Refresh Table Entry
Purpose: You can use this function to refresh the routing table on the client. Function prototype:
- void refreshTableEntry(String familyString, boolean hasTestLoad)
- void refreshTableEntry(final String tableName, final String family, boolean hasTestLoad)
Parameters:
- tableName: the name of the target table, which must be specified when you use OHTablePool.
- familyString: the target column family.
- hasTestLoad: whether a stress testing instrument is available, which is determined by the HBASE_HTABLE_TEST_LOAD_ENABLE parameter. If no stress testing instrument is available, set this parameter to false.
Examples:
// Use OHTable for initialization.
((OHTable) hTable).refreshTableEntry("family", false);
((OHTable) hTable).refreshTableEntry("family", true);
// Use OHTableClient for initialization.
((OHTableClient) hTable).refreshTableEntry("family", false);
((OHTableClient) hTable).refreshTableEntry("family", true);
// Use OHTablePool for initialization.
ohTablePool.refreshTableEntry("test", "family", false);
ohTablePool.refreshTableEntry("test", "family", true);
Increment Column Value
Purpose: You can use this function to increment the data in a single column of a row, and returns the incremented value if the operation succeeds. 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, which can be a negative value.
- writeToWAL: whether to pre-write logs. By default, logs are pre-written.
Examples:
// Increment a single column by 1.
String column = "incrementColumn";
String key = "incrementKey";
String family = "family";
int increment_value = 1;
long ret = hTable.incrementColumnValue(
key.getBytes(),
family.getBytes(),
column.getBytes(),
increment_value,
1);
Increment
Purpose: You can use this function to increment data of the long or int type in a single column or multiple columns of the specified row. Function prototype:
- Result increment(Increment increment)
Parameters:
- increment: the increment type. You must use addColumn to set the attribute.
Examples:
// Increment a single column by 1.
String column = "incrementColumn";
String key = "incrementKey";
String family = "family";
int increment_value = 1;
Increment increment = new Increment(key.getBytes());
increment.addColumn(family.getBytes(), column.getBytes(), increment_value);
Result r = hTable.increment(increment);
Append
Purpose: You can use this function to increment data of the string type in a single column or multiple columns of the specified row. Function prototype:
- Result append(Append append)
Parameters:
- append: the append type. You must use the add function to set the attribute.
Examples:
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);
Assert.assertEquals(1, r.raw().length);
for (KeyValue kv : r.raw()) {
Assert.assertEquals("_append", Bytes.toString(kv.getValue()));
}
Check And Delete
Purpose: You can use this function to delete a column meeting the specified condition. It returns true if a column meeting the condition 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.
Examples:
String key = "deleteKey";
String family = "family";
String column = "column";
delete = new Delete(key.getBytes());
delete.deleteColumn(family.getBytes(), column.getBytes());
boolean ret = hTable.checkAndDelete(
key.getBytes(),
family.getBytes(),
column.getBytes(),
value.getBytes(),
delete);
Delete
Purpose: You can use this function to delete specified cells or rows. Function prototype:
- void delete(Delete delete)
- void delete(List<Delete> deletes)
Parameters:
- deletes: the rows to be deleted, which are specified by using the deleteFamily function.
Examples:
// Delete the row corresponding to a key, family, or column.
String key = "delete_row";
String family = "family";
String column = "column";
Delete delete = new Delete(key.getBytes());
delete.deleteFamily(family.getBytes(), column.getBytes());
hTable.delete(delete);
Check And Put
Purpose: You can use this function to check and replace the data of a specified column. It returns true if the data of a column meeting the condition 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.
Examples:
String key = "putkey";
String family = "family"
String column = "column";
String value = "value";
String new_value = "value_new"
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);
Put
Purpose: You can use this function to insert data. Function prototype:
- void put(Put put)
- void put(List<Put> puts)
Parameters:
- put: a put object, which means to insert a single record.
- puts: put objects, which means to insert multiple records at a time.
Examples:
// Insert a single record.
String key = "putKey";
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.
String column = "column";
String value = "value";
String family = "family";
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);
Scan
Purpose: You can use this function to scan a table based on 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 name of the target column for filtering.
- scan: the Scan object, which is specified by using the addFamily or addColumn function.
Examples:
// Specify the scan object.
String startKey = "startKey";
String endKey = "endKey";
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 result : scanner) {
for (KeyValue keyValue : result.raw()) {
// User operation, for example:
System.out.println("rowKey: " + new String(keyValue.getRow())
+ " columnQualifier:" + new String(keyValue.getQualifier())
+ " timestamp:" + keyValue.getTimestamp() + " value:"
+ new String(keyValue.getValue()));
}
}
Get
Purpose: You can use this function to obtain the data of the specified row. Function prototype:
- Result get(final Get get)
- Result[] get(List<Get> gets)
Parameters:
- get: the Get object, which is specified by using the addColumn or addFamily function.
- gets: the list of Get objects.
Examples:
// Obtain one family.
String key = "getKey";
String family = "family";
int maxVersion = 1;
Get get = new Get(key.getBytes());
get.addFamily(family.getBytes());
get.setMaxVersions(maxVersion);
Result result = hTable.get(get);
Exists
Purpose: You can use this function to determine whether the column family or column specified in the Get object exists. If it exists, true is returned. Otherwise, false is returned. Function prototype:
- boolean exists(Get get)
Parameters:
- get: the Get object, which is specified by using the addFamily or addColumn function.
Examples:
String key = "existKey";
String family = "family";
get = new Get(key.getBytes());
get.addFamily(family.getBytes());
Assert.assertTrue(hTable.exists(get));
Get Configuration
Purpose: You can use this function to return the config handle of an operation instance. It can be used to change an attribute during operations. Function prototype:
- Configuration getConfiguration()
Parameters:
None
Examples:
hTable.getConfiguration().set(HBASE_HTABLE_TEST_LOAD_ENABLE, "true");
hTable.getConfiguration().set(HBASE_HTABLE_TEST_LOAD_SUFFIX, "_a");
hTable.getConfiguration().set("rs.list.acquire.read.timeout", "10000");