APRENDER. PRATICAR. EVOLUIR.1. Escolher a unidade de distribuição a partir do acesso
Uma base de posições pode guardar milhões de documentos e ainda concentrar a maior parte da carga num único valor de partition key. Cardinalidade elevada ajuda, mas não prova distribuição de pedidos: um fundo muito ativo pode dominar leituras e escritas. Antes de escolher a chave, descreve os pedidos críticos, os filtros disponíveis e a unidade de transação pretendida. Distingue partições lógicas, definidas pelo valor da chave, das partições físicas geridas pelo serviço. Escalar a capacidade total não corrige automaticamente uma concentração que atinge limites locais. No desenho, estima crescimento de dados e consumo de RU por chave, incluindo o fecho diário e o comportamento de retries. Uma média de utilização baixa na conta não exclui throttling num subconjunto quente.
2. Tratar alterações da chave como migração
O valor da partition key de um item não é um atributo que possas alterar no lugar através de replace. Mover um item exige criar a versão no novo valor e retirar a anterior; entre partições lógicas diferentes, essas operações não formam automaticamente uma transação única. Se uma chave baseada no owner de um fundo muda quando a responsabilidade é transferida, o desenho precisa de considerar esse ciclo de vida. Uma migração deve definir identificação estável do negócio, convivência temporária, deteção de duplicados, validação e recuperação de uma execução interrompida. Não apresentes uma alteração ao modelo de dados como simples aumento de RU. Inclui consultas, integrações e referências que ainda procurem o valor antigo antes de eliminar a cópia anterior.
3. Delimitar atomicidade antes de escolher o batch
Transactional batch agrupa operações pontuais com a mesma partition key no mesmo container. Todas concluem ou o batch reverte. Não o confundas com bulk execution, cujo objetivo é débito e não atomicidade conjunta. Num pedido que grava uma posição e o respetivo registo de controlo, a colocação dos dois itens pode permitir esse contrato local. Se estiverem em partições distintas, é necessário outro desenho de coordenação ou uma revisão da unidade transacional. Quando uma operação falha, o resultado individual dessa operação identifica a causa, enquanto outras podem apresentar 424 como dependência falhada. Um 409 numa criação pode revelar um item já existente. O diagnóstico deve encontrar a causa inicial, sem interpretar cada 424 como uma falha independente que exige repetir escritas avulsas.
4. Garantir leitura após escrita entre instâncias
Session consistency oferece garantias dentro da sessão, e o SDK acompanha session tokens associados a partições. Numa aplicação com várias instâncias, a escrita pode acontecer numa instância e a leitura seguinte noutra com um cliente diferente. Não assumes que o token foi partilhado só porque ambas usam a mesma conta Cosmos DB. Decide como manter o contexto necessário e testa o percurso real através do balanceador. O token deve ser preservado sem o interpretar ou alterar, e deve corresponder à partição relevante. Funciona como barreira mínima de versão, não como pedido de um snapshot histórico exato. Uma instância nova sem esse contexto não demonstra leitura da escrita anterior de outra instância. Se o requisito exige a versão global mais recente para todas as leituras, compara esse requisito com a garantia escolhida e com o custo de alternativas mais fortes.
5. Distinguir consistência de proteção contra lost updates
Duas equipas podem ler a mesma versão e calcular alterações diferentes. Uma leitura consistente não impede que a segunda escrita substitua o trabalho da primeira se a aplicação não verificar a versão lida. Com optimistic concurrency, a aplicação envia If-Match com o ETag observado; se já não corresponde, a operação é recusada com 412. O próximo passo depende da regra de negócio: reler, reconciliar e voltar a propor a alteração, ou apresentar o conflito para decisão. Remover If-Match para fazer o retry passar abandona a proteção pretendida. Também não deves confundir 412 com throttling 429, pois aumentar capacidade não resolve uma versão obsoleta. O modelo local demonstra este contrato com um inteiro fictício; não representa o formato real do ETag nem as políticas de conflito entre regiões.
6. Aceitar resultados de negócio e custos observados
O plano de aceitação deve combinar pedidos representativos, chaves quentes, concorrência e failover quando fizer parte do requisito. Regista consumo de RU, latência, retries, conflitos e resultado final das operações, com identificadores fictícios nos materiais de treino. Uma aplicação pode ter baixo tempo médio de resposta e falhar a confirmação de uma escrita recente quando o pedido muda de instância. Outra pode suportar o pico agregado e continuar a estrangular um único fundo. Define separadamente as evidências de distribuição, atomicidade, consistência de leitura e concorrência. Para produção, entrega ao suporte uma forma de distinguir 409, 412, 424 e 429 no contexto da operação. O objetivo é escolher a ação correta com base no contrato violado, evitando aumentar capacidade ou repetir trabalho quando o problema exige reconciliar estado.
record = {"version": 3, "position": 100}
def conditional_update(expected, new_value):
if expected != record["version"]:
return 412
record.update(version=record["version"] + 1, position=new_value)
return 200
reader_a = record["version"]
reader_b = record["version"]
assert conditional_update(reader_a, 105) == 200
assert conditional_update(reader_b, 99) == 412
assert record["position"] == 105
assert record["version"] == 4
assert conditional_update(record["version"], 103) == 200
print("five fictional version checks passed; no Cosmos DB request performed")
Caso fictício: dois operadores corrigem a mesma posição. O primeiro grava com o ETag atual. O segundo recebe 412. Em vez de remover a condição, a aplicação relê a posição, mostra o conflito e aplica a regra de reconciliação aprovada.
Armadilhas comuns
Confundir cardinalidade com distribuição real; tratar bulk como transação; perder session tokens entre instâncias; repetir uma escrita após 412 removendo a condição de versão.
Tópicos relacionados: Modelação de dados · Integração e outbox · Capacidade e observabilidade
Partição, atomicidade, consistência e concorrência são decisões relacionadas, mas cada uma precisa de um contrato próprio.
Referência: Cosmos DB partitioning · AZ-305 objectives 2026-04-17