使用 OBKV-HBase Java 客户端连接集群

更新时间：2025-12-03 10:41:34

OBKV-HBase 支持通过 OBKV-HBase 客户端连接 OBKV-HBase 集群使用 HBase 兼容的 API 进行数据处理。若您当前有业务使用了原生 HBase 数据操作逻辑，您可以通过部署 OceanBase 数据库集群，在 OBServer 服务端创建 HBase Table，并通过 OBKV-HBase 客户端进行数据操作。本文介绍如何配置客户端、连接 OBServer、以及进行基本的增删改查操作。

OBKV-HBase Java 客户端

注意

OBKV-HBase 仅支持 Java 客户端。

OBKV-HBase Java 客户端基于 OBKV-Table 提供的基本接口，在客户端封装了 HBase 兼容的 API，目前已兼容 HBase 0.94 版本的特性。

准备工作

使用 OBKV-HBase 客户端连接 OBKV-HBase 集群进行数据处理之前，请确保您已经完成如下准备工作：

已经部署了 OceanBase 集群。关于支持的部署方案、部署方式以及详细的部署操作，参见部署简介。
已经创建了 MySQL 租户。关于创建租户的详细操作，参见创建租户。
已经创建了数据库。关于创建数据库的详细操作，参见创建数据库。
已经创建了 OBKV-HBase 数据表。关于创建 OBKV-HBase 数据表的详细操作，参见数据库模式设计。

建表示例：

-- 首先创建一个表组 htable1
CREATE TABLEGROUP htable1;

-- 创建和 htable1 表组绑定的测试表 htable1$family1
 CREATE TABLE htable1$family1 (
       K varbinary(1024),
       Q varbinary(256),
       T bigint,
       V varbinary(1048576) NOT NULL,
       PRIMARY KEY(K, Q, T)) 
       TABLEGROUP =  htable1;

步骤一：添加客户端依赖

添加 OBKV-HBase 客户端 jar 包依赖到本地 java 工程的 pom.xml 文件（或参考 OBKV-HBase 使用 Demo）。

<dependency>
    <groupId>com.oceanbase</groupId>
    <artifactId>obkv-hbase-client</artifactId>
    <version>0.1.4</version>
</dependency>

注意

尽量使用最新版本 jar 包，旧版本的 jar 包可能不支持新的服务端。
这里的版本号可能不是最新的，参考中央仓库的已发布 OBKV-HBase 版本，将版本号替换为已发布的最新版本号。

步骤二：设置客户端连接参数

OBKV-HBase 在公有云以及私有化部署方式各有不同，需要设置的客户端连接参数也不一样。如果你是私有化部署 OceanBase 集群，请参考直连模式配置，如果你是使用公有云 OBKV 服务，请参考云上模式。

直连模式配置 (私有化部署)

## 假设当前集群如下
## ClusterName：obkvcluster
## TenantName：obkv
## DataBaseName: test
## UserName：root
## SYS_USER_NAME : sysroot

#### 必选项
Configuration conf = new Configuration();

## 格式为userName@tenantName#clusterName 
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root@obkv#obkvcluster");

## fullUserName中userName访问OceanBase的密码
conf.set(HBASE_OCEANBASE_PASSWORD, "");

## 从obconfig server获取RSlist的url，详见Config URL获取相关内容
conf.set(HBASE_OCEANBASE_PARAM_URL, "");

## 系统租户下的用户名, 只有系统租户下的用户才有权限访问路由表
conf.set(HBASE_OCEANBASE_SYS_USER_NAME, "sysroot");

## 系统租户下的用户密码
conf.set(HBASE_OCEANBASE_SYS_PASSWORD, "");         

#### 可选项
## 执行请求的超时时间(基于业务特点选)，单位是ms，如下表示超时时间1s
conf.set("rpc.execute.timeout", "1000");

可以参考以下方式获取 Config URL。

从 OCP 获取 Config URL

如果使用了 OCP，可以从 OCP 中获取 Config URL。
1. 登录 OceanBase 云平台。
2. 在左侧导航栏选择集群，下滑找到 集群列表。
3. 单击打开需要访问的集群名称。
4. 在集群详细信息页找到 ConfigURL 参数，该参数在客户端初始化中需要配置。
使用 OBD 部署 Config Server 并获取 Config URL

如果没有使用 OCP，需要使用命令行部署 Config Server，并获取 ObRootServiceInfoUrl。

云上模式配置（公有云）

## 假设当前集群如下
## DataBaseName: test
## UserName：root

#### 必选项
Configuration conf = new Configuration();

## 数据库新建的用户名，不用三段式，username
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root");    

## 用户Password
conf.set(HBASE_OCEANBASE_PASSWORD, "");       

## 详见ODP Address备注
conf.set(HBASE_OCEANBASE_ODP_ADDR, "");        

## OBKV的端口是3307（固定）
conf.setInt(HBASE_OCEANBASE_ODP_PORT, "3307");     

## 云上使用ODP模式(固定)
conf.setBoolean(HBASE_OCEANBASE_ODP_MODE, true);  

## 数据库的database的名字
conf.set(HBASE_OCEANBASE_DATABASE, "test");              

#### 可选项
## 执行请求的超时时间(基于自己业务特征配置)
conf.set("rpc.execute.timeout", "1000");

可以通过以下方式获取 ODP Address。进入 OB Cloud 租户工作台，并查看部署关系图。

odp

连接 OceanBase 集群

设置完客户端连接参数之后，我们开始初始化客户端，当前支持 OHTableClient 和 OHTablePool 两种方式，二者的区别如下：

OHTableClient：非线程安全的, 内部只有一个 OHTable 句柄，多线程同时访问同一个 OHTable 会导致不可预估的问题（单线程场景使用）。
OHTablePool：OHTable 池，需要的时候从池中获取对应表的 OHTable 实例使用（多线程场景使用）。

通过 OHTable 连接

// 设置 configuration，参考上一节，这里不展开
Configuration conf = new Configuration(); // 创建配置项
conf.set(xxx); //设置各个配置项
OHTableClient hTable = new OHTableClient("test1", conf); // 创建 htable对象
hTable.init(); // 初始化hTable
//执行相关逻辑
hTable.close(); //关闭htable对象

通过 OHTablePool 连接

OBKV-HBase 提供 Table pool 池化模式管理多个 Table 的操作实例，目前资源池包含有 Reusable、RoundRobin 和 ThreadLocal 三种方式。可以在实例化 table pool 时指定使用某种模式。

用法同 HBase 的 HTablePool，当需要某个 Table 的 HTable 时使用 pool.getTable("xx") 获取对应的 HTable, 需要注意的是:

参数使用优先级: Table 专用参数 (如 pool.setOdpAddr() 等) > Conf 设置的参数 > 默认参数。
使用完 HTable 后记得 close(), 将 OHTable 返还给 Pool, 推荐可以使用 try/finally 的方式返回 HTable。

// 设置 configuration，参考上一节，这里不展开
Configuration conf = new Configuration(); // 创建配置项
conf.set(xxx);  //设置各个配置项

// 初始化 maxSize，用来表示 pool 中每张表的最大 htable 引用数
int maxSize = 100;
// 初始化 poolType，有 Reusable / ThreadLocal / RoundRobin 三种，推荐使用 ThreadLocal
PoolMap.PoolType poolType = PoolMap.PoolType.ThreadLocal;
OHTablePool pool = new OHTablePool(conf, maxSize, poolType);
HTableInterface hTable = pool.getTable("test"); // 获取对应表的hTable
//执行相关逻辑
hTable.close(); // retrun table to the pool

OBKV-HBase 客户端配置项

除了连接参数，我们可以通过 Configuration 设置一些其他的配置项，如下例中设置客户端的 RPC 超时时间为 3s。

conf.set("rpc.execute.timeout", "3000");

常用配置项速查

配置项	含义	默认值
HBASE_OCEANBASE_FULL_USER_NAME	用户名, 根据连接模式的不同可见步骤二：设置客户端连接参数章节	空
HBASE_OCEANBASE_PASSWORD	用户 Password	空
HBASE_OCEANBASE_PARAM_URL	从 obconfig server 获取 RSlist 的 url	空
HBASE_OCEANBASE_SYS_USER_NAME	系统租户下的用户名	空
HBASE_OCEANBASE_SYS_PASSWORD	系统租户下的用户密码	空
HBASE_OCEANBASE_ODP_MODE	是否使用云上配置	False
HBASE_OCEANBASE_ODP_ADDR	ODP Address，详情见步骤二：设置客户端连接参数章节	空
HBASE_OCEANBASE_ODP_PORT	ODP Port，详情见步骤二：设置客户端连接参数章节	空
HBASE_OCEANBASE_DATABASE	云上使用，数据库的 database 的名字	空
`rpc.connect.timeout`	建立RPC连接的超时时间，单位 ms	1000ms
`rpc.execute.timeout`	执行RPC请求的socket超时时间，单位 ms	3000ms
`rpc.operation.timeout`	OceanBase 内部执行 RPC 请求的超时时间，单位 ms 建议和 rpc.execute.timeout 配置成一个值	2000ms
`metadata.refresh.interval`	刷新METADATA的时间间隔，单位 ms	60000ms
`runtime.continuous.failure.ceiling`	连续运行失败上限，会刷新 TABLE 的信息	100
`bolt.netty.buffer.low.watermark`	netty 写缓存的低水位	5*1024(512K)
`bolt.netty.buffer.high.watermark`	netty 写缓存的高水位	1024*1024(1M)
`runtime.retry.interval`	运行出错重试的时间间隔	100ms
`runtime.retry.times`	运行出错重试的次数	3

OHTable 配置

除了 Configuration，也可以通过 OHTable 的接口来设置单个 OHTable 的配置项：

接口	含义	默认值
`setAutoFlush()`	设置 auto-flush	True
`setWriteBufferSize()`	设置写缓冲区大小	2097152 Byte

支持的 HBase 操作

按照上述步骤初始化完客户端之后，便可以开始执行操作，本章介绍了部分 OHTable 接口操作，如果想了解更多的接口信息，请参考：OHTable.java。

相关 OBKV-HBase 使用的 Demo 请参考：OBKV-HBase 使用 Demo。

后续操作

部署 OBKV-HBase 客户端并建立和集群的连接之后，就可以对数据进行相应的操作了，有关数据操作的具体示例，参见数据操作示例。