批量操作接口的相关说明

批量操作,顾名思议,就是一个请求中可以同时操作多条记录,目前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对于分包的行为

  1. 对于PB表 C++ SDK发送的批量操作,TcaplusDB在响应包达到分包条件后,会自动进行分包返回。

  2. 对于TDR表 C++ SDK发送的批量操作,分包规则如下:

    批量get操作,TcaplusDB在响应包达到分包条件后,会自动进行分包返回。

    其他批量操作,可通过TcaplusServiceRequest::SetMultiResponseFlag()接口设置:

    - 当设置flag=0(默认值也是0),表示不允许响应包进行多包返回, 这种情况下,一趟响应若涉及多个记录(超过256KB),只返回第一个响应包(部分记录)。未设置分包,可能会出现返回响应包数据记录为空或者比实际少的情况。
    
    - 当设置flag=1时,表示允许响应包进行多包返回,即允许分包,当TcaplusDB在响应包达到分包条件后,会进行分包返回。
    
  3. 其他SDK,请参考TcaplusDB SDK & API

2.3. 允许分包时,SDK如何判断是最后一个响应包

  1. C++ TDR API,可调用TcaplusServiceResponse::HaveMoreResPkgs()判断;

  2. C++ PB API,回调中返回错误码API_ERR_NO_MORE_RECORD;

  3. 其他SDK,请参考TcaplusDB SDK & API

3. 批量操作响应包是否返回记录

  1. 对于批量get操作,是会返回每条记录的执行结果以及对应的记录数据;

  2. 对于其他批量操作,默认是只返回每条记录的执行结果,而不返回记录数据,如果还需要返回记录数据,SDK可以通过设置一个flag来要求TcaplusDB后台返回记录数据;

  3. batch场景,响应消息必然返回key字段,不会返回value字段(BatchGet除外,会返回value);需要返回value时,请调用request的SetResultFlagForSuccess和SetResultFlagForFail;

4. 批量操作响应包处理

当前以C++ TDR SDK为例,讲解一下批量操作响应包的处理流程:

  1. 先通过response获取响应包的总错误码,如果总错误码不等于0,就表示所有的都处理失败了;总错误码等于0时,表示至少有一条记录处理成功了,可以继续后面的操作;

  2. 调用GetRecordNum()接口来得到当前响应包中携带的记录数,这些记录都是TcaplusDB已经处理过的;BatchGet操作,RecordNum只是查询的key的数量,不是真实结果的记录数;部分key查询partkeyselect,RecordNum部分key返回的记录数,就是响应包中返回的记录数;

  3. 循环调用FetchRecord()接口来获取每条记录的执行结果以及具体的记录数据;当FetchRecord()返回值不为0时,表示这条记录执行失败了;当FetchRecord()返回值为0时,表示这条记录执行成功了,如果设置了返回具体的记录数据,那么可以进一步得到记录数据;

  4. 判断是否是最后一个响应包,如果不是最后一个响应包,那么需要继续接收后续的响应包,如果是最后一个响应包,那么表示此次批量操作已经完成了;

5. 批量操作限制

  1. 一个批量操作最多允许操作1024条记录;

6.

各个SDK和API关于批量操作的具体接口和示例,请参考TcaplusDB SDK & API

results matching ""

    No results matching ""