Saída do Azure Stream Analytics para Azure Cosmos DB

A saída do Azure Cosmos DB no Azure Stream Analytics grava os resultados do processamento de fluxo como documentos JSON em um contêiner do Azure Cosmos DB. Ele suporta arquivamento de dados e consultas de baixa latência em dados JSON não estruturados. Entender como essa saída se comporta ajuda a configurá-la para a taxa de transferência, consistência e particionamento que seu cenário exige.

Conceitos básicos do Azure Cosmos DB como um destino de saída

A saída do Azure Cosmos DB no Stream Analytics grava os resultados do processamento do seu fluxo como saída JSON nos contêineres do Azure Cosmos DB. Se você não estiver familiarizado com Azure Cosmos DB, consulte a documentação do Azure Cosmos DB para começar.

O Stream Analytics conecta ao Azure Cosmos DB apenas através da API SQL. Outras APIs do Azure Cosmos DB ainda não são suportadas. Se você direcionar o Stream Analytics para contas do Azure Cosmos DB criadas com outras APIs, é possível que os dados não sejam armazenados corretamente. Quando você usar Azure Cosmos DB como saída, defina seu trabalho para o nível de compatibilidade 1.2.

O Stream Analytics não cria contêineres em seu banco de dados. Em vez disso, requer que você os crie antecipadamente. Em seguida, você pode controlar os custos de cobrança dos contêineres do Azure Cosmos DB. Também pode ajustar o desempenho, a consistência e a capacidade de seus contêineres diretamente usando as APIs do Azure Cosmos DB. As seções a seguir detalham algumas das opções de contêiner para o Azure Cosmos DB.

Ajustar a consistência, a disponibilidade e a latência

Para atender aos requisitos da sua aplicação, ajuste o banco de dados e os contêineres no Azure Cosmos DB e faça concessões entre consistência, disponibilidade, latência e throughput.

Dependendo dos níveis de consistência de leitura que seu cenário precisa em relação à latência de leitura e escrita, escolha um nível de consistência na sua conta de banco de dados. Para melhorar o throughput, aumente as Unidades de Solicitação (RUs) no contêiner. Também por padrão, o Azure Cosmos DB habilita a indexação síncrona em cada operação CRUD para seu contêiner. Essa opção é outra forma útil de controlar o desempenho de leitura e escrita no Azure Cosmos DB. Para ter mais informações, consulte o artigo Alterar o banco de dados e os níveis de consistência da consulta.

Inserções e atualizações a partir do Stream Analytics

Ao usar a integração do Stream Analytics com o Azure Cosmos DB, você pode inserir ou atualizar registros no seu container com base em uma determinada coluna de ID do Documento. Essa operação também é chamada de upsert. O Stream Analytics usa uma abordagem upsert otimista. Atualizações ocorrem somente quando uma inserção falha devido a conflito de ID do documento.

Ao usar o nível de compatibilidade 1.0, o Stream Analytics realiza essa atualização como uma operação PATCH, então suporta atualizações parciais do documento. O Stream Analytics adiciona novas propriedades ou substitui uma propriedade existente de forma incremental. Porém, as alterações nos valores das propriedades da matriz em seu documento JSON resultam em substituir toda a matriz. Ou seja, a matriz não é mesclada.

Ao usar o nível de compatibilidade 1.2, o comportamento do upsert muda para inserir ou substituir o documento. A seção mais adiante sobre o nível de compatibilidade 1.2 descreve ainda mais esse comportamento.

Se o documento JSON de entrada tiver um campo ID existente, o Azure Cosmos DB usa automaticamente esse campo como a coluna ID do Documento. A Análise de Fluxo gerencia quaisquer escritas subsequentes dessa forma, levando a uma destas situações:

• IDs exclusivas levam à inserção.
• IDs duplicadas e ID do Documento definidas para ID levam ao upsert.
• IDs duplicadas e ID do Documento não definidas levam a erros após o primeiro documento.

Se você quiser salvar todos os documentos, incluindo aqueles que têm uma ID duplicada, renomeie o campo ID em sua consulta (usando a palavra-chave AS). Permita que o Azure Cosmos DB crie o campo ID ou substitua a ID pelo valor de outra coluna (usando a palavra-chave AS ou a configuração da ID do Documento).

Particionamento de dados no Azure Cosmos DB

O Azure Cosmos DB dimensiona automaticamente as partições com base em sua carga de trabalho. Use contêineres ilimitados para particionar seus dados. Quando o Stream Analytics grava em contêineres ilimitados, ele usa tanto gravadores paralelos quanto a etapa de consulta anterior ou um esquema de particionamento de entrada.

Dependendo de sua escolha de chave de partição, você pode receber este aviso:

CosmosDB Output contains multiple rows and just one row per partition key. If the output latency is higher than expected, consider choosing a partition key that contains at least several hundred records per partition key.

Escolha uma propriedade de chave de partição que tenha muitos valores distintos e distribua sua carga de trabalho de forma uniforme entre esses valores. Como um artefato natural do particionamento, a taxa máxima de transferência de uma única partição limita solicitações que envolvem a mesma chave de partição.

O tamanho de armazenamento para documentos que pertencem ao mesmo valor de chave de partição é limitado a 20 GB (o limite de tamanho da partição física é de 50 GB). Uma chave de partição ideal é aquela que aparece frequentemente como um filtro em suas consultas e tem cardinalidade suficiente para garantir que sua solução seja escalável.

As chaves de partição usadas para consultas de Stream Analytics e para o Azure Cosmos DB não precisam ser idênticas. Para topologias totalmente paralelas, use a chave de partição de entrada, PartitionId, como chave de partição da consulta Stream Analytics, mas essa escolha pode não ser a recomendação para a chave de partição de um contêiner do Azure Cosmos DB.

Uma chave de partição também é o limite para transações em procedimentos armazenados e gatilhos para o Azure Cosmos DB. Escolha a chave de partição para que documentos que ocorrem juntos em transações compartilhem o mesmo valor da chave de partição. O artigo Particionamento no Azure Cosmos DB fornece mais detalhes sobre como escolher uma chave de partição.

Para contêineres fixos do Azure Cosmos DB, o Stream Analytics não oferece nenhuma forma de ampliar ou descarregar depois que estão cheios. Eles têm um limite superior de 10 GB e uma taxa de transferência de 10.000 RU/s. Para migrar dados de um contêiner fixo para um contêiner ilimitado (por exemplo, um com pelo menos 1.000 RU/s e uma chave de partição), use a ferramenta de migração de dados ou a biblioteca de feed de alterações.

A capacidade de gravar em múltiplos contêineres fixos está sendo descontinuada. Não use para escalar seu trabalho de Stream Analytics.

Desempenho aprimorado com nível de compatibilidade 1.2

Ao usar o nível de compatibilidade 1.2, o Stream Analytics suporta integração nativa para escrita em massa no Azure Cosmos DB. Ao usar essa integração, o Stream Analytics escreve de forma eficaz no Azure Cosmos DB, maximizando o throughput e lidando eficientemente com solicitações de limitação.

O mecanismo de gravação aprimorado está disponível em um novo nível de compatibilidade devido a uma diferença no comportamento de upsert. Ao usar níveis anteriores à 1.2, o comportamento do upsert é inserir ou mesclar o documento. Ao usar a versão 1.2, o comportamento do upsert muda para inserir ou substituir o documento.

Ao usar níveis anteriores à 1.2, o Stream Analytics utiliza um procedimento armazenado personalizado para colocar em massa documentos upsert por chave de partição no Azure Cosmos DB. Lá, o Stream Analytics escreve um lote como uma transação. Mesmo quando um único registro apresenta um erro transitório (throttling), o Stream Analytics precisa tentar todo o lote novamente. Esse comportamento torna lentos até mesmo cenários com limitação de taxa razoável.

O exemplo a seguir mostra dois trabalhos de Stream Analytics idênticos lendo da mesma entrada dos Hubs de Eventos do Azure. Ambos os trabalhos de Stream Analytics são totalmente particionados, utilizando uma consulta tipo pass-through e gravam em contêineres idênticos do Azure Cosmos DB. As métricas à esquerda são do trabalho configurado com o nível de compatibilidade 1.0. As métricas à direita são do trabalho configurado com a versão 1.2. Uma chave de partição do contêiner do Azure Cosmos DB é um GUID exclusivo proveniente do evento de entrada.

A taxa de entrada de eventos no Event Hubs é duas vezes maior do que a capacidade de ingestão configurada dos contêineres do Azure Cosmos DB (20.000 RUs), portanto, você pode esperar limitação de taxa no Azure Cosmos DB. No entanto, o trabalho com 1.2 está gravando consistentemente em uma taxa de transferência mais alta (eventos de saída por minuto) e uma menor utilização média de UA%. No seu ambiente, essa diferença depende de alguns fatores a mais. Esses fatores incluem opções do formato de evento, tamanho do evento/mensagem de entrada, chaves de partição e consulta.

Ao usar a versão 1.2, o Stream Analytics utiliza de forma mais inteligente 100% do throughput disponível no Azure Cosmos DB, com poucas reenviações por limitação de velocidade ou limitação de taxa. Esse comportamento fornece uma experiência melhor para outras cargas de trabalho, como consultas em execução no contêiner ao mesmo tempo. Se você quiser ver como o Stream Analytics é escalado horizontalmente com o Azure Cosmos DB como um coletor de 1.000 a 10.000 mensagens por segundo, experimente este projeto de exemplo do Azure.

A taxa de transferência da saída do Azure Cosmos DB é a mesma ao usar as versões 1.0 e 1.1. É altamente recomendável que você use o nível de compatibilidade 1.2 no Stream Analytics com o Azure Cosmos DB.

Configurações do Azure Cosmos DB para a saída em JSON

Quando você configura o Azure Cosmos DB como uma saída no Stream Analytics, as seguintes propriedades definem a saída.

Depois de configurar a saída do Azure Cosmos DB, você pode usá-la na consulta como o destino de uma na instrução INTO. Quando você usa uma saída do Azure Cosmos DB dessa forma, precisa definir explicitamente uma chave de partição.

O registro da saída deve conter uma coluna que diferencia maiúsculas de minúsculas, denominada segundo a chave de partição no Azure Cosmos DB. Para ter maior paralelização, a instrução pode exigir uma cláusula PARTITION BY que usa a mesma coluna.

Aqui está um exemplo de consulta:

    SELECT TollBoothId, PartitionId
    INTO CosmosDBOutput
    FROM Input1 PARTITION BY PartitionId

Tratamento de erros e novas tentativas

Se ocorrer uma falha transitória, indisponibilidade de serviço ou limitação enquanto o Stream Analytics estiver enviando eventos para o Azure Cosmos DB, o Stream Analytics fará novas tentativas indefinidamente para concluir a operação com êxito. Mas ele não tenta novamente em caso de falhas Unauthorized (código de erro HTTP 401), NotFound (código de erro HTTP 404), Forbidden (código de erro HTTP 403) ou BadRequest (código de erro HTTP 400).

Problemas comuns que causam falha na saída do Azure Cosmos DB

Várias condições podem causar falha na saída do Azure Cosmos DB. Os dados de saída do Stream Analytics podem violar uma restrição única de índice no contêiner, a PartitionKey coluna pode não existir, ou a Id coluna pode não existir. Para mais informações sobre restrições de índice único, veja Restrições de chave únicas no Azure Cosmos DB.

Conteúdo relacionado

• Entender as saídas do Azure Stream Analytics
• Saída do Azure Stream Analytics para o Banco de Dados SQL do Azure
• Particionamento personalizado da saída de blob do Azure Stream Analytics