Operações em lotes transacionais no Azure Cosmos DB

APLICA-SE A: NoSQL

O lote transacional descreve um grupo de operações de ponto que precisam ou 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 são bem-sucedidas na ordem em que são descritas na operação de lote transacional, a transação é confirmada. No entanto, se qualquer 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 realizadas 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 feitas dentro de uma transação sejam tratadas como uma unidade: ou todas elas são confirmadas, ou nenhuma o é.
• A consistência assegura que os dados estejam sempre em um estado válido entre as transações.
• O isolamento garante que duas transações não interfiram uma com a outra - muitos sistemas comerciais fornecem vários níveis de isolamento que podem ser usados com base nas necessidades de cada aplicativo.
• A durabilidade cuida para que qualquer alteração confirmada em um banco de dados esteja sempre presente. O Azure Cosmos DB dá suporte a transações totalmente conformes a ACID com isolamento de instantâneo para operações dentro da mesma chave de partição lógica.

Operações transacionais em lote e procedimentos armazenados

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

• Opção de linguagem - o lote transacional tem suporte no SDK e na linguagem com a qual você já trabalha, ao passo que os procedimentos armazenados precisam ser escritos em JavaScript.
• Controle de versão de código - Codificar o aplicativo de controle de versão e integrá-lo ao pipeline de CI/CD é muito mais natural do que orquestrar a atualização de um procedimento armazenado e garantir que a sobreposição ocorra no momento certo. Isso também facilita a reversão de alterações.
• Desempenho - latência reduzida de até 30% em operações equivalentes quando comparada com a execução do procedimento armazenado.
• Serialização de conteúdo: cada operação em um lote transacional pode usar as opções de serialização personalizada para o payload.

Como criar uma operação transacional em lote

.NET

Ao criar uma operação transacional em lote, 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);

Por fim, chame ExecuteAsync no lote:

using TransactionalBatchResponse response = await batch.ExecuteAsync();

Ao receber a resposta, examine se ela foi bem-sucedida. Se ela tiver sido, 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á o código de status do respectivo erro. Todas as outras operações terão um código de status 424 (dependência com falha). Se a operação falhar porque ela tenta criar um item que já existe, um código de status 409 (conflito) será retornado. O código de status permite que se identifique a causa da falha da transação.

Java

Ao criar uma operação transacional em lote, 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);

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

CosmosBatchResponse response = container.executeCosmosBatch(batch);

Ao receber a resposta, examine se ela foi bem-sucedida. Se ela tiver sido, extraia os resultados:

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

Importante

Se houver uma falha, a operação com falha terá o código de status do respectivo erro. Todas as outras operações terão um código de status 424 (dependência com falha). Se a operação falhar porque ela tenta criar um item que já existe, um código de status 409 (conflito) será retornado. O código de status permite que se identifique 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='/road_bikes'))

No Python, as operações em Lotes Transacionais são muito semelhantes às APIs de operações singulares e são tuplas que contêm (operation_type_string, args_tuple, batch_operation_kwargs_dictionary). Veja abaixo os itens de exemplo que serão usados para demonstrar a funcionalidade de operações em lotes:

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
    ]

Por fim, 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]

Observação para usar a operação de patch e a operação de replace_if_match_etag no lote
O dicionário kwargs de operação em lotes é limitado e usa apenas um total de três valores de chave diferentes. Se você quiser usar patch condicional dentro do lote, o uso da chave filter_predicate está disponível para a operação de patch ou, se você quiser 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á o código de status do respectivo erro. Todas as outras operações terão um código de status 424 (dependência com falha). Se a operação falhar porque ela tenta criar um item que já existe, um código de status 409 (conflito) será retornado. O código de status permite que se identifique a causa da falha da transação.

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

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

O serviço recebe a solicitação e executa todas as operações dentro de um escopo transacional, usando o mesmo protocolo de serialização para retornar uma resposta. Essa resposta pode ser um êxito ou uma falha. Ela fornece respostas de operação individuais por operação.

O SDK expõe a resposta para que você verifique o resultado e, opcionalmente, extrai cada um dos resultados de operação internos.

Limitações

Atualmente, há dois limites conhecidos:

• O tamanho do limite de solicitação do Azure Cosmos DB restringe o tamanho do payload do Lote Transacional a 2 MB e o tempo máximo de execução a 5 segundos.
• Há um limite atual de 100 operações por Lote Transacional para garantir que o desempenho seja o esperado e esteja dentro dos SLAs.

Próximas etapas

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

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