Consultar dados do Azure Cosmos DB usando um pool SQL sem servidor
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 Transact-SQL (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 através 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.
Este artigo explica como escrever uma consulta com um pool SQL sem servidor que consulta 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.
Nota
Não é possível usar a identidade gerenciada para acessar um contêiner do Azure Cosmos DB a partir do pool SQL sem servidor.
Pré-requisitos
- Certifique-se de preparar o repositório analítico:
- Habilite o armazenamento analítico em seus contêineres do Azure Cosmos DB.
- Obtenha a cadeia de conexão com uma chave somente leitura que você pode usar para consultar o repositório analítico.
- Obtenha a chave somente leitura que será usada para acessar o contêiner do Azure Cosmos DB.
- 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 (mais de 80 GB), considere usar a camada de cache, como o Analysis Services, e carregue 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 usar a
OPENROWSET
função com a cláusula explícitaWITH
que tem os menores tipos possíveis. Por exemplo, não useVARCHAR(1000)
se souber que a propriedade tem até cinco 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
que faz referência a uma credencial 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.
Converter a partir 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 Cosmos DB 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_UTF8
porque 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_UTF8
T-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 de Doenças (ECDC) COVID-19 Cases and COVID-19 Open Research Dataset (CORD-19).
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
eCord19
carregados com os conjuntos de dados de exemplo anteriores
Observe que essa conexão não garante 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 WITH
OPENROWSET
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.
Importante
No script, substitua esses valores por seus próprios valores:
- your-cosmosdb - o nome da sua conta do Cosmos DB
- yourcosmosdbkey - sua chave de conta do Cosmos DB
SELECT TOP 10 *
FROM OPENROWSET(
'CosmosDB',
'Account=your-cosmosdb;Database=covid;Key=yourcosmosdbkey',
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 retorna todas as propriedades dos itens do Azure Cosmos DB.
Supondo que os itens no contêiner do Azure Cosmos DB tenham date_rep
, cases
e geo_id
propriedades, os 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=your-cosmosdb;Database=covid;Key=yourcosmosdbkey',
Cord19) as cord19
Especificar explicitamente o esquema
Embora o recurso de inferência automática de esquema forneça OPENROWSET
uma experiência 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 de coluna exatos na WITH
cláusula:
SELECT TOP 10 *
FROM OPENROWSET(
'CosmosDB',
'Account=your-cosmosdb;Database=covid;Key=yourcosmosdbkey',
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 Mapeamentos de tipo do Azure Cosmos DB para SQL no final deste 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 mantenha a chave da sua conta na definição de visualização.
CREATE CREDENTIAL MyCosmosDbAccountCredential
WITH IDENTITY = 'SHARED ACCESS SIGNATURE', SECRET = 'yourcosmosdbkey';
GO
CREATE OR ALTER VIEW Ecdc
AS SELECT *
FROM OPENROWSET(
PROVIDER = 'CosmosDB',
CONNECTION = 'Account=your-cosmosdb;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 de 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 um problema 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. As referências de exibição, colunas ou objetos provavelmente 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. Lembre-se de 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=your-cosmosdb;Database=covid;Key=yourcosmosdbkey',
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 | title | 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":"",… |
Para saber mais, consulte Analisar tipos de dados complexos no Azure Synapse Analytics ou Consultar tipos aninhados em arquivos Parquet e JSON usando pool SQL sem servidor.
Importante
Se você vir caracteres inesperados em seu texto como Mélade
em vez de , então o agrupamento do banco de Mélade
dados não está definido como agrupamento UTF-8 . Você pode alterar o agrupamento de 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=your-cosmosdb;Database=covid;Key=yourcosmosdbkey',
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:
title | 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 Mélade
em vez de , então o agrupamento do banco de Mélade
dados não está definido como agrupamento UTF-8 . Você pode alterar o agrupamento de 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 retorna 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 retorna valores digitados date
corretamente e valores formatados string
incorretamente.
O número de casos é armazenado como um int32
valor, mas há um valor que é inserido como um 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, assumimos que string
é o tipo correto para a geo_id
propriedade e int32
é o tipo correto para a cases
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 são retornados como NULL
valores. Esta consulta faz referência apenas ao cases
com o tipo especificado na expressão (cases.int32
).
Se você tiver valores com outros tipos (cases.int64
, cases.float64
) que não podem ser limpos em um contêiner do Azure Cosmos DB, precisará fazer referência explícita a eles em uma WITH
cláusula e combinar os resultados. A consulta a seguir agrega , int32
int64
e 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
, int64
ou float64
valores. Todos os valores devem ser extraídos para calcular o número de casos por país ou 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.
Conteúdos relacionados
- Usar o Power BI e o pool Synapse SQL sem servidor para analisar dados do Azure Cosmos DB
- Criar e usar modos de exibição usando o pool SQL sem servidor
- Tutorial: Explore e analise data lakes com pool SQL sem servidor
- Se você estiver recebendo erros ou enfrentando problemas de desempenho, consulte Solucionar problemas do pool SQL sem servidor
- Módulo: Implementar o Azure Synapse Link com o Azure Cosmos DB