Update data with OBKV-Table|OceanBase Cloud

Update data with OBKV-Table

Last Updated：2026-06-04 02:38:42 Updated

The OBKV-Table Java client supports single-row and batch data updates. Choose the API that fits your use case.

Update APIs

The following ObTableClient APIs can update data:

API	Description	Notes
`update(String tableName)`	Updates one row. You can set update conditions.
`insertOrUpdate(String tableName)`	Inserts or updates one row.
`replace(String tableName)`	Replaces one row (delete-then-insert semantics).
`put(String tableName)`	Overwrites one row.	You must update every column. The table has no indexes. The table has no LOB columns. The tenant `binlog_row_image` value must be `minimal`.
`increment(String tableName)`	Atomically adds a value to an integer column.	When the old row does not exist, a new row is updated with the specified delta value.
`append(String tableName)`	Atomically appends a string to a string column.	When the old row does not exist, a new row is inserted with the specified delta value.
`checkAndInsUp(String tableName, ObTableFilter filter, InsertOrUpdate insUp, boolean checkExists, boolean rollbackWhenCheckFailed)`	Updates when conditions are met	The check in this API has two meanings: The row does not exist (determined by the primary key, not because the filter condition is not met). The row exists but does not satisfy the filter condition. When the row exists: If the filter condition is met, an update is performed. If the filter condition is not met, no operation is performed. When the row does not exist: `checkExists = true`: no operation is performed. `checkExists = false`: an insert is performed. When the check fails: `rollbackWhenCheckFailed = false`: no error is raised. `rollbackWhenCheckFailed = true`: an `ObTableException` is thrown with message `[-10518][OB_KV_CHECK_FAILED][Check failed in CheckAndInsUp]`.

Update examples

Prerequisites

Your ObTableClient is initialized.

You have created a relational table in your database. The examples below use this table:

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;

Single-row update

update

The following example updates one row and sets workYear to 11 for the row whose primary key employeeId is 1001.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+----------+---------+
| employeeId | name     | department | position | workYear | comment |
+------------+----------+------------+----------+----------+---------+
|       1001 | zhangsan | R&D        | dev      |       10 | NULL    |
+------------+----------+------------+----------+----------+---------+
*/
private static void updateRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey = row().add(colVal("employeeId", 1001));
    Row properties = row().add(colVal("workYear", 11));
    obkvHandle.update("employees")
            .setRowKey(rowKey)
            .addMutateRow(properties)
            .execute();
}

The following example updates one row: if workYear for the row whose primary key employeeId is 1001 is greater than or equal to 3, it sets workYear to 11.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+----------+---------+
| employeeId | name     | department | position | workYear | comment |
+------------+----------+------------+----------+----------+---------+
|       1001 | zhangsan | R&D        | dev      |       10 | NULL    |
+------------+----------+------------+----------+----------+---------+
*/
private static void updateRowWithFilter(ObTableClient obkvHandle) throws Exception {
    Row rowKey = row().add(colVal("employeeId", 1001));
    Row properties = row().add(colVal("workYear", 11));
    ObTableValueFilter filter = compareVal(ObCompareOp.GE, "workYear", 3);
    obkvHandle.update("employees")
            .setRowKey(rowKey)
            .addMutateRow(properties)
            .setFilter(filter)
            .execute();
}

insertOrUpdate

The following example updates one row and sets workYear to 11 for the row whose primary key employeeId is 1001.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+----------+---------+
| employeeId | name     | department | position | workYear | comment |
+------------+----------+------------+----------+----------+---------+
|       1001 | zhangsan | R&D        | dev      |       10 | NULL    |
+------------+----------+------------+----------+----------+---------+
*/
private static void insertOrUpdateRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey = row().add(colVal("employeeId", 1001));
    Row properties = row().add(colVal("workYear", 11));
    obkvHandle.insertOrUpdate("employees")
            .setRowKey(rowKey)
            .addMutateRow(properties)
            .execute();
}

replace

The following example updates one row and sets workYear to 11 for the row whose primary key employeeId is 1001.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+----------+---------+
| employeeId | name     | department | position | workYear | comment |
+------------+----------+------------+----------+----------+---------+
|       1001 | zhangsan | R&D        | dev      |       10 | NULL    |
+------------+----------+------------+----------+----------+---------+
*/
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", 11));
    obkvHandle.replace("employees")
            .setRowKey(rowKey)
            .addMutateRow(properties)
            .execute();
}

put

The following example overwrites one row and sets workYear to 1 for the row whose primary key employeeId is 1001.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+-----------+--------------+
| employeeId | name     | department | position | workYear  | comment      |
+------------+----------+------------+----------+-----------+--------------+
|       1001 | zhangsan | R&D        | dev      |        10 | new employee |
+------------+----------+------------+----------+-----------+--------------+
*/
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();
}

increment

The following example atomically adds 1 to workYear for the row whose primary key employeeId is 1001, so the final value is 11.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+----------+---------+
| employeeId | name     | department | position | workYear | comment |
+------------+----------+------------+----------+----------+---------+
|       1001 | zhangsan | R&D        | dev      |       10 | NULL    |
+------------+----------+------------+----------+----------+---------+
*/
private static void incrementRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey = row().add(colVal("employeeId", 1001));
    Row properties = row().add(colVal("workYear", 1));
    obkvHandle.increment("employees")
            .setRowKey(rowKey)
            .addMutateRow(properties)
            .execute();
}

append

The following example appends the string dev to position for the row whose primary key employeeId is 1001, so the final value is java dev.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+----------+---------+
| employeeId | name     | department | position | workYear | comment |
+------------+----------+------------+----------+----------+---------+
|       1001 | zhangsan | R&D        | java     |       10 | NULL    |
+------------+----------+------------+----------+----------+---------+
*/
private static void appendRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey = row().add(colVal("employeeId", 1001));
    Row properties = row().add(colVal("position", "dev"));
    obkvHandle.append("employees")
            .setRowKey(rowKey)
            .addMutateRow(properties)
            .execute();
}

checkAndInsUp

The following example checks whether workYear for the row whose primary key employeeId is 1001 is greater than or equal to 3. If so, it runs insertUpOp and updates comment to good.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+----------+---------+
| employeeId | name     | department | position | workYear | comment |
+------------+----------+------------+----------+----------+---------+
|       1001 | zhangsan | R&D        | dev      |       10 | NULL    |
+------------+----------+------------+----------+----------+---------+
*/
private static void checkAndInsUpRow(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))
            .add(colVal("comment", "good"));
    InsertOrUpdate insertUpOp = insertOrUpdate().setRowKey(rowKey).addMutateRow(properties);
    ObTableValueFilter filter = compareVal(ObCompareOp.GE, "workYear", 3);
    MutationResult result = obkvHandle.checkAndInsUp("employees", filter, insertUpOp, true)
            .execute();
    System.out.println(result.getAffectedRows());
}

Batch update

batchUpdate

The following example updates two rows in one batch and sets workYear to 11 for rows whose primary keys employeeId are 1001 and 1002.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+----------+---------+
| employeeId | name     | department | position | workYear | comment |
+------------+----------+------------+----------+----------+---------+
|       1001 | zhangsan | R&D        | dev      |       10 | NULL    |
|       1002 | lisi     | R&D        | dev      |       10 | NULL    |
+------------+----------+------------+----------+----------+---------+
*/
private static void batchUpdateRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey1 = row().add(colVal("employeeId", 1001));
    Row rowKey2 = row().add(colVal("employeeId", 1002));
    Row properties1 = row().add(colVal("workYear", 11));
    Row properties2 = row().add(colVal("workYear", 11));
    Update updateOp1 = update().setRowKey(rowKey1).addMutateRow(properties1);
    Update updateOp2 = update().setRowKey(rowKey2).addMutateRow(properties2);
    BatchOperationResult res = obkvHandle.batchOperation("employees")
            .addOperation(updateOp1,updateOp2)
            .execute();
    System.out.println(res.hasError());
}

batchInsertOrUpdate

The following example updates two rows in one batch and sets workYear to 11 for rows whose primary keys employeeId are 1001 and 1002.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+----------+---------+
| employeeId | name     | department | position | workYear | comment |
+------------+----------+------------+----------+----------+---------+
|       1001 | zhangsan | R&D        | dev      |       10 | NULL    |
|       1002 | lisi     | R&D        | dev      |       10 | NULL    |
+------------+----------+------------+----------+----------+---------+
*/
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("workYear", 11));
    Row properties2 = row().add(colVal("workYear", 11));
    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

The following example updates two rows in one batch and sets workYear to 11 for rows whose primary keys employeeId are 1001 and 1002.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+----------+---------+
| employeeId | name     | department | position | workYear | comment |
+------------+----------+------------+----------+----------+---------+
|       1001 | zhangsan | R&D        | dev      |       10 | NULL    |
|       1002 | lisi     | R&D        | dev      |       10 | NULL    |
+------------+----------+------------+----------+----------+---------+
*/
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", 11));
    Row properties2 = row().add(colVal("name", "lisi"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 11));
    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

The following example updates two rows in one batch and sets workYear to 11 for rows whose primary keys employeeId are 1001 and 1002.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+-----------+--------------+
| employeeId | name     | department | position | workYear  | comment      |
+------------+----------+------------+----------+-----------+--------------+
|       1001 | zhangsan | R&D        | dev      |        10 | new employee |
|       1002 | lisi     | R&D        | dev      |        10 | new employee |
+------------+----------+------------+----------+-----------+--------------+
*/
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", 11))
            .add(colVal("comment", "new employee"));
    Row properties2 = row().add(colVal("name", "lisi"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 11))
            .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());
}

batchIncrement

The following example increments workYear by 1 for two rows in one batch, so the final value is 11 for rows whose primary keys employeeId are 1001 and 1002.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+----------+---------+
| employeeId | name     | department | position | workYear | comment |
+------------+----------+------------+----------+----------+---------+
|       1001 | zhangsan | R&D        | dev      |       10 | NULL    |
|       1002 | lisi     | R&D        | dev      |       10 | NULL    |
+------------+----------+------------+----------+----------+---------+
*/
private static void batchIncrementRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey1 = row().add(colVal("employeeId", 1001));
    Row rowKey2 = row().add(colVal("employeeId", 1002));
    Row properties1 = row().add(colVal("workYear", 1));
    Row properties2 = row().add(colVal("workYear", 1));
    Increment incrementOp1 = increment().setRowKey(rowKey1).addMutateRow(properties1);
    Increment incrementOp2 = increment().setRowKey(rowKey2).addMutateRow(properties2);
    BatchOperationResult res = obkvHandle.batchOperation("employees")
            .addOperation(incrementOp1,incrementOp2)
            .execute();
    System.out.println(res.hasError());
}

batchAppend

The following example appends the string dev to position for two rows in one batch, so the final value is java dev for rows whose primary keys employeeId are 1001 and 1002.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+----------+---------+
| employeeId | name     | department | position | workYear | comment |
+------------+----------+------------+----------+----------+---------+
|       1001 | zhangsan | R&D        | java     |       10 | NULL    |
|       1002 | lisi     | R&D        | java     |       10 | NULL    |
+------------+----------+------------+----------+----------+---------+
*/
private static void batchAppendRow(ObTableClient obkvHandle) throws Exception {
    Row rowKey1 = row().add(colVal("employeeId", 1001));
    Row rowKey2 = row().add(colVal("employeeId", 1002));
    Row properties1 = row().add(colVal("position", " dev"));
    Row properties2 = row().add(colVal("position", " dev"));
    Append appendOp1 = append().setRowKey(rowKey1).addMutateRow(properties1);
    Append appendOp2 = append().setRowKey(rowKey2).addMutateRow(properties2);
    BatchOperationResult res = obkvHandle.batchOperation("employees")
            .addOperation(appendOp1,appendOp2)
            .execute();
    System.out.println(res.hasError());
}

batchCheckAndInsUp

The following example checks whether workYear is greater than or equal to 3 for rows whose primary keys employeeId are 1001 and 1002. If the condition is met, it updates comment to good.

// Assume the following data already exists in the database
/*
+------------+----------+------------+----------+----------+---------+
| employeeId | name     | department | position | workYear | comment |
+------------+----------+------------+----------+----------+---------+
|       1001 | zhangsan | R&D        | dev      |       10 | NULL    |
|       1002 | lisi     | R&D        | dev      |       10 | NULL    |
+------------+----------+------------+----------+----------+---------+
*/
private static void batchCheckAndInsUpRow(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))
            .add(colVal("comment", "good"));
    Row properties2 = row().add(colVal("name", "lisi"))
            .add(colVal("department", "R&D"))
            .add(colVal("position", "dev"))
            .add(colVal("workYear", 10))
            .add(colVal("comment", "good"));
    InsertOrUpdate insertUpOp1 = insertOrUpdate().setRowKey(rowKey1).addMutateRow(properties1);
    InsertOrUpdate insertUpOp2 = insertOrUpdate().setRowKey(rowKey2).addMutateRow(properties2);
    ObTableValueFilter filter = compareVal(ObCompareOp.GE, "workYear", 3);
    CheckAndInsUp ckOp1 = new CheckAndInsUp(filter, insertUpOp1, true);
    CheckAndInsUp ckOp2 = new CheckAndInsUp(filter, insertUpOp2, true);
    BatchOperationResult res = obkvHandle.batchOperation("employees")
            .addOperation(ckOp1,ckOp2)
            .execute();
    System.out.println(res.hasError());
}

OceanBase

Customer Stories

Documentation

Update data with OBKV-Table

Update APIs

Update examples

Prerequisites

Single-row update

update

insertOrUpdate

replace

put

increment

append

checkAndInsUp

Batch update

batchUpdate

batchInsertOrUpdate

batchReplace

batchPut

batchIncrement

batchAppend

batchCheckAndInsUp