OBKV-Table operation types

OBKV-Table supports four different operation types: login, execute, batch_execute, and query (scan query).

Each operation type is managed by a separate processor class, with each type having its own process function that handles different RPC message requests through inheritance and derivation.

• ObTableLoginRequest: the login operation type. It requires the username and password of the OceanBase tenant for authentication, which is similar to SQL statements. You can call other OBKV-Table operations only after successful authentication.
• ObTableOperationRequest: the execute type. Operations of this type include insert, update, replace, get, increment, and append.
• ObTableBatchOperationRequest: the batch execute type that consists of multiple execute operations.
• ObTableQueryRequest: the type for streaming queries, such as the range scan for a specific primary key.

The following class diagram shows the implementation of different operation types.

Execute

The OBServer node processes the ObTableOperationRequest operations and returns the values of errno and affected_rows to the client.

Insert

You can call this operation to insert a row.

This operation returns the following results:

• If the row is inserted, the return value of errno is OB_SUCCESS, and that of affected_rows is 1.
• If the insertion fails, the return value of affected_rows is 0.
• If the insertion fails because of a primary key conflict, which means the row already exists, the return value of errno is OB_ERR_PRIMARY_KEY_DUPLICATE.
• Other common values of errno are as follows:
  • OB_TIMEOUT: indicates an execution timeout.
  • OB_TRY_LOCK_ROW_CONFLICT: indicates a lock wait timeout.

Get

You can call this operation to retrieve a row.

The target row is returned if it exists, and null is returned if the target row does not exist.

Delete

You can call this operation to delete a row.

This operation returns the following results:

• If the target row is deleted, the return value of errno is OB_SUCCESS, and that of affected_rows is 1.
• If the target row does not exist, the return value of errno is OB_SUCCESS, and that of affected_rows is 0.

Update

You can call this operation to update a row.

This operation returns the following results:

• If the target row is updated, the return value of errno is OB_SUCCESS, and that of affected_rows is 1.
• If the target row does not exist, the return value of errno is OB_SUCCESS, and that of affected_rows is 0.

Insert_or_update

You can call this operation to insert or update a row.

This operation returns the following results:

• If the target row does not exist, the new row is inserted, and the return value of errno is OB_SUCCESS, and that of affected_rows is 1.
• If the target row already exists, which means a primary key conflict, the row is updated. The return value of errno is OB_SUCCESS, and that of affected_rows is 1.
• If the insertion encounters a unique index conflict, the target row is also updated.

Replace

You can call this operation to replace a row.

This operation returns the following results:

• If the target row does not exist, the new row is inserted, and the return value of errno is OB_SUCCESS, and that of affected_rows is 1.
• If the target row already exists, which means a primary key conflict, the original row is deleted and the new row is inserted. The return value of errno is OB_SUCCESS, and that of affected_rows is greater than 1.
• If a unique index conflict takes place, conflicting rows are deleted, and rows to be replaced are inserted. The return value of errno is OB_SUCCESS, and that of affected_rows is greater than 1 because the deleted rows are counted.

Increment

You can call this operation to atomically increment the value of the specified column by an increment value. The increment value can be negative.

This operation is supported since OceanBase Database V1.4.75. It supports columns of integer data types: TINYINT, SMALLINT, MEDIUMINT, INT, and BIGINT, and their unsigned versions. Errors are returned for columns of other data types.

This operation returns the following results:

• If the calculation result overflows the value range of the column type, an error is returned.
• If the target row does not exist, the new row is inserted and the increment value is set as the initial value, which is equivalent to having an original value of 0.
• If the target row exists but the value of the specified column is NULL, the increment value is set as the initial value, which is equivalent to having an original value of 0.

Append

You can call this operation to atomically append a string to the value of the specified column.

This operation is supported since OceanBase Database V1.4.75. It supports columns of VARCHAR and VARBINARY data types. Errors are returned for columns of other data types.

This operation returns the following results:

• If the calculation result overflows the length of the column, an error is returned.
• If the target row does not exist, the new row is inserted and the increment value is set as the initial value, which is equivalent to having an original value of an empty string.
• If the target row exists but the specified column value is NULL, the increment value is set as the initial value, which is equivalent to having an original value of an empty string.

Batch execute

A batch execute operation includes a collection of execute operations. For more information about a specific execute operation, see the Execute section.

To accelerate the batch operation, the OBServer node is optimized for batch processing read-only transactions. Therefore, it demonstrates better performance in batch operations of read-only requests than those of read/write requests.

Query

OBKV-Table supports range scan based on the primary key or the prefix of the primary key. When the primary key is not specified, OBKV-Table also supports range scan based on the index or index prefix.

You can call query operations to scan multiple specified segments. At present, the OBServer node can return a result set of at most 64 MB of data (adjustable) in the RPC message interaction process of a Query.

For more information about how to set various query conditions, see Introduction to the client and instructions.