OBKV-Table 写入数据 - OceanBase 数据库 V4.3.5

OBKV-Table 写入数据

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

本文档介绍了 OBKV-Table 的写入能力。OBKV-Table Java 客户端支持单行数据写入和批量数据写入。业务可以根据需求选择对应的接口进行数据写入。

支持写入的接口

ObTableClient 有写入能力的接口如下：

接口	说明	注意事项
`insert(String tableName)`	写入一行数据	当主键冲突时，会写入失败
`insertOrUpdate(String tableName)`	写入或更新一行数据
`replace(String tableName)`	替换一行数据	当旧行不存在时，将写入新行
`put(String tableName)`	覆盖写一行数据	必须写入每一列表中无索引表中无 lob 类型租户的 `binlog_row_image` 值必须为 `minimal`

写入示例

准备条件

写入前需要做如下准备：

你的 ObTableClient 已经初始化完成。

在你的数据库中已经创建了关系表，为方便说明，后续示例以下面的关系表进行说明：

CREATE TABLE IF NOT EXISTS `employees` (
`employeeId` int NOT NULL, 
`name` varchar(100) NOT NULL,
`department` varchar(50),
`position` varchar(50),
`workYear` int,
`comment` varchar(100),
PRIMARY KEY (`employeeId`)
) PARTITION BY KEY(`employeeId`) PARTITIONS 97;

其他说明如下：

已支持 JSON 类型，具体说明及写入示例请参见 OBKV-Table 数据类型。

单行写入

下面的示例代码演示了如何使用 ObTableClient 写入单行数据。

insert

示例代码写入了一行数据，主键 employeeId 为 1001，写入了 4 个属性列。

private static void insertRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey = row().add(colVal("employeeId", 1001));
    Row properties = row().add(colVal("name", "zhangsan"))
        .add(colVal("department", "R&D"))
        .add(colVal("position", "dev"))
        .add(colVal("workYear", 10));
    obkvHandle.insert("employees")
        .setRowKey(rowKey)
        .addMutateRow(properties)
        .execute();
}

insertOrUpdate

示例代码演示了如何使用 ObTableClient 写入或更新一行数据，主键 employeeId 为 1001，写入了 4 个属性列。

private static void insertOrUpdateRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey = row().add(colVal("employeeId", 1001));
    Row properties = row().add(colVal("name", "zhangsan"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 10));
    obkvHandle.insertOrUpdate("employees")
            .setRowKey(rowKey)
            .addMutateRow(properties)
            .execute();
}

replace

示例代码演示了如何使用 ObTableClient 替换一行数据，主键 employeeId 为 1001，写入了 4 个属性列。

private static void replaceRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey = row().add(colVal("employeeId", 1001));
    Row properties = row().add(colVal("name", "zhangsan"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 10));
    obkvHandle.replace("employees")
            .setRowKey(rowKey)
            .addMutateRow(properties)
            .execute();
}

put

示例代码演示了如何使用 ObTableClient 覆盖写一行数据，主键 employeeId 为 1001，写入了 4 个属性列。

private static void putRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey = row().add(colVal("employeeId", 1001));
    Row properties = row().add(colVal("name", "zhangsan"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 1))
            .add(colVal("comment", "new employee"));
    obkvHandle.put("employees")
            .setRowKey(rowKey)
            .addMutateRow(properties)
            .execute();
}

批量写入

下面的示例代码演示了如何使用 ObTableClient 批量写入数据.

batchInsert

示例代码在一批里写入了 2 行数据，主键 employeeId 分别为 1001 和 1002，每一行都写入了 4 个属性列。

private static void batchInsertRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey1 = row().add(colVal("employeeId", 1001));
    Row rowKey2 = row().add(colVal("employeeId", 1002));
    Row properties1 = row().add(colVal("name", "zhangsan"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 10));
    Row properties2 = row().add(colVal("name", "lisi"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 5));
    Insert insertOp1 = insert().setRowKey(rowKey1).addMutateRow(properties1);
    Insert insertOp2 = insert().setRowKey(rowKey2).addMutateRow(properties2);
    BatchOperationResult res = obkvHandle.batchOperation("employees")
            .addOperation(insertOp1,insertOp2)
            .execute();
    System.out.println(res.hasError());
}

batchInsertOrUpdate

示例代码在一批里写入了 2 行数据，主键 employeeId 分别为 1001 和 1002，每一行都写入了 4 个属性列。

private static void batchInsertOrUpdateRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey1 = row().add(colVal("employeeId", 1001));
    Row rowKey2 = row().add(colVal("employeeId", 1002));
    Row properties1 = row().add(colVal("name", "zhangsan"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 10));
    Row properties2 = row().add(colVal("name", "lisi"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 5));
    InsertOrUpdate insertUpOp1 = insertOrUpdate().setRowKey(rowKey1).addMutateRow(properties1);
    InsertOrUpdate insertUpOp2 = insertOrUpdate().setRowKey(rowKey2).addMutateRow(properties2);
    BatchOperationResult res = obkvHandle.batchOperation("employees")
            .addOperation(insertUpOp1,insertUpOp2)
            .execute();
    System.out.println(res.hasError());
}

batchReplace

示例代码在一批里写入了 2 行数据，主键 employeeId 分别为 1001 和 1002，每一行都写入了 4 个属性列。

private static void batchReplaceRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey1 = row().add(colVal("employeeId", 1001));
    Row rowKey2 = row().add(colVal("employeeId", 1002));
    Row properties1 = row().add(colVal("name", "zhangsan"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 10));
    Row properties2 = row().add(colVal("name", "lisi"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 5));
    Replace replaceOp1 = replace().setRowKey(rowKey1).addMutateRow(properties1);
    Replace replaceOp2 = replace().setRowKey(rowKey2).addMutateRow(properties2);
    BatchOperationResult res = obkvHandle.batchOperation("employees")
            .addOperation(replaceOp1,replaceOp2)
            .execute();
    System.out.println(res.hasError());
}

batchPut

示例代码在一批里写入了 2 行数据，主键 employeeId 分别为 1001 和 1002，每一行都写入了表中全部的 5 个属性列。

private static void batchPutRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey1 = row().add(colVal("employeeId", 1001));
    Row rowKey2 = row().add(colVal("employeeId", 1002));
    Row properties1 = row().add(colVal("name", "zhangsan"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 1))
            .add(colVal("comment", "new employee"));
    Row properties2 = row().add(colVal("name", "lisi"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 1))
            .add(colVal("comment", "new employee"));
    Put putOp1 = put().setRowKey(rowKey1).addMutateRow(properties1);
    Put putOp2 = put().setRowKey(rowKey2).addMutateRow(properties2);
    BatchOperationResult res = obkvHandle.batchOperation("employees")
            .addOperation(putOp1,putOp2)
            .execute();
    System.out.println(res.hasError());
}