Conditional Filter and Update

Conditional update includes two parts: conditional filter and update. The latter currently refers to updating arrays.

1. Instructions

For addition, deletion, modification and query, filter conditions can be set through the SetCondition interface. Only when the conditions are met, the query data will be returned or the update operation will be performed. Otherwise, error codes COMMON_ERR_CONDITION_NOT_MATCHED will be returned.

int32_t TcaplusServiceRecord::SetCondition(const std::string &condition);

// Batch class request, calling SetCondition on the Request object
int32_t TcaplusServiceRequest::SetCondition(const std::string &condition);

For the modification request, in addition to SetData or SetValue to set the data, it can also set update operations through the SetOperation interface. Currently, it refers to the insertion (PUSH), deletion (POP), and modification (SET) of arrays.

// Operation state to set the array in a record
// [IN] operation, operation state, including PUSH/POP/SET/GET
// [IN] operationOption, operation option, useful only for GET. See enum RecordOperationOption
// retval 0: successful setting
// retval < 0: failed setting 
int32_t TcaplusServiceRecord::SetOperation(const std::string &operation, int operateOption);

// Batch class request, calling SetCondition on the Request object
int32_t TcaplusServiceRequest::SetOperation(const std::string &operation, int operateOption);

Examples

USER u = {};
// Set primary key
u.dwId = 1;
strcpy(u.szName, "a");
record->SetData(&u, sizeof(u));
// For pre-condition filtering, first judge whether the gameids has 101
record->SetCondition("gameids NOT CONTAINS($ = 101)");
// For post-array operations, insert 101
record->SetOperation("PUSH gameids#[-1][$ = 101]");
// Send a write request
// ...
// Process the response return value
if (ret == COMMON_ERR_CONDITION_NOT_MATCHED) // If the conditions are not met, it indicates that there is 101 in gameids
{
    // ...
}

The above SetCondition and SetOperation settings are SQL like text, see Detailed Syntax Description.

2. Which Commands Support Conditional Updates?

In the SDK with version 3.55.0 or higher, the supported commands are

• TCAPLUS_API_GET_REQ
• TCAPLUS_API_DELETE_REQ
• TCAPLUS_API_REPLACE_REQ
• TCAPLUS_API_UPDATE_REQ
• TCAPLUS_API_GET_BY_PARTKEY_REQ
• TCAPLUS_API_LIST_GET_REQ
• TCAPLUS_API_LIST_GETALL_REQ
• TCAPLUS_API_LIST_DELETE_REQ
• TCAPLUS_CMD_LIST_DELETE_BATCH_REQ
• TCAPLUS_API_LIST_REPLACE_REQ
• TCAPLUS API TABLE TRAVERSE REQ (Traverse the whole table)
• TCAPLUS_API_LIST_TABLE_TRAVERSE_REQ (Traverse the whole table)
• TCAPLUS_API_UPDATE_ITEM_REQ (PUSH, SET, POP of arrays)
• TCAPLUS_API_LIST_UPDATE_ITEM_REQ (PUSH, SET, POP of arrays)
• TCAPLUS_API_QUERY_REQ (GET of the array, that is, the array element of the subscript range returned by the query)
• TCAPLUS_API_LIST_QUERY_REQ (GET of the array, that is, the array element of the subscript range returned by the query)

Part requests and batch operations can only be supported if the version is greater than or equal to 3.64.0, including

• TCAPLUS_API_INCREASE_REQ
• TCAPLUS_API_UPDATE_BY_PARTKEY_REQ
• TCAPLUS_API_DELETE_BY_PARTKEY_REQ
• TCAPLUS_API_BATCH_GET_REQ
• TCAPLUS_API_BATCH_DELETE_REQ
• TCAPLUS_API_BATCH_UPDATE_REQ
• TCAPLUS_API_BATCH_REPLACE_REQ
• TCAPLUS_API_BATCH_GET_BY_PARTKEY_REQ

For more functional support of conditional filtering and updating, please contact Tcaplus.

3. Notations

• The maximum text length of parameters condition and operation is 1023.
• Conditional filter and update depend on the Unpack ability of TDR. The SDK of TcaplusDB supports two ways to write data records, namely, Record.SetValue() and Record.SetData(). Conditional update does not support complex data types (structures and arrays) written by SetValue().
• The array field in the TDR table has a corresponding refer field (the actual size of the array), and the PUSH and POP operations on the array will automatically modify this refer field.