This topic describes the write capability of OBKV-Table. The OBKV-Table Java client supports single-row and batch data writes for both index-organized and heap-organized tables. You can choose the appropriate interface based on your requirements.
Supported write interfaces
The following interfaces of ObTableClient support writing:
API |
Description |
Considerations |
|---|---|---|
insert(String tableName) |
Writes a row of data | The write fails when a primary key conflict occurs. |
insertOrUpdate(String tableName) |
Writes or updates a row of data | |
replace(String tableName) |
Replaces a row of data | If the old row does not exist, a new row is written. |
put(String tableName) |
Overwrites a row of data |
|
Write examples
Prerequisites
Before you write data, make sure that the following prerequisites are met:
- Your ObTableClient has been initialized.
- You have created an index-organized or heap-organized table in your database. 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) -- Creating a unique index can speed up queries ) ORGANIZATION = HEAP PARTITION BY KEY(c1) PARTITIONS 97; -- Specify the heap table by using the ORGANIZATION parameter.
Other notes:
- JSON data types are supported. For details and write examples, see Data types supported by OBKV-Table.
Single-row write
The following sample code shows how to use ObTableClient to write a single row of data.
insert
The sample code writes a row of data whose primary key employeeId is 1001, inserting 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 interface to write a single row to a heap-organized table. For heap-organized table writes, you must set the partitioning key value by using the setPartitionKey interface to ensure correct data routing.
@Test
public void testSingleInsert() throws Exception {
try {
// Insert data
// Note that you need to set the value of partitioning key c1 using setPartitionKey.
// You also need to set the value of c1 using addMutateColVal.
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
The sample code demonstrates how to use ObTableClient to write or update a row of data. The primary key employeeId is 1001, and four attribute columns are written.
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 interface to write or update a single row in a heap-organized table. For heap-organized table writes, you must set the partitioning key value by using the setPartitionKey interface to ensure correct data routing.
@Test
public void testSingleInsertOrUpdate1() throws Exception {
try {
// Insert data
// Note that you need to set the value of partitioning key c1 using setPartitionKey.
// You also need to set the value of c1 using addMutateColVal.
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
The sample code demonstrates how to use ObTableClient to replace a row of data. The primary key employeeId is 1001, and four attribute columns are written.
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 interface to replace a single row in a heap-organized table. For heap-organized table replacement operations, you must set the partitioning key value by using the setPartitionKey interface to ensure correct data routing.
@Test
public void testSingleReplace1() throws Exception {
try {
// Insert data
// Note that you need to set the value of partitioning key c1 using setPartitionKey.
// You also need to set the value of c1 using addMutateColVal.
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 interface does not support heap-organized tables.
The sample code overwrites a row of data in an index-organized table by using ObTableClient. The primary key employeeId is 1001, and four attribute columns are written.
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 sample code demonstrates how to use ObTableClient to write data in batches.
batchInsert
The sample code inserts two rows of data in a batch. The primary keys employeeId are 1001 and 1002, and each row contains 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 BatchOperation interface to write data to a heap-organized table in batches. For heap-organized table writes, you must set the partitioning key value by using the setPartitionKey interface to ensure correct data routing.
@Test
public void testBatchInsert() throws Exception {
try {
// Perform batch inserts by using BatchOperation
BatchOperation batch = client.batchOperation("test");
// Add multiple insert operations
// Note that you need to set the value of partitioning key c1 using setPartitionKey.
// You also need to set the value of c1 using addMutateColVal.
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
The sample code inserts two rows of data in a batch. The primary keys employeeId are 1001 and 1002, and each row contains 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 BatchOperation interface to write or update data in a heap-organized table in batches. For heap-organized table writes, you must set the partitioning key value by using the setPartitionKey interface to ensure correct data routing.
@Test
public void testBatchInsertOrUpdate1() throws Exception {
try {
// Perform batch inserts by using BatchOperation
BatchOperation batch = client.batchOperation(tableName);
// Add multiple insert operations
// Note that you need to set the value of partitioning key c1 using setPartitionKey.
// You also need to set the value of c1 using addMutateColVal.
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
The sample code inserts two rows of data in a batch. The primary keys employeeId are 1001 and 1002, and each row contains 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 BatchOperation interface to replace data in a heap-organized table in batches. For heap-organized table replacement operations, you must set the partitioning key value by using the setPartitionKey interface to ensure correct data routing.
@Test
public void testBatchReplace1() throws Exception {
try {
// Perform batch inserts by using BatchOperation
BatchOperation batch = client.batchOperation(tableName);
// Add multiple replace operations
// Note that you need to set the value of partitioning key c1 using setPartitionKey.
// You also need to set the value of c1 using addMutateColVal.
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 sample code inserts two rows of data in a batch. The primary keys employeeId are 1001 and 1002. Each row contains all five attribute columns of 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());
}