Batch Operation Interface Description
Batch operation means that multiple records can be operated simultaneously in one request. At present, TcaplusDB supports batch requests for Generic tables, including batch get operations, batch insert operations, batch update operations, batch replace operations, and batch delete operations.
- The batch class operations are all non atomic operations. As long as one record is successfully executed, the overall execution result is successful. However, the response package will provide the execution result and error code for each record.
- Note for batch SetKey SetValue: after SetKey SetValue, call the Pack method of the record to download the package.
1. Response Package Error Code of Batch Operation
The response package error code of batch operation is divided into two types: whole error code and sub-operation error code. When at least one sub-operation is successful, the whole error code is successful; When all sub-operations fail, the whole error code is failure. The whole error code can be obtained from the return value of the response, and the sub-operation error code can be obtained from the return value of a single record.
2. Split Response Package of Batch Operation
2.1. Conditions for Splitting Package
Package splitting will be triggered when the response package exceeds 256 KB. However, it should be ensured that package splitting will not split a single record (no matter how large the record is). For example, the three records of the response package are 10 KB, 251 KB, and 1 MB respectively, and will be returned in two packages, namely (10 KB, 251 KB) and (1 MB).
2.2. Different SDKs for Package Splitting
For batch operations sent by the PB table C++SDK, TcaplusDB will automatically return the split packages after the response package meets the package splitting condition.
For batch operations sent by the TDR table C++SDK, the package splitting rules are as follows:
For batch get operations, TcaplusDB will automatically split the package after the response package meets the splitting condition.
Other batch operations can be set through the interface TcaplusServiceRequest::SetMultiResponseFlag():
- When flag=0 is set (the default value is also 0), it means that multi-package return is not allowed. In this case, if a response involves multiple records (more than 256 KB), only the first response package (part records) will be returned. If package splitting is not set, the returned response packet record may be empty or less than the actual value. - When flag=1 is set, it means that multi-package return is allowed, that is, package splitting is allowed. TcaplusDB will split the package when the response package meets the splitting condition.For other SDKs, please refer to TcaplusDB SDK & API.
2.3. How Does the SDK Determine Whether It Is the Last Response Package When Package Splitting Is Allowed
For C++TDR API, TcaplusServiceResponse::HaveMoreResPkgs() can be called to determine;
For C++ PB API, error code API_ERR_NO_MORE_RECORD can be returned in the callback;
For other SDKs, please refer to TcaplusDB SDK & API.
3. Whether the Batch Operation Response Package Returns Records
For batch get operations, the execution results and corresponding record data of each record will be returned;
For other batch operations, the default is to return only the execution result of each record, but not the record data. If the record data needs to be returned, the SDK can set a flag to enable the TcaplusDB to return the record data.
In the batch scenario, the response message must return the key field and not the value field (except for BatchGet, which returns value); When a value needs to be returned, please call the SetResultFlagForSuccess and SetResultFlagForFail of the request;
4. Batch Operation Response Package Processing
Take the C++TDR SDK as an example to explain the processing process of batch operation response package:
First, get the whole error code of the response package through response. If the whole error code is not equal to 0, it means that the execution of all records failed; If the whole error code is equal to 0, it means that at least one record has been successfully executed, and continue the following operations;
Call the GetRecordNum() interface to get the number of records carried in the current response package. These records have been processed by TcaplusDB;
Call the FetchRecord() interface in a loop to get the execution results and data of each record; If the FetchRecord() return value is not equal to 0, it means that the execution of this record failed. If the FetchRecord() return value is equal to 0, it means that the record has been successfully executed. If the specific record data is set to return, the record data can be obtained further;
Determine whether it is the last response package. If it is not the last response package, continue to receive subsequent response packages. If it is the last response package, it means that the batch operation has been completed;
5. Batch Operation Limitations
- A batch operation can operate a maximum of 1024 records;
6.
For specific interfaces and examples of batch operations in various SDKs and APIs, please refer to TcaplusDB SDK & API.