Insert data with OBKV-Table|OceanBase Cloud

Insert data with OBKV-Table

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

This topic describes OBKV-Table write capabilities. The OBKV-Table Java client supports single-row and batch writes for index-organized tables and heap-organized tables. Choose the appropriate API based on your requirements.

Write APIs

The following ObTableClient APIs support writes:

API	Description	Notes
`insert(String tableName)`	Write a single row	Fails when the primary key conflicts
`insertOrUpdate(String tableName)`	Insert or update a single row
`replace(String tableName)`	Replace a single row	Inserts a new row when the old row does not exist
`put(String tableName)`	Overwrite a single row	You must write every column The table has no indexes The table has no LOB columns The tenant `binlog_row_image` value must be `minimal` Heap-organized tables are not supported

Write examples

Prerequisites

Before writing data, complete the following:

Your ObTableClient is initialized.

You have created an index-organized table or heap-organized table in your database. For example:

-- Index-organized 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;

-- Heap-organized table
CREATE TABLE test (
    c1 bigint, 
    c2 varchar(20), 
    c3 bigint,
    UNIQUE INDEX idx_unique_c1 (c1) -- A unique index can speed up queries
  ) ORGANIZATION = HEAP PARTITION BY KEY(c1) PARTITIONS 97; -- Use ORGANIZATION to specify a heap table

Additional notes:

JSON is supported.

Single-row write

The following examples show how to write a single row with ObTableClient.

insert

Index-organized table

Heap-organized table

The example writes one row with primary key employeeId set to 1001 and four attribute columns.

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();
}

This example shows how to use the insert API to write a single row to a heap table. For heap tables, you must call setPartitionKey to set the partition key so data is routed correctly.

@Test
public void testSingleInsert() throws Exception {
    try {
        // Insert data
        // Use setPartitionKey to set the partition key c1
        // Use addMutateColVal to set the value of c1 as well
        MutationResult result = client.insert("test")
            .setPartitionKey(row(colVal("c1", 1000L)))
            .addMutateColVal(colVal("c1", 1000L), colVal("c2", "test1"), colVal("c3", 3000L))
            .execute();
    
        assertEquals("Insert should affect 1 row", 1, result.getAffectedRows());   
        System.out.println("Single insert successful: " + result + " row affected");
    } finally {
        // Clean up data
        truncateTable();
    }
}

insertOrUpdate

Index-organized table

Heap-organized table

The example shows how to insert or update one row with primary key employeeId set to 1001 and four attribute columns.

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();
}

This example shows how to use the insertOrUpdate API to insert or update a single row in a heap table. For heap tables, you must call setPartitionKey to set the partition key so data is routed correctly.

@Test
public void testSingleInsertOrUpdate1() throws Exception {
    try {
        // Insert data
        // Use setPartitionKey to set the partition key c1
        // Use addMutateColVal to set the value of c1 as well
        MutationResult result = client.insertOrUpdate(tableName)
            .setPartitionKey(row(colVal("c1", 1000L)))
            .addMutateColVal(colVal("c1", 1000L), colVal("c2", "test1"), colVal("c3", 3000L))
            .execute(); 
    
        assertEquals("Insert should affect 1 row", 1, result.getAffectedRows());
        System.out.println("Single insertOrUpdate successful: " + result + " row affected");
    } finally {
        // Clean up data
        truncateTable();
    }
}

replace

Index-organized table

Heap-organized table

The example shows how to replace one row with primary key employeeId set to 1001 and four attribute columns.

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();
}

This example shows how to use the replace API to replace a single row in a heap table. For heap tables, you must call setPartitionKey to set the partition key so data is routed correctly.

@Test
public void testSingleReplace1() throws Exception {
    try {
        // Insert data
        // Use setPartitionKey to set the partition key c1
        // Use addMutateColVal to set the value of c1 as well
        MutationResult result = client.replace(tableName)
            .setPartitionKey(row(colVal("c1", 1000L)))
            .addMutateColVal(colVal("c1", 1000L), colVal("c2", "test1"), colVal("c3", 3000L))
            .execute();
        
        assertEquals("Insert should affect 1 row", 1, result.getAffectedRows());
        System.out.println("Single replace successful: " + result + " row affected");
    } finally {
        // Clean up data
        truncateTable();
    }
}

put

Notice

This API does not support heap-organized tables.

The example shows how to overwrite one row in an index-organized table with primary key employeeId set to 1001 and four attribute columns.

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();
}

Batch write

The following examples show how to batch-write data with ObTableClient.

batchInsert

Index-organized table

Heap-organized table

The example writes two rows in one batch with primary keys employeeId set to 1001 and 1002. Each row has four attribute columns.

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());
}

This example shows how to use the batchInsert API to batch-write rows to a heap table. For heap tables, you must call setPartitionKey to set the partition key so data is routed correctly.

@Test
public void testBatchInsert() throws Exception {
    try {
        // Use BatchOperation for batch insert
        BatchOperation batch = client.batchOperation("test");
        
        // Add multiple insert operations
        // Use setPartitionKey to set the partition key c1
        // Use addMutateColVal to set the value of c1 as well
        for (int i = 1; i <= 3; i++) {
            Insert insert = new Insert();
            insert.setPartitionKey(row(colVal("c1", (long)(1000 + i))))
                .addMutateColVal(colVal("c1", (long)(1000 + i)), colVal("c2", "batch_test" + i), colVal("c3", (long)(3000 + i)));
            batch.addOperation(insert);
        }
        
        batch.execute();
        System.out.println("Batch insert successful: 3 operations executed");
    } finally {
        // Clean up data
        truncateTable();
    }
}

batchInsertOrUpdate

Index-organized table

Heap-organized table

The example writes two rows in one batch with primary keys employeeId set to 1001 and 1002. Each row has four attribute columns.

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());
}

This example shows how to use the batchInsertOrUpdate API to batch insert or update rows in a heap table. For heap tables, you must call setPartitionKey to set the partition key so data is routed correctly.

@Test
public void testBatchInsertOrUpdate1() throws Exception {
    try {
        // Use BatchOperation for batch insert
        BatchOperation batch = client.batchOperation(tableName);
        
        // Add multiple insert operations
        // Use setPartitionKey to set the partition key c1
        // Use addMutateColVal to set the value of c1 as well
        for (int i = 1; i <= 3; i++) {
            InsertOrUpdate insertOrUpdate = new InsertOrUpdate();
            insertOrUpdate.setPartitionKey(row(colVal("c1", (long)(1000 + i))))
                .addMutateColVal(colVal("c1", (long)(1000 + i)), colVal("c2", "batch_test" + i), colVal("c3", (long)(3000 + i)));
            batch.addOperation(insertOrUpdate);
        }
        
        batch.execute();
        System.out.println("Batch insertOrUpdate successful: 3 operations executed");
    } finally {
        // Clean up data
        truncateTable();
    }
}

batchReplace

Index-organized table

Heap-organized table

The example writes two rows in one batch with primary keys employeeId set to 1001 and 1002. Each row has four attribute columns.

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());
}

This example shows how to use the batchReplace API to batch-replace rows in a heap table. For heap tables, you must call setPartitionKey to set the partition key so data is routed correctly.

@Test
public void testBatchReplace1() throws Exception {
    try {
        // Use BatchOperation for batch insert
        BatchOperation batch = client.batchOperation(tableName);
        
        // Add multiple replace operations
        // Use setPartitionKey to set the partition key c1
        // Use addMutateColVal to set the value of c1 as well
        for (int i = 1; i <= 3; i++) {
            Replace replace = new Replace();
            replace.setPartitionKey(row(colVal("c1", (long)(1000 + i))))
                .addMutateColVal(colVal("c1", (long)(1000 + i)), colVal("c2", "batch_test" + i), colVal("c3", (long)(3000 + i)));
            batch.addOperation(replace);
        }
        
        batch.execute();
        System.out.println("Batch replace successful: 3 operations executed");
    } finally {
        // Clean up data
        truncateTable();
    }
}

batchPut

Notice

This API does not support heap-organized tables.

The example writes two rows in one batch with primary keys employeeId set to 1001 and 1002. Each row includes all five attribute columns in the table.

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());
}

OceanBase

Customer Stories

Documentation

Insert data with OBKV-Table

Write APIs

Write examples

Prerequisites

Single-row write

insert

insertOrUpdate

replace

put

Notice

Batch write

batchInsert

batchInsertOrUpdate

batchReplace

batchPut

Notice