--- title: "使用 OBKV-HBase 客户端连接集群 - OceanBase 数据库 V4.3.5 | OceanBase 文档中心" description: 使用 OBKV-HBase 客户端连接集群 OBKV-HBase 支持通过 OBKV-HBase 客户端连接 OBKV-HBase 集群使用 HBase 兼容的 API 进行数据处理。若您当前有业务使用了原生 HBase 数据操作逻辑，您可以通过部署 OceanBase 数据库集群，在 OBServer 服务端创建 … --- 切换语言 - 中文站 - 简体中文 - International - English - 日本站 - 日本語 文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库KV 型 - V 4.3.5 LTS # 使用 OBKV-HBase 客户端连接集群 更新时间：2026-04-15 16:01:32 [编辑](https://github.com/oceanbase/oceanbase-kv/edit/V4.3.5/zh-CN/200.obkv-hbase/200.obkv-hbase-develop/200.connecting-by-using-obkv-hbase-client.md) OBKV-HBase 支持通过 OBKV-HBase 客户端连接 OBKV-HBase 集群使用 HBase 兼容的 API 进行数据处理。若您当前有业务使用了原生 HBase 数据操作逻辑，您可以通过部署 OceanBase 数据库集群，在 OBServer 服务端创建 HBase Table，并通过 OBKV-HBase 客户端进行数据操作。本文介绍如何配置客户端、连接 OBServer、以及进行基本的增删改查操作。 ## OBKV-HBase Java 客户端 #### 注意 OBKV-HBase 仅支持 Java 客户端。 OBKV-HBase 客户端基于 OBKV-Table 提供的基本接口，在客户端封装了 HBase 兼容的 API，目前已兼容 HBase 1.x/2.x 版本的特性。 ## 准备工作 使用 OBKV-HBase 客户端连接 OBKV-HBase 集群进行数据处理之前，请确保您已经完成如下准备工作： - 已经部署了 OceanBase 集群。关于支持的部署方案、部署方式以及详细的部署操作，参见 [部署简介](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002022351)。 - 已经创建了 MySQL 租户。关于创建租户的详细操作，参见 [创建租户](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000001573963)。 - 已经创建了数据库。关于创建数据库的详细操作，参见 [创建数据库](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000001576014)。 - 已经创建了 OBKV-HBase 数据表。关于创建 OBKV-HBase 数据表的详细操作，参见 [数据库模式设计](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002022352)。 建表示例： ``` -- 首先创建一个表组 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](https://github.com/oceanbase/obkv-hbase-client-java/tree/main/example/simple-hbase-demo)）。OBKV-HBase 客户端兼容相关说明请见 [OBKV-HBase 客户端兼容](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002022334)。 ```Java com.oceanbase obkv-hbase-client 0.1.4 ``` #### 注意 - 尽量使用最新版本 jar 包，旧版本的 jar 包可能不支持新的服务端。 - 这里的版本号可能不是最新的，参考[中央仓库](https://mvnrepository.com/artifact/com.oceanbase/obkv-hbase-client)的已发布 OBKV-HBase 版本，将版本号替换为已发布的最新版本号。 ## 步骤二：设置客户端连接参数 OBKV-HBase 在公有云以及私有化部署方式各有不同，需要设置的客户端连接参数也不一样。如果你是私有化部署 OceanBase 集群，请参考直连模式配置，如果你是使用公有云 OBKV 服务，请参考云上模式。 同时所有的配置项可以通过两种方式进行设置： - 通过 HBaseConfiguration/Configuration 的 set 方法在代码中 Connection 初始化之前进行设置。 - 在 OBKV-HBase 客户端配置文件中设置 - 如果你使用的是 org.apache.hadoop.hbase.HBaseConfiguration 对连接进行初始化，则在 `hbase-site.xml` 文件中设置。 - 如果你使用的是 org.apache.hadoop.conf.Configuration 对连接进行初始化，则在 `core-site.xml` 文件中进行设置。� ### 直连模式配置 (私有化部署) #### 通过 Configuration 设置 ``` ## 假设当前集群如下 ## 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"); ``` #### 通过配置文件设置 ```xml hbase.oceanbase.fullUserName root@obkv#obkvcluster hbase.oceanbase.password hbase.oceanbase.paramURL your config url hbase.oceanbase.sysUserName sysroot hbase.oceanbase.sysPassword ``` #### 注意 paramURL 会包含 xml 特殊字符 `&`,需要将其转换成 `&`,否则会解析失败。 #### 获取 Config URL 可以参考以下方式获取 Config URL： - 从 OCP 获取 Config URL 如果使用了 OCP，可以从 OCP 中获取 Config URL。 1. 登录 OceanBase 云平台。 2. 在左侧导航栏选择 **集群**，下滑找到 **集群列表**。 3. 单击打开需要访问的集群名称。 4. 在集群详细信息页找到 **ConfigURL** 参数，该参数在客户端初始化中需要配置。 ![ConfigURL](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/observer/kv/obkv-hbase-client.png) - 使用 obd 部署 Config Server 并获取 Config URL 如果没有使用 OCP，需要 [使用命令行部署 Config Server](https://www.oceanbase.com/docs/community-obd-cn-1000000000774262）， 并获取 ObRootServiceInfoUrl。 ### 云上模式配置（公有云） #### 通过 Configuration 设置 ``` ## 假设当前集群如下 ## 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"); ``` #### 通过配置文件设置 在 OBKV-HBase 客户端配置文件中设置对应的参数。 ```xml hbase.oceanbase.fullUserName root hbase.oceanbase.password hbase.oceanbase.odpAddr hbase.oceanbase.odpPort 3307 hbase.oceanbase.odpMode true hbase.oceanbase.database test ``` #### 获取 ODP Address 可以通过以下方式获取 ODP Address。进入 OB Cloud 租户工作台，并查看部署关系图。 ![odp](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/observer/kv/cloud.png) ## 连接 OceanBase 集群 设置完客户端连接参数之后，我们开始初始化客户端，当前支持通过 ConnectionFactory/OHTableClient/OHTablePool 三种方式，三者的区别如下： - ConnectionFactory（推荐使用）：原生 HBase 客户端创建连接的方式，通过 ConnectionFactory 可以创建 Hbase Connection，进而对不同的 Hbase 进行操作，Connection 本身是线程安全的。通过配置文件方式初始化客户端。这种方式 HBase 业务可以做到不改代码进行迁移。 - OHTableClient：非线程安全的, 内部只有一个 OHTable 句柄，多线程同时访问同一个 OHTable 会导致不可预估的问题（单线程场景使用）。 - OHTablePool：OHTable 池，需要的时候从池中获取对应表的 OHTable 实例使用（多线程场景使用）。 ### 通过 ConnectionFactory 连接 1. 修改 HBase Connection 类型 首先我们需要修改 Connection 类型为 OBKV-HBase 的 Connection 类型，我们可以通过如下两种方式进行修改： - 修改配置文件 在配置文件中修改 HBase Connection 类型为 OBKV-Hbase 的 Connection 类型： ```xml hbase.connection.impl com.alipay.oceanbase.hbase.util.OHConnectionImpl ``` - 直接设置 Configuration 修改 HBase 业务代码中的 Configuration，添加 `HBASE_CLIENT_CONNECTION_IMPL` 配置： ```java import org.apache.hadoop.hbase.client; conf.set(ClusterConnection.HBASE_CLIENT_CONNECTION_IMPL, "com.alipay.oceanbase.hbase.util.OHConnectionImpl"); ``` 2. 创建 HBase 连接 ```java // 设置 configuration，这里也可以通过配置文件设置，参考上一节，这里不展开 Configuration conf = new Configuration(); // 创建配置项 conf.set(xxx); //设置各个配置项 Connection connection = ConnectionFactory.createConnection(c); TableName tableName = TableName.valueOf("your hbase table"); Table hTable = connection.getTable(tableName); //执行相关逻辑 hTable.close(); //关闭 htable 对象 connection.close(); //关闭 connection 对象 ``` ### 通过 OHTable 连接 ```java // 设置 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。 ```java // 设置 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。 ```java 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](https://github.com/oceanbase/obkv-hbase-client-java/blob/main/src/main/java/com/alipay/oceanbase/hbase/OHTable.java)。 相关 OBKV-HBase 使用的 Demo 请参考：[OBKV-HBase 使用 Demo](https://github.com/oceanbase/obkv-hbase-client-java/tree/main/example/simple-hbase-demo)。 ## 后续操作 部署 OBKV-HBase 客户端并建立和集群的连接之后，就可以对数据进行相应的操作了，有关数据操作的具体示例，参见 [数据操作示例](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002022353)。 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线