批量操作接口的相关说明
批量操作,顾名思议,就是一个请求中可以同时操作多条记录,目前TcaplusDB对于Generic表支持的批量请求包括批量get操作,批量insert操作,批量update操作,批量replace操作,批量delete操作。
- batch类的操作都是非原子操作,只要有一个记录执行成功,总的执行结果就是成功,但是响应包中会给出每条记录的执行结果及错误码。
- 批量SetKey SetValue注意:批量请求的record在SetKey SetValue之后,调用record的Pack方法打下包
1. 批量操作响应包错误码
批量操作的响应包错误码分为两种:总错误码和子操作错误码。当至少一个子操作成功时,总错误码为成功;当所有子操作都失败时,总错误码为失败。总错误码可以通过response的返回值获取,子操作错误码通过获取单个record的返回值得到。
2. 批量操作响应包分包
2.1. 分包条件
当响应包超过256KB会触发分包。但保证分包不会切分单个记录(不管这个记录多大),例如,响应包的3个记录分别是10KB、251KB、1MB,会分为2个包返回,即(10KB、251KB)和(1MB)。
2.2. 不同SDK对于分包的行为
对于PB表 C++ SDK发送的批量操作,TcaplusDB在响应包达到分包条件后,会自动进行分包返回。
对于TDR表 C++ SDK发送的批量操作,分包规则如下:
批量get操作,TcaplusDB在响应包达到分包条件后,会自动进行分包返回。
其他批量操作,可通过TcaplusServiceRequest::SetMultiResponseFlag()接口设置:
- 当设置flag=0(默认值也是0),表示不允许响应包进行多包返回, 这种情况下,一趟响应若涉及多个记录(超过256KB),只返回第一个响应包(部分记录)。未设置分包,可能会出现返回响应包数据记录为空或者比实际少的情况。 - 当设置flag=1时,表示允许响应包进行多包返回,即允许分包,当TcaplusDB在响应包达到分包条件后,会进行分包返回。
其他SDK,请参考TcaplusDB SDK & API。
2.3. 允许分包时,SDK如何判断是最后一个响应包
C++ TDR API,可调用TcaplusServiceResponse::HaveMoreResPkgs()判断;
C++ PB API,回调中返回错误码API_ERR_NO_MORE_RECORD;
其他SDK,请参考TcaplusDB SDK & API。
3. 批量操作响应包是否返回记录
对于批量get操作,是会返回每条记录的执行结果以及对应的记录数据;
对于其他批量操作,默认是只返回每条记录的执行结果,而不返回记录数据,如果还需要返回记录数据,SDK可以通过设置一个flag来要求TcaplusDB后台返回记录数据;
batch场景,响应消息必然返回key字段,不会返回value字段(BatchGet除外,会返回value);需要返回value时,请调用request的SetResultFlagForSuccess和SetResultFlagForFail;
4. 批量操作响应包处理
当前以C++ TDR SDK为例,讲解一下批量操作响应包的处理流程:
先通过response获取响应包的总错误码,如果总错误码不等于0,就表示所有的都处理失败了;总错误码等于0时,表示至少有一条记录处理成功了,可以继续后面的操作;
调用GetRecordNum()接口来得到当前响应包中携带的记录数,这些记录都是TcaplusDB已经处理过的;BatchGet操作,RecordNum只是查询的key的数量,不是真实结果的记录数;部分key查询partkeyselect,RecordNum部分key返回的记录数,就是响应包中返回的记录数;
循环调用FetchRecord()接口来获取每条记录的执行结果以及具体的记录数据;当FetchRecord()返回值不为0时,表示这条记录执行失败了;当FetchRecord()返回值为0时,表示这条记录执行成功了,如果设置了返回具体的记录数据,那么可以进一步得到记录数据;
判断是否是最后一个响应包,如果不是最后一个响应包,那么需要继续接收后续的响应包,如果是最后一个响应包,那么表示此次批量操作已经完成了;
5. 批量操作限制
- 一个批量操作最多允许操作1024条记录;
6.
各个SDK和API关于批量操作的具体接口和示例,请参考TcaplusDB SDK & API。