Consultar dados do Azure Cosmos DB com um pool SQL sem servidor no Azure Synapse Link

Um pool SQL sem servidor permite que você analise dados em seus contêineres do Azure Cosmos DB habilitados com o Azure Synapse Link quase em tempo real sem afetar o desempenho de suas cargas de trabalho transacionais. Ele oferece uma sintaxe T-SQL familiar para consultar dados do repositório analítico e conectividade integrada a uma ampla gama de business intelligence (BI) e ferramentas de consulta ad-hoc por meio da interface T-SQL.

Para consultar o Azure Cosmos DB, a área de superfície SELECT completa é suportada por meio da função OPENROWSET, que inclui a maioria das funções e operadores SQL. Você também pode armazenar resultados da consulta que lê dados do Azure Cosmos DB junto com dados no Armazenamento de Blobs do Azure ou no Armazenamento do Azure Data Lake usando criar tabela externa como selecionar (CETAS). Atualmente, não é possível armazenar resultados de consulta de pool SQL sem servidor no Azure Cosmos DB usando o CETAS.

Neste artigo, você aprenderá a escrever uma consulta com um pool SQL sem servidor que consultará dados de contêineres do Azure Cosmos DB habilitados com o Azure Synapse Link. Em seguida, você pode saber mais sobre como criar exibições de pool SQL sem servidor em contêineres do Azure Cosmos DB e conectá-las a modelos do Power BI neste tutorial. Este tutorial usa um contêiner com um esquema bem definido do Azure Cosmos DB. Você também pode conferir o módulo Learn sobre como consultar o Azure Cosmos DB com o SQL Serverless para o Azure Synapse Analytics

Pré-requisitos

  • Certifique-se de que preparou a Loja analítica:
  • Certifique-se de que aplicou todas as práticas recomendadas, tais como:
    • Verifique se o armazenamento analítico do Azure Cosmos DB está na mesma região do pool SQL sem servidor.
    • Verifique se o aplicativo cliente (Power BI, serviço de análise) está na mesma região do pool SQL sem servidor.
    • Se você estiver retornando uma grande quantidade de dados (maior que 80 GB), considere usar a camada de cache, como o Analysis Services, e carregar as partições menores que 80 GB no modelo do Analysis Services.
    • Se você estiver filtrando dados usando colunas de cadeia de caracteres, certifique-se de que está usando a função com a cláusula explícita WITH que tem os menores tipos possíveis (por exemplo, não use VARCHAR(1000) se souber que a OPENROWSET propriedade tem até 5 caracteres).

Descrição geral

O pool SQL sem servidor permite que você consulte o armazenamento analítico do Azure Cosmos DB usando OPENROWSET a função.

  • OPENROWSET com chave embutida. Essa sintaxe pode ser usada para consultar coleções do Azure Cosmos DB sem a necessidade de preparar credenciais.
  • OPENROWSET essa credencial referenciada que contém a chave de conta do Azure Cosmos DB. Essa sintaxe pode ser usada para criar exibições em coleções do Azure Cosmos DB.

Para dar suporte à consulta e análise de dados em um repositório analítico do Azure Cosmos DB, um pool SQL sem servidor é usado. O pool SQL sem servidor usa a OPENROWSET sintaxe SQL, portanto, você deve primeiro converter sua cadeia de conexão do Azure Cosmos DB para este formato:

OPENROWSET( 
       'CosmosDB',
       '<SQL connection string for Azure Cosmos DB>',
       <Container name>
    )  [ < with clause > ] AS alias

A cadeia de conexão SQL para o Azure Cosmos DB especifica o nome da conta do Azure Cosmos DB, o nome do banco de dados, a chave mestra da conta do banco de dados e um nome de região opcional para a OPENROWSET função. Algumas dessas informações podem ser extraídas da cadeia de conexão padrão do Azure Cosmos DB.

Convertendo do formato de cadeia de conexão padrão do Azure Cosmos DB:

AccountEndpoint=https://<database account name>.documents.azure.com:443/;AccountKey=<database account master key>;

A cadeia de conexão SQL tem o seguinte formato:

'account=<database account name>;database=<database name>;region=<region name>;key=<database account master key>'

A região é opcional. Se omitida, a região primária do contêiner é usada.

Importante

Há outro parâmetro opcional na cadeia de conexão chamado endpoint. O endpoint param é necessário para contas que não correspondem ao formato padrão *.documents.azure.com . Por exemplo, se sua conta do Azure CosmosDB terminar com .documents.azure.us, certifique-se de adicionar endpoint=<account name>.documents.azure.us a cadeia de conexão.

O nome do contêiner do Azure Cosmos DB é especificado sem aspas OPENROWSET na sintaxe. Se o nome do contêiner tiver caracteres especiais, por exemplo, um traço (-), o nome deverá ser colocado entre colchetes ([]) na OPENROWSET sintaxe.

Importante

Certifique-se de que você está usando algum agrupamento de banco de dados UTF-8, por exemplo, Latin1_General_100_CI_AS_SC_UTF8porque os valores de cadeia de caracteres em um repositório analítico do Azure Cosmos DB são codificados como texto UTF-8. Uma incompatibilidade entre a codificação de texto no arquivo e o agrupamento pode causar erros inesperados de conversão de texto. Você pode alterar facilmente o agrupamento padrão do banco de dados atual usando a instrução alter database current collate Latin1_General_100_CI_AI_SC_UTF8T-SQL .

Nota

Um pool SQL sem servidor não oferece suporte à consulta de um repositório transacional do Azure Cosmos DB.

Conjunto de dados de exemplo

Os exemplos neste artigo baseiam-se em dados do Centro Europeu de Prevenção e Controlo das Doenças (ECDC) COVID-19 Cases and COVID-19 Open Research Dataset (CORD-19), doi:10.5281/zenodo.3715505.

Você pode ver a licença e a estrutura dos dados nessas páginas. Também pode transferir dados de exemplo para os conjuntos de dados ECDC e CORD-19.

Para acompanhar este artigo mostrando como consultar dados do Azure Cosmos DB com um pool SQL sem servidor, certifique-se de criar os seguintes recursos:

  • Uma conta de banco de dados do Azure Cosmos DB habilitada para o Azure Synapse Link.
  • Um banco de dados do Azure Cosmos DB chamado covid.
  • Dois contêineres do Azure Cosmos DB nomeados Ecdc e Cord19 carregados com os conjuntos de dados de exemplo anteriores.

Você pode usar a seguinte cadeia de conexão para fins de teste: Account=synapselink-cosmosdb-sqlsample;Database=covid;Key=s5zarR2pT0JWH9k8roipnWxUYBegOuFGjJpSjGlR36y86cW0GQ6RaaG8kGjsRAQoWMw1QKTkkX8HQtFpJjC8Hg==. Observe que essa conexão não garantirá o desempenho porque essa conta pode estar localizada em uma região remota em comparação com seu ponto de extremidade Synapse SQL.

Explore os dados do Azure Cosmos DB com inferência automática de esquema

A maneira mais fácil de explorar dados no Azure Cosmos DB é usando o recurso de inferência automática de esquema. Ao omitir a WITHOPENROWSET cláusula da instrução, você pode instruir o pool SQL sem servidor a detetar automaticamente (inferir) o esquema do repositório analítico do contêiner do Azure Cosmos DB.

SELECT TOP 10 *
FROM OPENROWSET( 
       'CosmosDB',
       'Account=synapselink-cosmosdb-sqlsample;Database=covid;Key=s5zarR2pT0JWH9k8roipnWxUYBegOuFGjJpSjGlR36y86cW0GQ6RaaG8kGjsRAQoWMw1QKTkkX8HQtFpJjC8Hg==',
       Ecdc) as documents

No exemplo anterior, instruímos o pool SQL sem servidor a se conectar ao covid banco de dados na conta MyCosmosDbAccount do Azure Cosmos DB autenticada usando a chave do Azure Cosmos DB (o manequim no exemplo anterior). Em seguida, acessamos a Ecdc loja analítica do contêiner na West US 2 região. Como não há projeção de propriedades específicas, a OPENROWSET função retornará todas as propriedades dos itens do Azure Cosmos DB.

Supondo que os itens no contêiner do Azure Cosmos DB tenham date_rep, e geo_id propriedades, casesos resultados dessa consulta são mostrados na tabela a seguir:

date_rep cases geo_id
2020-08-13 254 RS
2020-08-12 235 RS
2020-08-11 163 RS

Se precisar explorar dados do outro contêiner no mesmo banco de dados do Azure Cosmos DB, você poderá usar a mesma cadeia de conexão e fazer referência ao contêiner necessário como o terceiro parâmetro:

SELECT TOP 10 *
FROM OPENROWSET( 
       'CosmosDB',
       'Account=synapselink-cosmosdb-sqlsample;Database=covid;Key=s5zarR2pT0JWH9k8roipnWxUYBegOuFGjJpSjGlR36y86cW0GQ6RaaG8kGjsRAQoWMw1QKTkkX8HQtFpJjC8Hg==',
       Cord19) as cord19

Especificar explicitamente o esquema

Embora o recurso de inferência automática de esquema forneça OPENROWSET uma consulta simples e fácil de usar, seus cenários de negócios podem exigir que você especifique explicitamente o esquema para propriedades relevantes somente leitura dos dados do Azure Cosmos DB.

A OPENROWSET função permite especificar explicitamente quais propriedades você deseja ler dos dados no contêiner e especificar seus tipos de dados.

Vamos imaginar que importamos alguns dados do conjunto de dados ECDC COVID com a seguinte estrutura para o Azure Cosmos DB:

{"date_rep":"2020-08-13","cases":254,"countries_and_territories":"Serbia","geo_id":"RS"}
{"date_rep":"2020-08-12","cases":235,"countries_and_territories":"Serbia","geo_id":"RS"}
{"date_rep":"2020-08-11","cases":163,"countries_and_territories":"Serbia","geo_id":"RS"}

Esses documentos JSON simples no Azure Cosmos DB podem ser representados como um conjunto de linhas e colunas no Synapse SQL. A OPENROWSET função permite especificar um subconjunto de propriedades que você deseja ler e os tipos exatos de coluna na WITH cláusula:

SELECT TOP 10 *
FROM OPENROWSET(
      'CosmosDB',
      'Account=synapselink-cosmosdb-sqlsample;Database=covid;Key=s5zarR2pT0JWH9k8roipnWxUYBegOuFGjJpSjGlR36y86cW0GQ6RaaG8kGjsRAQoWMw1QKTkkX8HQtFpJjC8Hg==',
       Ecdc
    ) with ( date_rep varchar(20), cases bigint, geo_id varchar(6) ) as rows

O resultado dessa consulta pode se parecer com a tabela a seguir:

date_rep cases geo_id
2020-08-13 254 RS
2020-08-12 235 RS
2020-08-11 163 RS

Para obter mais informações sobre os tipos SQL que devem ser usados para valores do Azure Cosmos DB, consulte as regras para mapeamentos de tipo SQL no final do artigo.

Criar vista

A criação de modos de exibição nos master bancos de dados padrão não é recomendada ou suportada. Portanto, você precisa criar um banco de dados de usuários para suas visualizações.

Depois de identificar o esquema, você pode preparar uma exibição sobre seus dados do Azure Cosmos DB. Você deve colocar sua chave de conta do Azure Cosmos DB em uma credencial separada e fazer referência a essa credencial da OPENROWSET função. Não guarde a chave da sua conta na definição de vista.

CREATE CREDENTIAL MyCosmosDbAccountCredential
WITH IDENTITY = 'SHARED ACCESS SIGNATURE', SECRET = 's5zarR2pT0JWH9k8roipnWxUYBegOuFGjJpSjGlR36y86cW0GQ6RaaG8kGjsRAQoWMw1QKTkkX8HQtFpJjC8Hg==';
GO
CREATE OR ALTER VIEW Ecdc
AS SELECT *
FROM OPENROWSET(
      PROVIDER = 'CosmosDB',
      CONNECTION = 'Account=synapselink-cosmosdb-sqlsample;Database=covid',
      OBJECT = 'Ecdc',
      SERVER_CREDENTIAL = 'MyCosmosDbAccountCredential'
    ) with ( date_rep varchar(20), cases bigint, geo_id varchar(6) ) as rows

Não use OPENROWSET sem esquema explicitamente definido, pois isso pode afetar seu desempenho. Certifique-se de usar os menores tamanhos possíveis para suas colunas (por exemplo, VARCHAR(100) em vez do padrão VARCHAR(8000)). Você deve usar algum agrupamento UTF-8 como agrupamento de banco de dados padrão ou defini-lo como agrupamento de coluna explícito para evitar problemas de conversão UTF-8. O agrupamento fornece o melhor desempenho quando você filtra Latin1_General_100_BIN2_UTF8 dados usando algumas colunas de cadeia de caracteres.

Ao consultar o modo de exibição, você pode encontrar erros ou resultados inesperados. Isso provavelmente significa que o modo de exibição faz referência a colunas ou objetos que foram modificados ou não existem mais. Você precisa ajustar manualmente a definição de exibição para alinhar com as alterações de esquema subjacentes. Tenha em mente que isso pode acontecer ao usar a inferência automática de esquema na exibição e ao especificar explicitamente o esquema.

Consultar objetos aninhados

Com o Azure Cosmos DB, você pode representar modelos de dados mais complexos compondo-os como objetos aninhados ou matrizes. O recurso de sincronização automática do Azure Synapse Link for Azure Cosmos DB gerencia a representação de esquema no repositório analítico pronta para uso, o que inclui o tratamento de tipos de dados aninhados que permitem consultas avançadas do pool SQL sem servidor.

Por exemplo, o conjunto de dados CORD-19 tem documentos JSON que seguem esta estrutura:

{
    "paper_id": <str>,                   # 40-character sha1 of the PDF
    "metadata": {
        "title": <str>,
        "authors": <array of objects>    # list of author dicts, in order
        ...
     }
     ...
}

Os objetos aninhados e matrizes no Azure Cosmos DB são representados como cadeias de caracteres JSON no resultado da consulta quando a OPENROWSET função os lê. Você pode especificar os caminhos para valores aninhados nos objetos ao usar a WITH cláusula:

SELECT TOP 10 *
FROM OPENROWSET( 
       'CosmosDB',
       'Account=synapselink-cosmosdb-sqlsample;Database=covid;Key=s5zarR2pT0JWH9k8roipnWxUYBegOuFGjJpSjGlR36y86cW0GQ6RaaG8kGjsRAQoWMw1QKTkkX8HQtFpJjC8Hg==',
       Cord19)
WITH (  paper_id    varchar(8000),
        title        varchar(1000) '$.metadata.title',
        metadata     varchar(max),
        authors      varchar(max) '$.metadata.authors'
) AS docs;

O resultado dessa consulta pode se parecer com a tabela a seguir:

paper_id cargo do IdP Autores
BB11206963E831F... Informações Complementares Uma eco-epidemi... {"title":"Supplementary Informati… [{"first":"Julien","last":"Mélade","suffix":"","af…
BB1206963E831F1... O uso de soros convalescentes em doenças imunológicas... {"title":"The Use of Convalescent… [{"first":"Antonio","last":"Lavazza","suffix":"", …
bb378eca9aac649... Tylosema esculentum (Marama) Tuber e B... {"title":"Tylosema esculentum (Ma… [{"first":"Walter","last":"Chingwaru","suffix":"",…

Saiba mais sobre como analisar tipos de dados complexos, como arquivos Parquet e contêineres no Azure Synapse Link para Azure Cosmos DB ou estruturas aninhadas em um pool SQL sem servidor.

Importante

Se você vir caracteres inesperados em seu texto como em vez de , então o agrupamento do banco de dados não está definido como MÃÂ&copy;ladeagrupamento UTF-8.Mélade Altere o agrupamento do banco de dados para agrupamento UTF-8 usando uma instrução SQL como ALTER DATABASE MyLdw COLLATE LATIN1_GENERAL_100_CI_AS_SC_UTF8.

Nivelar matrizes aninhadas

Os dados do Azure Cosmos DB podem ter submatrizes aninhadas como a matriz do autor de um conjunto de dados CORD-19 :

{
    "paper_id": <str>,                      # 40-character sha1 of the PDF
    "metadata": {
        "title": <str>,
        "authors": [                        # list of author dicts, in order
            {
                "first": <str>,
                "middle": <list of str>,
                "last": <str>,
                "suffix": <str>,
                "affiliation": <dict>,
                "email": <str>
            },
            ...
        ],
        ...
}

Em alguns casos, talvez seja necessário "unir" as propriedades do item superior (metadados) com todos os elementos da matriz (autores). Um pool SQL sem servidor permite nivelar estruturas aninhadas aplicando a OPENJSON função na matriz aninhada:

SELECT
    *
FROM
    OPENROWSET(
      'CosmosDB',
      'Account=synapselink-cosmosdb-sqlsample;Database=covid;Key=s5zarR2pT0JWH9k8roipnWxUYBegOuFGjJpSjGlR36y86cW0GQ6RaaG8kGjsRAQoWMw1QKTkkX8HQtFpJjC8Hg==',
       Cord19
    ) WITH ( title varchar(1000) '$.metadata.title',
             authors varchar(max) '$.metadata.authors' ) AS docs
      CROSS APPLY OPENJSON ( authors )
                  WITH (
                       first varchar(50),
                       last varchar(50),
                       affiliation nvarchar(max) as json
                  ) AS a

O resultado dessa consulta pode se parecer com a tabela a seguir:

cargo Autores Primeiro Último Afiliação
Informações Complementares Uma eco-epidemi... [{"first":"Julien","last":"Mélade","suffix":"","affiliation":{"laboratory":"Centre de Recher… Julien Mélade {"laboratory":"Centre de Recher…
Informações Complementares Uma eco-epidemi... [{"first":"Nicolas","last":"4#","suffix":"","affiliation":{"laboratory":"","institution":"U… Nicolas N.º 4 {"laboratory":"","institution":"U…
Informações Complementares Uma eco-epidemi... [{"first":"Beza","last":"Ramazindrazana","suffix":"","affiliation":{"laboratory":"Centre de Recher… Beza Ramazindrazana {"laboratory":"Centre de Recher…
Informações Complementares Uma eco-epidemi... [{"first":"Olivier","last":"Flores","suffix":"","affiliation":{"laboratory":"UMR C53 CIRAD, … Olivier Flores {"laboratory":"UMR C53 CIRAD, …

Importante

Se você vir caracteres inesperados em seu texto como em vez de , então o agrupamento do banco de dados não está definido como MÃÂ&copy;ladeagrupamento UTF-8.Mélade Altere o agrupamento do banco de dados para agrupamento UTF-8 usando uma instrução SQL como ALTER DATABASE MyLdw COLLATE LATIN1_GENERAL_100_CI_AS_SC_UTF8.

Mapeamentos do tipo Azure Cosmos DB para SQL

Embora o repositório transacional do Azure Cosmos DB seja independente do esquema, o repositório analítico é esquematizado para otimizar o desempenho da consulta analítica. Com o recurso de sincronização automática do Azure Synapse Link, o Azure Cosmos DB gerencia a representação de esquema no repositório analítico pronta para uso, o que inclui o tratamento de tipos de dados aninhados. Como um pool SQL sem servidor consulta o repositório analítico, é importante entender como mapear tipos de dados de entrada do Azure Cosmos DB para tipos de dados SQL.

As contas do Azure Cosmos DB da API SQL (Core) suportam tipos de propriedade JSON de número, cadeia de caracteres, booleano, nulo, objeto aninhado ou matriz. Você precisaria escolher tipos SQL que correspondam a esses tipos JSON se estiver usando a WITH cláusula em OPENROWSET. A tabela a seguir mostra os tipos de coluna SQL que devem ser usados para diferentes tipos de propriedade no Azure Cosmos DB.

Tipo de propriedade do Azure Cosmos DB Tipo de coluna SQL
Boolean bit
Número inteiro bigint
Decimal flutuante
String varchar (agrupamento de banco de dados UTF-8)
Data e hora (cadeia de caracteres formatada em ISO) Varchar(30)
Data e hora (carimbo de data/hora UNIX) bigint
Nulo any SQL type
Objeto aninhado ou matriz varchar(max) (agrupamento de banco de dados UTF-8), serializado como texto JSON

Esquema de fidelidade total

O esquema de fidelidade total do Azure Cosmos DB registra os valores e seus melhores tipos de correspondência para cada propriedade em um contêiner. A OPENROWSET função em um contêiner com esquema de fidelidade total fornece o tipo e o valor real em cada célula. Vamos supor que a consulta a seguir leia os itens de um contêiner com esquema de fidelidade total:

SELECT *
FROM OPENROWSET(
      'CosmosDB',
      'account=MyCosmosDbAccount;database=covid;region=westus2;key=C0Sm0sDbKey==',
       Ecdc
    ) as rows

O resultado dessa consulta retornará tipos e valores formatados como texto JSON:

date_rep cases geo_id
{"data":"2020-08-13"} {"int32":"254"} {"string":"RS"}
{"data":"2020-08-12"} {"int32":"235"} {"string":"RS"}
{"data":"2020-08-11"} {"int32":"316"} {"string":"RS"}
{"data":"2020-08-10"} {"int32":"281"} {"string":"RS"}
{"data":"2020-08-09"} {"int32":"295"} {"string":"RS"}
{"string":"2020/08/08"} {"int32":"312"} {"string":"RS"}
{"data":"2020-08-07"} {"float64":"339.0"} {"string":"RS"}

Para cada valor, você pode ver o tipo identificado em um item de contêiner do Azure Cosmos DB. A maioria dos valores da date_rep propriedade contém date valores, mas alguns deles são armazenados incorretamente como cadeias de caracteres no Azure Cosmos DB. O esquema de fidelidade total retornará valores digitados date corretamente e valores formatados string incorretamente. O número de casos é uma informação armazenada como um valor, mas há um valor que é inserido como um int32 número decimal. Este valor tem o float64 tipo. Se houver alguns valores que excedam o maior int32 número, eles serão armazenados como o int64 tipo. Todos os geo_id valores neste exemplo são armazenados como string tipos.

Importante

A OPENROWSET função sem uma WITH cláusula expõe os valores com tipos esperados e os valores com tipos inseridos incorretamente. Esta função foi concebida para a exploração de dados e não para a elaboração de relatórios. Não analise valores JSON retornados dessa função para criar relatórios. Use uma cláusula WITH explícita para criar seus relatórios. Você deve limpar os valores que têm tipos incorretos no contêiner do Azure Cosmos DB para aplicar correções no repositório analítico de fidelidade total.

Para consultar contas do Azure Cosmos DB para MongoDB, você pode saber mais sobre a representação de esquema de fidelidade total no repositório analítico e os nomes de propriedade estendida a serem usados em O que é o Repositório Analítico do Azure Cosmos DB?.

Consultar itens com esquema de fidelidade total

Ao consultar o esquema de fidelidade total, você precisa especificar explicitamente o tipo SQL e o tipo de propriedade esperado do Azure Cosmos DB na WITH cláusula.

No exemplo a seguir, assumiremos que string é o tipo correto para a propriedade e int32 é o tipo correto para a geo_idcases propriedade:

SELECT geo_id, cases = SUM(cases)
FROM OPENROWSET(
      'CosmosDB'
      'account=MyCosmosDbAccount;database=covid;region=westus2;key=C0Sm0sDbKey==',
       Ecdc
    ) WITH ( geo_id VARCHAR(50) '$.geo_id.string',
             cases INT '$.cases.int32'
    ) as rows
GROUP BY geo_id

Os valores para geo_id e cases que têm outros tipos serão retornados como NULL valores. Esta consulta fará referência apenas ao cases com o tipo especificado na expressão (cases.int32).

Se você tiver valores com outros tipos (cases.int64, ) que não podem ser limpos em um contêiner do Azure Cosmos DB, cases.float64precisará fazer referência explícita a eles em uma WITH cláusula e combinar os resultados. A consulta a seguir agrega , int32int64e float64 armazenada na cases coluna:

SELECT geo_id, cases = SUM(cases_int) + SUM(cases_bigint) + SUM(cases_float)
FROM OPENROWSET(
      'CosmosDB',
      'account=MyCosmosDbAccount;database=covid;region=westus2;key=C0Sm0sDbKey==',
       Ecdc
    ) WITH ( geo_id VARCHAR(50) '$.geo_id.string', 
             cases_int INT '$.cases.int32',
             cases_bigint BIGINT '$.cases.int64',
             cases_float FLOAT '$.cases.float64'
    ) as rows
GROUP BY geo_id

Neste exemplo, o número de casos é armazenado como int32, int64ou float64 valores. Todos os valores devem ser extraídos para calcular o número de casos por país/região.

Resolução de Problemas

Revise a página de autoajuda para encontrar os problemas conhecidos ou as etapas de solução de problemas que podem ajudá-lo a resolver possíveis problemas com consultas do Azure Cosmos DB.

Próximos passos

Para obter mais informações, consulte os seguintes artigos que podem estar em inglês: