Operações em lote transacionais no Azure Cosmos DB

APLICA-SE A: NoSQL

O lote transacional descreve um grupo de operações pontuais que precisam ser bem-sucedidas ou falhar junto com a mesma chave de partição em um contêiner. As operações são definidas, adicionadas ao lote e o lote é executado. Se todas as operações forem bem-sucedidas na ordem em que estão descritas na operação de lote transacional, a transação será confirmada. No entanto, se alguma operação falhar, toda a transação será revertida.

O que é uma transação no Azure Cosmos DB

Uma transação em um banco de dados típico pode ser definida como uma sequência de operações executadas como uma única unidade lógica de trabalho. Cada transação fornece garantias de propriedade ACID (Atomicidade, Consistência, Isolamento, Durabilidade).

• A atomicidade garante que todas as operações realizadas dentro de uma transação são tratadas como uma única unidade, e todas elas estão comprometidas ou nenhuma delas está.
• A consistência garante que os dados estejam sempre em um estado válido nas transações.
• O isolamento garante que nenhuma transação interfira uma com a outra – muitos sistemas comerciais fornecem vários níveis de isolamento que podem ser usados com base nas necessidades do aplicativo.
• A durabilidade garante que qualquer alteração confirmada em um banco de dados esteja sempre presente. O Azure Cosmos DB dá suporte a transações totalmente compatíveis com ACID com isolamento de instantâneo para operações dentro da mesma chave de partição lógica.

Operações em lote transacionais e procedimentos armazenados

Atualmente, o Azure Cosmos DB dá suporte a procedimentos armazenados, que também fornecem o escopo transacional em operações. No entanto, as operações em lote transacionais oferecem os seguintes benefícios:

• Opção de idioma – O lote transacional é suportado no SDK e no idioma com o qual você já trabalha, enquanto os procedimentos armazenados precisam ser escritos em JavaScript.
• Controle de versão de código – Versionar o código do aplicativo e integrá-lo ao seu pipeline de CI/CD é muito mais natural do que orquestrar a atualização de um procedimento armazenado e garantir que a substituição aconteça no momento certo. Também facilita a reversão de alterações.
• Desempenho – Reduziu a latência em operações equivalentes em até 30% em comparação com a execução do procedimento armazenado.
• Serialização de conteúdo – Cada operação dentro de um lote transacional pode usar opções de serialização personalizadas para sua carga útil.

Como criar uma operação em lote transacional

.NET

Ao criar uma operação em lote transacional, comece com uma instância de contêiner e chame CreateTransactionalBatch:

PartitionKey partitionKey = new PartitionKey("road-bikes");

TransactionalBatch batch = container.CreateTransactionalBatch(partitionKey);

Em seguida, adicione várias operações ao lote:

Product bike = new (
    id: "68719520766",
    category: "road-bikes",
    name: "Chropen Road Bike"
);

batch.CreateItem<Product>(bike);

Part part = new (
    id: "68719519885",
    category: "road-bikes",
    name: "Tronosuros Tire",
    productId: bike.id
);

batch.CreateItem<Part>(part);

Finalmente, chame ExecuteAsync no lote:

using TransactionalBatchResponse response = await batch.ExecuteAsync();

Uma vez recebida a resposta, verifique se a resposta foi bem-sucedida. Se a resposta indicar um sucesso, extraia os resultados:

if (response.IsSuccessStatusCode)
{
    TransactionalBatchOperationResult<Product> productResponse;
    productResponse = response.GetOperationResultAtIndex<Product>(0);
    Product productResult = productResponse.Resource;

    TransactionalBatchOperationResult<Part> partResponse;
    partResponse = response.GetOperationResultAtIndex<Part>(1);
    Part partResult = partResponse.Resource;
}

Importante

Se houver uma falha, a operação com falha terá um código de status de seu erro correspondente. Todas as outras operações terão um código de status 424 (dependência com falha). Se a operação falhar porque tenta criar um item que já existe, um código de status de 409 (conflito) será retornado. O código de status permite identificar a causa da falha da transação.

Java

Ao criar uma operação de lote transacional, chame CosmosBatch.createCosmosBatch:

PartitionKey partitionKey = new PartitionKey("road-bikes");

CosmosBatch batch = CosmosBatch.createCosmosBatch(partitionKey);

Em seguida, adicione várias operações ao lote:

Product bike = new Product();
bike.setId("68719520766");
bike.setCategory("road-bikes");
bike.setName("Chropen Road Bike");

batch.createItemOperation(bike);

Part part = new Part();
part.setId("68719519885");
part.setCategory("road-bikes");
part.setName("Tronosuros Tire");
part.setProductId(bike.getId());

batch.createItemOperation(part);

Finalmente, use uma instância de contêiner para chamar executeCosmosBatch com o lote:

CosmosBatchResponse response = container.executeCosmosBatch(batch);

Uma vez recebida a resposta, verifique se a resposta foi bem-sucedida. Se a resposta indicar um sucesso, extraia os resultados:

if (response.isSuccessStatusCode())
{
    List<CosmosBatchOperationResult> results = response.getResults();
}

Importante

Se houver uma falha, a operação com falha terá um código de status de seu erro correspondente. Todas as outras operações terão um código de status 424 (dependência com falha). Se a operação falhar porque tenta criar um item que já existe, um código de status de 409 (conflito) será retornado. O código de status permite identificar a causa da falha da transação.

Python

Obter ou criar uma instância de contêiner:

container = database.create_container_if_not_exists(id="batch_container",
                                                        partition_key=PartitionKey(path='/category'))

Em Python, as operações de lote transacional são muito semelhantes às apis de operações singulares e são tuplas contendo (operation_type_string, args_tuple, batch_operation_kwargs_dictionary). Abaixo estão os itens de exemplo que serão usados para demonstrar a funcionalidade das operações em lote:

create_demo_item = {
    "id": "68719520766",
    "category": "road-bikes",
    "name": "Chropen Road Bike"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item1 = {
    "id": "68719519884",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item2 = {
    "id": "68719519886",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item3 = {
    "id": "68719519887",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, we'll upsert the item with id 68719519885
upsert_demo_item = {
    "id": "68719519885",
    "category": "road-bikes",
    "name": "Tronosuros Tire Upserted",
    "productId": "68719520768"
}

# for replace demo, we'll replace the read_demo_item2 with this item
replace_demo_item = {
    "id": "68719519886",
    "category": "road-bikes",
    "name": "Tronosuros Tire replaced",
    "productId": "68719520769"
}

# for replace with etag match demo, we'll replace the read_demo_item3 with this item
# The use of etags and if-match/if-none-match options allows users to run conditional replace operations
# based on the etag value passed. When using if-match, the request will only succeed if the item's latest etag
# matches the passed in value. For more on optimistic concurrency control, see the link below:
# https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency
replace_demo_item_if_match_operation = {
    "id": "68719519887",
    "category": "road-bikes",
    "name": "Tronosuros Tireh",
    "wasReplaced": "Replaced based on etag match"
    "productId": "68719520769"
}

Prepare as operações a serem adicionadas ao lote:

create_item_operation = ("create", (create_demo_item,), {})
read_item_operation = ("read", ("68719519884",), {})
delete_item_operation = ("delete", ("68719519885",), {})
upsert_item_operation = ("upsert", (upsert_demo_item,), {})
replace_item_operation = ("replace", ("68719519886", replace_demo_item), {})
replace_item_if_match_operation = ("replace",
                                       ("68719519887", replace_demo_item_if_match_operation),
                                       {"if_match_etag": container.client_connection.last_response_headers.get("etag")})

Adicione as operações ao lote:

batch_operations = [
        create_item_operation,
        read_item_operation,
        delete_item_operation,
        upsert_item_operation,
        replace_item_operation,
        replace_item_if_match_operation
    ]

Finalmente, execute o lote:

try:
    # Run that list of operations
    batch_results = container.execute_item_batch(batch_operations=batch_operations, partition_key="road_bikes")
    # Batch results are returned as a list of item operation results - or raise a CosmosBatchOperationError if
    # one of the operations failed within your batch request.
    print("\nResults for the batch operations: {}\n".format(batch_results))
except exceptions.CosmosBatchOperationError as e:
        error_operation_index = e.error_index
        error_operation_response = e.operation_responses[error_operation_index]
        error_operation = batch_operations[error_operation_index]
        print("\nError operation: {}, error operation response: {}\n".format(error_operation, error_operation_response))
    # [END handle_batch_error]

Nota para usar a operação de patch e replace_if_match_etag operação no lote
O dicionário kwargs de operação em lote é limitado e leva apenas um total de três valores de chave diferentes. No caso de querer usar patch condicional dentro do lote, o uso de filter_predicate chave está disponível para a operação de patch, ou no caso de querer usar etags com qualquer uma das operações, o uso das chaves if_match_etag/if_none_match_etag também está disponível.

batch_operations = [
       ("replace", (item_id, item_body), {"if_match_etag": etag}),
       ("patch", (item_id, operations), {"filter_predicate": filter_predicate, "if_none_match_etag": etag}),
   ]

Importante

Se houver uma falha, a operação com falha terá um código de status de seu erro correspondente. Todas as outras operações terão um código de status 424 (dependência com falha). Se a operação falhar porque tenta criar um item que já existe, um código de status de 409 (conflito) será retornado. O código de status permite identificar a causa da falha da transação.

Como são executadas as operações transacionais em lote

Quando o Lote Transacional é executado, todas as operações no Lote Transacional são agrupadas, serializadas em uma única carga útil e enviadas como uma única solicitação para o serviço Azure Cosmos DB.

O serviço recebe a solicitação e executa todas as operações dentro de um escopo transacional e retorna uma resposta usando o mesmo protocolo de serialização. Essa resposta é um sucesso ou um fracasso e fornece respostas de operação individuais por operação.

O SDK expõe a resposta para você verificar o resultado e, opcionalmente, extrair cada um dos resultados da operação interna.

Limitações

Atualmente, existem dois limites conhecidos:

• O limite de tamanho de solicitação do Azure Cosmos DB restringe o tamanho da carga útil do Lote Transacional a não exceder 2 MB e o tempo máximo de execução é de 5 segundos.
• Há um limite atual de 100 operações por lote transacional para garantir que o desempenho esteja conforme o esperado e dentro dos SLAs.

Próximos passos

• Saiba mais sobre o que você pode fazer com o TransactionalBatch

• Visite nossos exemplos para obter mais maneiras de usar nosso SDK .NET do Azure Cosmos DB