OBKV-Table 操作类型 - OceanBase 数据库 V4.3.5

OBKV-Table 操作类型

更新时间：2026-04-15 16:01:32

OBKV-Table 支持单操作、批操作、查询操作类型。

单操作

单操作的一个接口最多操作一条记录，单操作一定需要设置 Rowkey。

基础单操作

操作	描述
insert	insert 提供单行数据插入的语义，必须指定主键列： 1. 如果该行不存在，插入该行； 2. 如果存在，则插入失败
put	put 提供覆盖写的语义，必须指定主键列： 1. 如果该行不存在，插入该行； 2. 如果存在，覆盖已有行。
get	get 提供单行数据取回的语义，必须指定主键列：如果查询列（Select Column）没有指定，默认查询所有列。
update	update 提供单行数据更新的语义，必须指定主键列。同时可以做条件更新，对非主键列指定条件，满足条件才做更新操作。
delete	delete 提供单行数据删除的语义，必须指定主键列，同时可以做条件删除，对非主键列指定条件，满足条件才删除该行。

复合单操作

操作	功能
insertOrUpdate	insertOrUpdate 提供插入或者更新的语义： 1. 必须指定主键列，如果该行不存在，插入该行； 2. 如果存在，更新已有行。
increment	increment 提供对整型列增加一个增加值的语义，必须指定主键列，以及需要增加值的列。increment 也支持提供条件，如果指定条件，只有该行满足条件时，才会做 increment 操作： 1. 如果指定的行不存在，插入该行，并将做 increment 的列的初始化设置为增量值； 2. 如果该行存在并且需要做 increment 的列的当前值为 NULL，将该列的值更新为增量值。
append	append 提供对字符类型列追加某个字符串，必须指定主键列，以及需要追加字符串的列。append 也支持提供条件，如果指定条件，只有该行满足条件时，才会做 append 操作： 1. 如果指定的行不存在，插入该行，并将做 append 的列的初始化设置为追加串； 2. 如果该行存在并且需要做 append 的列的当前值为 NULL，将该列的值更新为追加串。
checkAndInsertup	checkAndInsertup 提供条件更新的语义： 1. 在 checkExist 参数为 `true` 的时候，如果有符合条件的行存在，则执行给定的 InsertUp 操作，否则什么都不做； 2. 在 checkExist 参数为 false 的时候，如果没有符合条件的行存在，则执行给定的 InsertUp 操作，否则什么都不做。 3. 在 rollbackWhenCheckFailed 参数为 `true` 的时候，如果 check 失败，则会抛出异常 ObTableException，异常的 message 为 `[-10518][OB_KV_CHECK_FAILED][Check failed in checkAndInsUp]`。

批操作

OBKV-Table 支持上述基础单操作以及复合单操作的批量：

支持一个 Batch 中都是一种操作，比如批量插入。
支持一个 Batch 中混合上述所列的不同单操作。

查询

在 OBKV-Table 中，查询和单操作在语义上的区别是查询可以访问若干条数据，单操作最多只能访问一条数据。一个典型的查询主要包含如下几部分：

Select ：业务场景实际需要的列。建议按需选择，不要返回过多无用的列，否则会对 CPU/内存/网络资源都有一定的消耗。
ScanRange：查询的范围。
Index ：显示指定需要使用的索引。
Filter：查询的过滤条件。
Limit：查询需要返回的数据条数。

索引

OBKV-Table 支持局部索引，以及全局索引。

索引和查询

索引只能在查询中使用。
基于索引的行查询，可以访问主表所有的列。但是如果查询的列在索引中没有，需要额外访问主表，会有比较大的开销。在设计索引的时候，需要充分考虑业务实际的查询场景。
在使用索引的时候需要显式指定。

局部索引和全局索引

局部索引和全局索引主要的区别如下：

分区键是否和主表保持一致：如果保持一致，即为局部索引，如果不一致，则为全局索引。
维护索引代价不同：写一条数据的时候，局部索引由于分区键相同，待写入的主表行和索引行在一个节点上，所以是个单机事务。全局索引的主表行和索引行，在分布式架构中大概率不在一个节点上，因此可能是分布式事务，开销更大。

需要注意的是：

不建议使用全局索引。因为全局索引在服务端会产生分布式事务，对时延以及吞吐都有比较大的影响。
规划局部索引时，维护索引的开销也需要重点考虑。比如有了索引后，需要同时维护主表和索引表，对存储的写入量会变大，对时延和吞吐会有影响，对存储的占用也有影响。

Filter

逻辑运算符

OBKV-Table 支持的逻辑运算符如下：

运算符	描述	可选值
AND	逻辑与，两个 Filter 需要同时满足。	operator.AND
OR	逻辑或，两个 Filter 只需要满足一个即可。	operator.OR

比较运算符

OBKV-Table 支持的比较运算符如下：

运算符	描述	支持的类型
>	大于	参考 OBKV-Table 支持的数据类型
>=	大于等于
<	小于
<=	小于等于
!=	不等于
=	等于
IS NULL	为空	仅支持 NULL 类型
IS NOT NULL	不为空	仅支持 NULL 类型

聚合

OBKV-Table 支持的聚合函数如下：

函数	描述	参数类型	结果类型
COUNT	计数	任意类型	BIGINT
SUM	求和	整数类型/浮点数类型	BIGINT/DOUBLE
MAX	最大值	可为数值、字符、日期型或其它可比较类型的数据列	与参数类型一致
MIN	最小值	可为数值、字符、日期型或其它可比较类型的数据列	与参数类型一致
AVG	平均值	整数类型/浮点数类型	BIGINT/DOUBLE

注意

OBKV-Table 聚合操作是基于过滤函数的特殊查询，会基于聚合函数的语义返回特定结果，而非大量原始数据。
OBKV-Table 聚合操作会扫描大量数据，消耗大量 I/O 资源，请谨慎使用。