Azure Cosmos DB v2 (Beta)

  • Artigo

Resumo

Item Descrição
Estado da liberação Beta
Produtos Power BI (Modelos semânticos)
Power BI (Fluxos de dados)
Malha (fluxo de dados Gen2)
Tipos de autenticação compatíveis Tecla de Feed

Pré-requisitos

Funcionalidades com suporte

  • Importação
  • DirectQuery (Modelos semânticos do Power BI)
  • Opções avançadas
    • Número de repetições
    • Habilitar transmissão da função "AVERAGE"
    • Habilitar transmissão "SORT" para várias colunas

Conectar ao Azure Cosmos DB

Para se conectar aos dados do Azure Cosmos DB:

  1. Inicie o Power BI Desktop.

  2. Na guia Página Inicial, selecione Obter Dados.

  3. Na caixa de pesquisa, insira Cosmos DB v2.

  4. Selecione Azure Cosmos DB v2 (Beta) e depois Conectar.

    Captura de tela mostrando a opção Selecionar o Azure Cosmos DB v2.

  5. Na página de conexão do Azure Cosmos DB v2, de Ponto de extremidade do Cosmos, insira o URI da conta do Azure Cosmos DB que você deseja usar. Para o modo de Conectividade de Dados, escolha um modo apropriado para seu caso de uso, seguindo estas diretrizes gerais:

    • Para conjuntos de dados menores, selecione Importar. Ao usar o modo de importação, o Power BI trabalha com o Cosmos DB para importar o conteúdo de todo o conjunto de dados para uso em suas visualizações.

    • O modo DirectQuery habilita o pushdown de consulta para o contêiner do Cosmos DB para execução e melhora o desempenho do conector. Para contêineres do Cosmos DB particionados, uma consulta SQL com uma função agregada será transmitida ao Cosmos DB se a consulta também contiver um filtro (cláusula WHERE) na chave de partição. Por exemplo, se a chave de partição for definida como "Produto", uma consulta SQL que pode ser transmitida e executada no servidor Cosmos DB pode ser:

      SELECT SUM(ColumnName) FROM TableName where Product = 'SampleValue'

    Observação

    Use o Link do Azure Synapse para Azure Cosmos DB se você quiser executar funções agregadas particionadas cruzadas no contêiner do Cosmos DB.

    Para obter mais informações:

    Captura de tela da caixa de diálogo de conexão mostrando a entrada do Ponto de Extremidade do Cosmos e o modo Conectividade de dados definido como DirectQuery.

  6. No prompt para configurar a autenticação da fonte de dados, insira a chave da conta. Depois, selecione Conectar. Seu catálogo de dados, bancos de dados e tabelas aparecem na caixa de diálogo Navegador.

  7. No painel Opções de Exibição, marque a caixa de seleção para o conjunto de dados que você quer usar.

    Captura de tela do navegador enfatizando os dados que você selecionou.

  8. A melhor maneira de especificar o filtro da chave de partição (para que as funções agregadas possam ser enviadas para o Cosmos DB) é usar os parâmetros M dinâmicos. Para usar parâmetros M dinâmicos, você precisa criar um conjunto de dados com valores de chave de partição exclusivos, criar um parâmetro, adicioná-lo como filtro no conjunto de dados principal, vinculá-lo ao conjunto de dados da chave de partição exclusivo e usá-lo como uma segmentação de dados para o conjunto de dados principal. Use as etapas a seguir para habilitar parâmetros M dinâmicos para filtragem de chave de partição.

    a. Crie um conjunto de dados com valores da chave de partição exclusivos:

    No Navegador, selecione Transformar dados em vez de Carregar para abrir o editor do Power Query. Clique com o botão direito do mouse no conjunto de dados de consultas e selecione Duplicar para criar um conjunto de dados.

    Captura de tela mostrando como selecionar duplicatas de sua consulta existente no editor do Power Query.

    Renomeie o novo modelo da chave de partição e clique com o botão direito do mouse na coluna de chave de partição do Cosmos DB. Neste exemplo, Produto é a coluna Chave de partição do Cosmos DB. Selecione Remover Outras Colunas e depois Remover Duplicatas.

    Captura de tela mostrando as chaves de partição exclusivas no editor do Power Query.

    b. Crie um parâmetro para filtragem dinâmica:

    No editor do Power Query, selecione Gerenciar Parâmetros>Novo parâmetro. Renomeie o novo parâmetro para refletir o parâmetro de filtro e insira um valor válido como Valor Atual.

    Captura de tela mostrando como criar um parâmetro no editor do Power Query.

    c. Aplique o filtro parametrizado no conjunto de dados principal:

    Selecione o ícone suspenso da coluna Chave de partição e selecione Filtros de Texto>É igual a. Altere o tipo de filtro de Texto para Parâmetro. Em seguida, escolha o parâmetro que foi criado na etapa b. Selecione Fechar e Aplicar no canto superior esquerdo do editor do Power Query.

    Captura de tela mostrando as etapas para aplicar o filtro parametrizado.

    d. Crie uma segmentação de valores de chave de partição com vinculação de parâmetro:

    No Power BI, selecione a guia Modelo. Depois, selecione o campo Chave de partição. No painel Propriedades, selecione Avançado>Associar ao parâmetro. Escolha o parâmetro que foi criado na etapa b.

    Captura de tela mostrando as etapas de associação do parâmetro.

    Selecione a guia Relatório e adicione uma segmentação com a chave de partição exclusiva.

    Captura de tela do segmentador.

    e. Adicione visualizações e aplique o filtro da chave de partição da segmentação de dados:

    Como o valor da chave de partição escolhida na segmentação de dados está vinculado ao parâmetro (conforme feito na etapa d) e o filtro parametrizado é aplicado no conjunto de dados principal (como feito na etapa c), o valor da chave de partição escolhida será aplicado como um filtro no conjunto de dados principal e a consulta com o filtro de chave de partição será transmitida ao Cosmos DB em todas as visualizações.

    Captura de tela da visualização após a partição do filtro principal.

Opções avançadas

O Power Query tem um conjunto de opções avançadas que você pode adicionar à sua consulta, se necessário.

A tabela a seguir lista todas as opções avançadas que você pode definir no Power Query.

Opção avançada Descrição
Número de repetições Quantidade de tentativas se houver códigos de retorno HTTP de 408 - Request Timeout, 412 - Precondition Failed ou 429 - Too Many Requests. O número padrão de novas tentativas é 5.
Habilitar transmissão da função AVERAGE Especifica se o conector permite a transmissão da função agregada do AVG para o Cosmos DB. O valor padrão é 1 e o conector tenta transmitir a função agregada do AVG para o Cosmos DB, por padrão. Se o argumento contiver valores de string, booleanos ou nulos para a função agregada do AVG, um conjunto de resultados indefinido será retornado pelo servidor Cosmos DB. Quando definida com o valor 0, a função agregada do AVG não é transmitida ao servidor Cosmos DB e o conector realiza a própria operação de agregação do AVG.
Habilitar transmissão SORT para várias colunas Especifica se o conector permite que várias colunas sejam transmitidas ao Cosmos DB quando especificado na cláusula ORDER BY da consulta SQL. O valor padrão é 0 e se mais de uma coluna for especificada na cláusula ORDER BY, o conector não transmite as colunas por padrão e, em vez disso, executa a ordem sozinho. Quando definido com o valor 1, o conector tenta transmitir várias colunas para o Cosmos DB quando especificado na cláusula ORDER BY da consulta SQL. Para permitir que várias colunas sejam transmitidas ao Cosmos DB, verifique se há índices compostos definidos nas colunas nas respectivas coleções. Para coleções particionadas, uma consulta SQL com ORDER BY será transmitida ao Cosmos DB somente se a consulta contiver um filtro na chave particionada. Além disso, se houver mais de oito colunas especificadas na cláusula ORDER BY, o conector não transmitirá a cláusula ORDER BY e, em vez disso, tratará a própria execução da ordem.

Limitações e problemas conhecidos

  • Para contêineres do Cosmos DB particionados, uma consulta SQL com uma função agregada será transmitida ao Cosmos DB se a consulta também contiver um filtro (cláusula WHERE) na chave de partição. Se a consulta agregada não contiver um filtro na chave de partição, a agregação será realizada pelo conector.

  • O conector não transmite uma função agregada se for chamado após a aplicação de TOP ou LIMIT. O Cosmos DB processa a operação TOP no final ao processar uma consulta. Por exemplo, na consulta a seguir, TOP é aplicado na subconsulta, enquanto a função agregada é aplicada sobre esse conjunto de resultados:

    SELECT COUNT(1) FROM (SELECT TOP 4 * FROM EMP) E

  • Se DISTINCT for fornecido em uma função agregada, o conector não transmite a função agregada para o Cosmos DB se uma cláusula DISTINCT for fornecida em uma função agregada. Quando presente em uma função agregada, DISTINCT não é compatível com a API SQL do Cosmos DB.

  • Para a função agregada SUM, o Cosmos DB retorna indefinido como o conjunto de resultados se algum dos argumentos em SUM for string, booliano ou nulo. Contudo, se existirem valores nulos, o conector transmite a consulta para o Cosmos DB de modo a solicitar à fonte de dados que substitua um valor nulo por zero como parte do cálculo SUM.

  • Para a função agregada AVG, o Cosmos DB retorna indefinido como o conjunto de resultados se algum dos argumentos em SUM for string, booliano ou nulo. O conector expõe uma propriedade de conexão para desabilitar a transmissão da função agregada do AVG para o Cosmos DB caso esse comportamento padrão do Cosmos DB precise ser substituído. Quando a transmissão do AVG está desabilitada, ela não é transmitida ao Cosmos DB e o conector realiza a própria operação de agregação do AVG. Para obter mais informações, acesse "Habilitar transmissão da função AVERAGE" em Opções avançadas.

  • Atualmente, não há suporte para contêineres do Azure Cosmos DB com chave de partição grande no conector.

  • A transmissão de agregação está desabilitada para a seguinte sintaxe por limitações do servidor:

    • Quando a consulta não está filtrando uma chave de partição ou quando o filtro de chave de partição usa o operador OR com outro predicado no nível superior na cláusula WHERE.

    • Quando a consulta tem uma ou mais chaves de partição, elas aparecem em uma cláusula IS NOT NULL na cláusula WHERE.

  • O conector V2 não oferece suporte a tipos de dados complexos, como matrizes, objetos e estruturas hierárquicas. Para cenários como esse, recomendamos utilizar o recurso Espelhamento de malha para o Azure Cosmos DB.

  • O conector V2 usa a amostragem dos primeiros 1.000 documentos para criar o esquema inferido. Seu uso não é recomendado para cenários de evolução de esquema quando apenas parte dos documentos é atualizada. Por exemplo, uma propriedade recém-adicionada a um documento em um contêiner com milhares de documentos pode não ser incluída no esquema inferido. Para cenários como esse, recomendamos utilizar o recurso Espelhamento de malha para o Azure Cosmos DB.

  • No momento, o conector V2 não oferece suporte a valores que não são de sequências nas propriedades do objeto.

  • A transmissão de filtro está desabilitada para a seguinte sintaxe devido a limitações do servidor:

    • Quando a consulta contendo uma ou mais colunas agregadas é referenciada na cláusula WHERE.