---
title: OBKV 介绍-OceanBase数据库使用指南
description: 了解OceanBase数据库在实际应用中关于OBKV 介绍相关的常见问题和使用技巧，帮助您快速解决OBKV 介绍的难题。
---
切换语言

- 简体中文
- English

划线反馈

# OBKV 介绍

更新时间：2026-05-29 08:46

适用版本： V2.1.x、V2.2.x、V3.1.x、V3.2.x 内容类型：TechNote  

OBKV 是 OceanBase 数据库提供的通过 API 接口访问 Table 模型/Hbase 模型的能力，OBKV 为用户提供更加简单高效的 API 访问接口，并且能在单一数据库下提供多种数据模型，满足用户不同场景下数据的多样性需求。

## 适用版本

OceanBase 数据库 V2.x 和 V3.x 版本。

## OBKV 基本介绍

OBKV 适用于表模型，KV 模式，宽表模型（Hbase），同时可以在此之上接入多种兼容性服务，同时提供多种 NoSQL 模型（如时序 CeresDB），适用于读写简单，没有复杂的 SQL 需求（连接，聚合等），但是读写量大，数据规模大，OBKV 直接和存储层进行交互，RT 更低，吞吐量更大。

![obkv](https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/doc/img/knowledge-base/database/drivers/imgX4U0zu7r7L.png)

### 表模型

表模型下，数据是强 Schema 的，就像 SQL 表一样。用户通过 SQL 的 DDL 语句创建表（支持 OceanBase 数据库所有分区表类型），表需要包含一个主键（primary key）和若干强类型的列，还可以定义二级索引和唯一性约束。OceanBase TableAPI 提供的表模型 API 可以和 OceanBase SQL 无缝集成，甚至共同使用。除了 Query 接口外，表模型的其他 API 都是通过主键对行数据进行读写的。

表模型的 API 我们称之为 TableAPI。

### 二级索引

表上可以创建索引，所有 TableAPI 的操作都会同步更新索引。使用 Query 接口，可以使用二级索引进行查询扫描。这对于普通 KV 模型下只有主键一个维度进行查询，在很多时候对于业务需求来说这是不够的。为此，在支持主键查询的简单KV模型下，应用不得不在业务层自己维护一个“索引表”。这样做不仅增加了业务数据层的复杂度，而且索引和主表的一致性往往难以保证，而且读写索引表需要应用和数据库之间多次交互响应延时很大。OceanBase TableAPI 在服务端原生支持二级索引，克服了上述所有问题。 ​

### 与 SQL 比较

OceanBase TableAPI 提供的表模型 API 可以和 OceanBase SQL 无缝集成，甚至共同使用。

- TableAPI 比基于 SQL 的存储设计，数据访问路径短，相同功能时性能更优；因为语义简单，更容易优化，性能预期更可控（Predictable）。
 - Batch 操作的语义比 SQL 更灵活高效。例如，multi-get 的不同行可以选取不同的列。
 - API 接口使用简单，直接提供 entity 语义，不需要复杂的 ER 映射。
 - 提供异步 API 接口，极大提升应用端的线程资源利用率（暂未实现）。
 - 使用简单的 RPC 协议，没有传统 JDBC/ODBC 接口的“重”连接，几乎不受连接数的限制（目前受 RPC 框架的限制）。

但是 TableAPI 的查询（Query）功能无法和 SQL 同日而语，提供 get、scan、limit 等有限功能。如果你需要聚合，排序，应该使用 SQL。TableAPI 也不提供交互式的事务等复杂事务功能。不同于传统关系数据库，OceanBase 数据库本身作为一个 SQL 功能齐全的 NewSQL 数据库，高扩展性和高可用性并不是选择使用 TableAPI 的考量因素。

## OBKV 的产品体系

所有的客户端都是在 Github 开源的，用户可以选择源码编译打包来使用客户端，也可以通过从中央仓库拉取最新的客户端。

### 服务端

当前除了 V4.0 版本 OBServer 不支持 OBKV 的功能外，V3.x 和 V4.1 的商业版/开源版都支持 OBKV 的功能。

### TableAPI 客户端

TableAPI 提供表模型的访问接口，当前 TableAPI 实现了多种语言版本的客户端，包括 JAVA/Rust/GO。

TableAPI 当前提供的接口主要有三类，包括：

- 单行操作接口：对单行数据进行读写
 - 批量操作接口：同时对多行进行操作，支持单行操作的所有类型
 - 查询接口：指定过滤条件对表中数据进行查询，类似 SQL 的 select-from-where

#### JAVA 客户端

- [Github 仓库地址](https://github.com/oceanbase/obkv-table-client-java)
 - [ReleaseNote](https://github.com/oceanbase/obkv-table-client-java/wiki)
 - [客户端说明文档](https://github.com/oceanbase/obkv-table-client-java/wiki/OBKV-Java客户端-说明文档)

在 `pom.xml` 中添加依赖引入 TableAPI JAVA 客户端。

```
<dependency>
    <groupId>com.oceanbase</groupId>
    <artifactId>obkv-table-client</artifactId>
    <version>1.1.1</version>
</dependency>

```

当前版本服务端版本支持：

- OceanBase 数据库 V4.1 以及以后：需要使用 1.1.0 及以后的版本
 - OceanBase 数据库 V3.x：需要使用 1.0.0 以及以后的版本

公有云 TableAPI 版本支持：需要使用 V1.1.0 及以后的版本

#### Rust 客户端

[Github 仓库地址](https://github.com/oceanbase/obkv-table-client-rs)

在 `cargo.toml` 中添加 rust 客户端依赖。

```
[dependencies]
obkv-table-client-rs = "0.1.0"

```

#### Go 客户端

[Github 仓库地址](https://github.com/oceanbase/obkv-table-client-go)

### HbaseAPI

HbaseAPI 提供宽表模型的访问接口，目前兼容 Hbase 094 版本的所有接口。

#### JAVA 客户端

[Github 仓库地址](https://github.com/oceanbase/obkv-hbase-client-java)

[ReleaseNote](https://github.com/oceanbase/obkv-hbase-client-java/wiki)

在 `pom.xml` 中添加依赖引入 HbaseAPI JAVA客户端。

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

```

- OceanBase 数据库 V4.1 以及以后：需要使用 V0.1.1 及以后的版本
 - OceanBase 数据库 V3.x: 需要使用 V0.1.0 及以后的版本 ​ 公有云 HbaseAPI 版本支持：需要使用 V0.1.1 及以后的版本

Previous

[如何判定参数类型不一致导致硬解析，生成新的计划](https://www.oceanbase.com/knowledge-base/oceanbase-database-1000000002342231)

Next

[执行报错 ERROR 4152 (42000): Null value，get obj error(ret=-4152)](https://www.oceanbase.com/knowledge-base/oceanbase-database-1000000001406987) ![有帮助](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) 咨询热线