OBKV-HBase supports connecting to an OBKV-HBase cluster using the OBKV-HBase client and invoking HBase-compatible APIs for data processing. If your business currently uses native HBase data operation logic, you can deploy an OceanBase cluster, create an HBase table on the OBServer side, and perform data operations through the OBKV-HBase client. This topic describes how to configure the client, connect to an OBServer, and perform basic CRUD operations.
OBKV-HBase client
The OBKV-HBase client is based on the basic interfaces provided by OBKV-HBase and encapsulates HBase-compatible APIs on the client side. It is currently compatible with the features of HBase version 0.94.
Prerequisites
Before using the OBKV-HBase client to connect to an OBKV-HBase cluster for data processing, ensure that the following prerequisites are met:
- You have created an OBKV cluster. For information about supported deployment solutions, methods, and detailed deployment procedures, see Create a cluster.
- You have created an OBKV tenant. For detailed operations on creating a tenant, see Create a tenant.
- You have created a database.
- You have created an OBKV-HBase data table. For detailed operations on creating an OBKV-HBase data table, see Database schema design.
Example:
-- First, create a table group named htable1.
CREATE TABLEGROUP htable1;
-- Create a test table named htable1$family1 bound to the htable1 table group.
CREATE TABLE htable1$family1 (
K varbinary(1024),
Q varbinary(256),
T bigint,
V varbinary(1048576) NOT NULL,
PRIMARY KEY(K, Q, T))
TABLEGROUP = htable1;
Step 1: Add client dependencies
Add the OBKV-HBase client JAR package dependency to the local Java project's pom.xml file (or refer to OBKV-HBase usage demo).
<dependency>
<groupId>com.oceanbase</groupId>
<artifactId>obkv-hbase-client</artifactId>
<version>0.1.4</version>
</dependency>
Notice
- Use the latest version of the JAR package whenever possible. Older versions may not support new servers.
- The version number here may not be the latest. Refer to the published OBKV-HBase versions in the Central Repository and replace the version number with the latest published version.
Step 2: Set client connection parameters
OBKV-HBase has different deployment methods in public and private clouds, and the client connection parameters required for configuration also vary. If you are deploying an OceanBase cluster on-premises, refer to the direct connection mode configuration. If you are using the public cloud OBKV service, refer to the cloud mode.
Direct connection mode configuration (On-premises deployment)
## Assume the current cluster is as follows
## ClusterName: obkvcluster
## TenantName: obkv
## DataBaseName: test
## UserName: root
## SYS_USER_NAME: sysroot
#### Required items
Configuration conf = new Configuration();
## The format is userName@tenantName#clusterName.
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root@obkv#obkvcluster");
## Password for the OceanBase user specified by userName in fullUserName.
conf.set(HBASE_OCEANBASE_PASSWORD, "");
## The URL for obtaining the RSlist from the obconfig server. For details, see Config URL.
conf.set(HBASE_OCEANBASE_PARAM_URL, "");
## The username under the system tenant. Only users under the system tenant have permission to access the routing table.
conf.set(HBASE_OCEANBASE_SYS_USER_NAME, "sysroot");
## The password for the system tenant user.
conf.set(HBASE_OCEANBASE_SYS_PASSWORD, "");
#### Optional items
## The timeout period for request execution (select based on business characteristics), in ms. The following example indicates a timeout of 1s.
conf.set("rpc.execute.timeout", "1000");
You can obtain the Config URL in the following ways.
Obtain the Config URL from OCP
If you are using OCP, you can obtain the Config URL from it.
- Log in to the OCP console.
- In the left-side navigation pane, select Cluster. Scroll down to find Cluster List.
- Click the name of the cluster you want to access.
- On the cluster details page, locate the ConfigURL parameter. This parameter needs to be configured during client initialization.
Deploy a Config Server using OBD and obtain the Config URL
If you are not using OCP, you need to deploy a Config Server using the command line and obtain the ObRootServiceInfoUrl.
Configure the cloud mode (public cloud)
## Assume the current cluster is as follows.
## DataBaseName: test
## UserName: root
#### Required
Configuration conf = new Configuration();
## The username for creating a database. No three-part format is required. Use username.
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root");
## User password
conf.set(HBASE_OCEANBASE_PASSWORD, "");
## See the remarks on ODP Address.
conf.set(HBASE_OCEANBASE_ODP_ADDR, "");
## The OBKV port is 3307 (fixed).
conf.setInt(HBASE_OCEANBASE_ODP_PORT, "3307");
## Use ODP mode in the cloud (fixed).
conf.setBoolean(HBASE_OCEANBASE_ODP_MODE, true);
## The name of the database.
conf.set(HBASE_OCEANBASE_DATABASE, "test");
#### Optional
## The timeout period for request execution (configure based on your business characteristics).
conf.set("rpc.execute.timeout", "1000");
You can obtain the ODP Address as follows: Go to the OceanBase Cloud tenant console and view the deployment diagram.
Connect to an OceanBase cluster
After setting the client connection parameters, initialize the client. Currently, two methods are supported: OHTableClient and OHTablePool. The differences between them are as follows:
- OHTableClient: Not thread-safe. There is only one OHTable handle internally. Multiple threads accessing the same OHTable simultaneously may cause unpredictable issues (use this method in single-thread scenarios).
- OHTablePool: An OHTable pool. Obtain an OHTable instance for the corresponding table from the pool when needed (use this method in multi-thread scenarios).
Connect using OHTable
// Set the configuration. Refer to the previous section; details are omitted here.
Configuration conf = new Configuration(); // Create the configuration.
conf.set(xxx); // Set various parameters.
OHTableClient hTable = new OHTableClient("test1", conf); // Create an htable object.
hTable.init(); // Initialize hTable.
//Execute the relevant logic.
hTable.close(); // Close the hTable object.
Connect using OHTablePool
OBKV-HBase provides a table pool mode to manage multiple table operation instances. Currently, the resource pool includes three methods: Reusable, RoundRobin, and ThreadLocal. You can specify which mode to use when instantiating the table pool.
The usage is the same as that of HBase's HTablePool. When you need the HTable for a specific table, use pool.getTable("xx") to obtain it. Note the following:
- Parameter precedence: Table-specific parameters (such as pool.setOdpAddr()) > parameters set in the configuration file > default parameters.
- Remember to call close() after using the HTable to return the OHTable to the pool. It is recommended to use try/finally blocks to ensure the HTable is returned.
// Set the configuration. Refer to the previous section; details are omitted here.
Configuration conf = new Configuration(); // Create the configuration item.
conf.set(xxx); //Set each parameter.
// Initializes maxSize, which represents the maximum number of HTables referenced by each table in the pool.
int maxSize = 100;
// Initializes poolType. Valid values: Reusable, ThreadLocal, and RoundRobin. We recommend that you set this parameter to ThreadLocal.
PoolMap.PoolType poolType = PoolMap.PoolType.ThreadLocal;
OHTablePool pool = new OHTablePool(conf, maxSize, poolType);
HTableInterface hTable = pool.getTable("test"); // Get the hTable of the corresponding table.
//Execute the relevant logic.
hTable.close(); // retrun table to the pool
OBKV-HBase client configuration parameters
In addition to connection parameters, you can configure other settings via the Configuration object. For example, you can set the client's RPC timeout to 3 seconds as shown below.
conf.set("rpc.execute.timeout", "3000");
Common configuration parameters
Parameter |
Meaning |
Default Value |
|---|---|---|
| HBASE_OCEANBASE_FULL_USER_NAME | Username. For more information, see Step 2: Set client connection parameters. | null |
| HBASE_OCEANBASE_PASSWORD | User password | null |
| HBASE_OCEANBASE_PARAM_URL | URL for obtaining the RSlist from the OBConfig server | null |
| HBASE_OCEANBASE_SYS_USER_NAME | Username in the sys tenant | null |
| HBASE_OCEANBASE_SYS_PASSWORD | Password of the user in the sys tenant | null |
| HBASE_OCEANBASE_ODP_MODE | Whether to use cloud mode | False |
| HBASE_OCEANBASE_ODP_ADDR | ODP address. For more information, see Step 2: Set client connection parameters. | null |
| HBASE_OCEANBASE_ODP_PORT | ODP Port. For more information, see Step 2: Set client connection parameters. | null |
| HBASE_OCEANBASE_DATABASE | The name of the database used in the cloud. | null |
rpc.connect.timeout |
The timeout period for establishing an RPC connection, in milliseconds. | 1000ms |
rpc.execute.timeout |
The timeout period for the socket that executes RPC requests, in milliseconds. | 3000ms |
rpc.operation.timeout |
The timeout period for internal RPC requests in OceanBase Database, in milliseconds. It is recommended to set this parameter to the same value as rpc.execute.timeout. |
10000ms |
metadata.refresh.interval |
The time interval for refreshing METADATA, in milliseconds. | 60000ms |
runtime.continuous.failure.ceiling |
Maximum number of consecutive operation failures before table metadata is refreshed | 100 |
bolt.netty.buffer.low.watermark |
Low watermark of the Netty write buffer | 512*1024(512K) |
bolt.netty.buffer.high.watermark |
High watermark of the Netty write buffer | 1024*1024(1M) |
runtime.retry.interval |
Retry interval after an operation fails | 1 |
runtime.retry.times |
Number of retries after an operation fails | 1 |
OHTable configuration
Besides using the Configuration object, you can also set configuration parameters for an individual OHTable through its interface:
API |
Meaning |
Default Value |
|---|---|---|
setAutoFlush() |
Set auto-flush | True |
setWriteBufferSize() |
Set the write buffer size | 2097152 bytes |
Supported HBase operations
After initializing the client as described above, you can start performing operations. This chapter introduces some of the OHTable interface operations. For more information about the interfaces, refer to: OHTable.java.
For a demo on using OBKV-HBase, refer to: OBKV-HBase Usage Demo.
What to do next
- After deploying the OBKV-HBase client and establishing a connection with the cluster, you can perform data operations. For specific examples of data operations, see Data Operation Examples.