Condividi tramite


Eseguire query sui dati di Azure Cosmos DB usando un pool SQL serverless

Un pool SQL serverless consente di analizzare i dati nei contenitori Azure Cosmos DB abilitati con Collegamento ad Azure Synapse quasi in tempo reale senza influire sulle prestazioni dei carichi di lavoro transazionali. Offre una sintassi Transact-SQL (T-SQL) familiare per eseguire query sui dati dall'archivio analitico e la connettività integrata a un'ampia gamma di strumenti di business intelligence (BI) e di query ad hoc tramite l'interfaccia T-SQL.

Per l'esecuzione di query su Azure Cosmos DB, la superficie di attacco SELECT completa è supportata tramite la funzione OPENROWSET, che include la maggior parte delle funzioni e degli operatori SQL. È anche possibile archiviare i risultati della query che legge i dati da Azure Cosmos DB insieme ai dati in Archiviazione BLOB di Azure o in Azure Data Lake Storage usando Create Table As Select (CETAS). Attualmente non è possibile archiviare i risultati delle query del pool SQL serverless in Azure Cosmos DB con CETAS.

Questo articolo illustra come scrivere una query con un pool SQL serverless che esegue query sui dati dai contenitori di Azure Cosmos DB abilitati con Azure Collegamento a Synapse. È quindi possibile ottenere altre informazioni sulla creazione di viste di pool SQL serverless sui contenitori di Azure Cosmos DB e sulla connessione ai modelli di Power BI in questa esercitazione. Questa esercitazione usa un contenitore con uno schema ben definito di Azure Cosmos DB. È anche possibile consultare il modulo Learn su come eseguire query su Azure Cosmos DB con SQL Serverless per Azure Synapse Analytics.

Nota

Non è possibile usare l'identità gestita per accedere a un contenitore di Azure Cosmos DB dal pool SQL serverless.

Prerequisiti

  • Assicurarsi di preparare l'archivio analitico:
  • Assicurarsi di aver applicato tutte le procedure consigliate, ad esempio:
    • Assicurarsi che l'archiviazione analitica di Azure Cosmos DB si trovi nella stessa area del pool SQL serverless.
    • Assicurarsi che l'applicazione client (Power BI, Analysis Service) si trovi nella stessa area del pool SQL serverless.
    • Se si restituisce una grande quantità di dati (più di 80 GB), è consigliabile usare il livello di memorizzazione nella cache, ad esempio Analysis Services, e caricare le partizioni inferiori a 80 GB nel modello di Analysis Services.
    • Se si filtrano i dati usando colonne stringa, assicurarsi di usare la OPENROWSET funzione con la clausola esplicita WITH con i tipi più piccoli possibili. Ad esempio, non usare VARCHAR(1000) se si sa che la proprietà ha fino a cinque caratteri.

Panoramica

Il pool SQL serverless consente di eseguire query nell'archiviazione analitica di Azure Cosmos DB usando la funzione OPENROWSET.

  • OPENROWSET con chiave inline. Questa sintassi può essere usata per eseguire query sulle raccolte di Azure Cosmos DB senza la necessità di preparare le credenziali.
  • OPENROWSET che fa riferimento a una credenziale che contiene la chiave dell'account Azure Cosmos DB. È possibile usare questa sintassi per creare viste sulle raccolte di Azure Cosmos DB.

Per supportare l'esecuzione di query e l'analisi dei dati in un archivio analitico di Azure Cosmos DB, viene usato un pool SQL serverless. Il pool SQL serverless usa la sintassi SQL di OPENROWSET, quindi è necessario prima convertire la stringa di connessione di Azure Cosmos DB in questo formato:

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

La stringa di connessione SQL per Azure Cosmos DB specifica il nome dell'account Azure Cosmos DB, il nome del database, la chiave master dell'account di database e un nome di area facoltativo per la funzione OPENROWSET. Alcune di queste informazioni possono essere ricavate dalla stringa di connessione standard di Azure Cosmos DB.

Eseguire la conversione dal formato stringa di connessione standard di Azure Cosmos DB:

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

Il formato di una stringa di connessione SQL è simile al seguente:

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

L'area è facoltativa. Se omessa, verrà usata l'area primaria del contenitore.

Importante

Esiste un altro parametro facoltativo in stringa di connessione denominato endpoint. Il endpoint parametro è necessario per gli account che non corrispondono al formato standard *.documents.azure.com . Ad esempio, se l'account Azure Cosmos DB termina con .documents.azure.us, assicurarsi di aggiungere endpoint=<account name>.documents.azure.us il stringa di connessione.

Il nome del contenitore di Azure Cosmos DB viene specificato senza virgolette nella sintassi di OPENROWSET. Se il nome del contenitore contiene caratteri speciali, ad esempio un trattino (-), il nome deve essere racchiuso tra parentesi quadre ([]) nella sintassi di OPENROWSET.

Importante

Assicurarsi di usare alcune regole di confronto del database UTF-8, ad esempio Latin1_General_100_CI_AS_SC_UTF8, perché i valori stringa in un archivio analitico di Azure Cosmos DB vengono codificati come testo UTF-8. Una mancata corrispondenza tra la codifica del testo nel file e le regole di confronto potrebbe causare errori imprevisti di conversione del testo. È possibile modificare facilmente le regole di confronto predefinite del database corrente con l'istruzione T-SQL alter database current collate Latin1_General_100_CI_AI_SC_UTF8.

Nota

Un pool SQL serverless non supporta l'esecuzione di query su un archivio transazionale di Azure Cosmos DB.

Set di dati di esempio

Gli esempi in questo articolo sono basati sui dati del Centro europeo per la prevenzione e il controllo delle malattie (ECDC) COVID-19 Case e COVID-19 Open Research Dataset (CORD-19).

È possibile visualizzare la licenza e la struttura dei dati in queste pagine. È anche possibile scaricare dati di esempio per i set di dati ECDC e CORD-19.

Per proseguire con questo articolo, che illustra come eseguire query sui dati di Azure Cosmos DB con un pool SQL serverless, assicurarsi di creare le risorse seguenti:

  • Un account del database Azure Cosmos DB abilitato per Azure Collegamento a Synapse
  • Un database di Azure Cosmos DB denominato covid
  • Due contenitori di Azure Cosmos DB denominati Ecdc e Cord19 caricati con i set di dati di esempio precedenti

Si noti che questa connessione non garantisce prestazioni perché questo account potrebbe trovarsi in un'area remota rispetto all'endpoint Synapse SQL.

Esplorare i dati di Azure Cosmos DB con l'inferenza automatica dello schema

Il modo più semplice per esplorare i dati in Azure Cosmos DB consiste nello sfruttare la capacità di inferenza automatica dello schema. Omettendo la clausola WITH dall'istruzione OPENROWSET, è possibile indicare al pool SQL serverless di rilevare automaticamente (tramite inferenza) lo schema dell'archivio analitico del contenitore di Azure Cosmos DB.

Importante

Nello script sostituire questi valori con i propri valori:

  • your-cosmosdb : nome dell'account Cosmos DB
  • yourcosmosdbkey : chiave dell'account Cosmos DB
SELECT TOP 10 *
FROM OPENROWSET( 
       'CosmosDB',
       'Account=your-cosmosdb;Database=covid;Key=yourcosmosdbkey',
       Ecdc) as documents

Nell'esempio precedente è stato indicato al pool SQL serverless di connettersi al database covid nell'account Azure Cosmos DB MyCosmosDbAccount autenticato usando la chiave di Azure Cosmos DB (fittizia nell'esempio precedente). È stato quindi eseguito l'accesso all'archivio analitico del contenitore Ecdc nell'area West US 2. Poiché non esiste alcuna proiezione di proprietà specifiche, la OPENROWSET funzione restituisce tutte le proprietà dagli elementi di Azure Cosmos DB.

Supponendo che gli elementi nel contenitore Azure Cosmos DB abbiano le proprietà date_rep, cases e geo_id, i risultati di questa query vengono visualizzati nella tabella seguente:

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

Se è necessario esplorare i dati dall'altro contenitore nello stesso database di Azure Cosmos DB, è possibile usare la stessa stringa di connessione e fare riferimento al contenitore richiesto come terzo parametro:

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

Specificare lo schema in modo esplicito

Anche se la funzionalità di inferenza automatica dello schema in OPENROWSET offre un'esperienza semplice e facile da usare, gli scenari aziendali potrebbero richiedere di specificare in modo esplicito lo schema per le proprietà pertinenti di sola lettura dai dati di Azure Cosmos DB.

La OPENROWSET funzione consente di specificare in modo esplicito le proprietà da leggere dai dati nel contenitore e di specificare i relativi tipi di dati.

Si supponga di aver importato alcuni dati dal set di dati ECDC COVID con la struttura seguente in 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"}

Questi documenti JSON flat in Azure Cosmos DB possono essere rappresentati come un set di righe e colonne in Synapse SQL. La OPENROWSET funzione consente di specificare un subset di proprietà che si desidera leggere e i tipi di colonna esatti nella WITH clausola :

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

Il risultato di questa query potrebbe essere simile alla tabella seguente:

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

Per altre informazioni sui tipi SQL da usare per i valori di Azure Cosmos DB, vedere Mapping dei tipi da Azure Cosmos DB a SQL alla fine di questo articolo.

Crea visualizzazione

La creazione di viste nei master database predefiniti o non è consigliata o supportata. È quindi necessario creare un database utente per le viste.

Dopo aver identificato lo schema, è possibile preparare una vista basata sui dati di Azure Cosmos DB. È opportuno inserire la chiave dell'account Azure Cosmos DB in credenziali separate e fare riferimento a tali credenziali dalla funzione OPENROWSET. Non mantenere la chiave dell'account nella definizione di visualizzazione.

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

Non usare OPENROWSET senza uno schema definito in modo esplicito perché potrebbe influire sulle prestazioni. Assicurarsi di usare le dimensioni più piccole possibili per le colonne, ad esempio VARCHAR(100) anziché il valore predefinito VARCHAR(8000). È consigliabile usare alcune regole di confronto UTF-8 come regole di confronto predefinite del database o impostarla come regole di confronto di colonna esplicite per evitare un problema di conversione UTF-8. Le regole di confronto Latin1_General_100_BIN2_UTF8 offrono prestazioni ottimali quando si filtrano i dati usando alcune colonne stringa.

Quando si esegue una query sulla vista, è possibile che si verifichino errori o risultati imprevisti. Le colonne o gli oggetti di riferimento alla vista sono stati probabilmente modificati o non esistono più. È necessario modificare manualmente la definizione della vista in modo che sia allineata alle modifiche sottostanti dello schema. Tenere presente che questa situazione può verificarsi sia quando si usa l'inferenza automatica dello schema nella vista che quando si specifica in modo esplicito lo schema.

Eseguire query su oggetti annidati

Con Azure Cosmos DB è possibile rappresentare modelli di dati più complessi componendoli come matrici oppure oggetti annidati. La funzionalità di sincronizzazione automatica di Collegamento ad Azure Synapse per Azure Cosmos DB gestisce la rappresentazione dello schema nell'archivio analitico predefinito, che include la gestione dei tipi di dati annidati che consentono l'esecuzione di query avanzate dal pool SQL serverless.

Ad esempio, il set di dati CORD-19 include documenti JSON conformi a questa struttura:

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

Le matrici e gli oggetti annidati in Azure Cosmos DB sono rappresentati come stringhe JSON nel risultato della query quando vengono letti dalla funzione OPENROWSET. È possibile specificare i percorsi dei valori annidati negli oggetti quando si usa la clausola WITH:

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;

Il risultato di questa query potrebbe essere simile alla tabella seguente:

paper_id title metadata authors
bb11206963e831f… Supplementary Information An eco-epidemi… {"title":"Supplementary Informati… [{"first":"Julien","last":"Mélade","suffix":"","af…
bb1206963e831f1… The Use of Convalescent Sera in Immune-E… {"title":"The Use of Convalescent… [{"first":"Antonio","last":"Lavazza","suffix":"", …
bb378eca9aac649… Tylosema esculentum (Marama) Tuber and B… {"title":"Tylosema esculentum (Ma… [{"first":"Walter","last":"Chingwaru","suffix":"",…

Per altre informazioni, vedere Analizzare i tipi di dati complessi in Azure Synapse Analytics o Eseguire query sui tipi annidati in file Parquet e JSON usando il pool SQL serverless.

Importante

Se nel testo vengono visualizzati caratteri imprevisti come MÃÂ&copy;lade invece di Mélade, le regole di confronto del database non sono impostate su UTF-8. È possibile modificare le regole di confronto del database in UTF-8 usando un'istruzione SQL come ALTER DATABASE MyLdw COLLATE LATIN1_GENERAL_100_CI_AS_SC_UTF8.

Rendere flat le matrici annidate

I dati di Azure Cosmos DB potrebbero presentare matrici secondarie annidate, come la matrice dell'autore di un set di dati 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>
            },
            ...
        ],
        ...
}

In alcuni casi, potrebbe essere necessario unire le proprietà dall'elemento superiore (metadati) con tutti gli elementi della matrice (autori). Un pool SQL serverless consente di rendere flat le strutture annidate applicando la funzione alla OPENJSON matrice nidificata:

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

Il risultato di questa query potrebbe essere simile alla tabella seguente:

title authors primo ultimo affiliation
Supplementary Information An eco-epidemi… [{"first":"Julien","last":"Mélade","suffix":"","affiliation":{"laboratory":"Centre de Recher… Julien Mélade {"laboratory":"Centre de Recher…
Supplementary Information An eco-epidemi… [{"first":"Nicolas","last":"4#","suffix":"","affiliation":{"laboratory":"","institution":"U… Nicolas #4 {"laboratory":"","institution":"U…
Supplementary Information An eco-epidemi… [{"first":"Beza","last":"Ramazindrazana","suffix":"","affiliation":{"laboratory":"Centre de Recher… Beza Ramazindrazana {"laboratory":"Centre de Recher…
Supplementary Information An eco-epidemi… [{"first":"Olivier","last":"Flores","suffix":"","affiliation":{"laboratory":"UMR C53 CIRAD, … Olivier Flores {"laboratory":"UMR C53 CIRAD, …

Importante

Se nel testo vengono visualizzati caratteri imprevisti come MÃÂ&copy;lade invece di Mélade, le regole di confronto del database non sono impostate su UTF-8. È possibile modificare le regole di confronto del database in UTF-8 usando un'istruzione SQL come ALTER DATABASE MyLdw COLLATE LATIN1_GENERAL_100_CI_AS_SC_UTF8.

Mapping dei tipi Azure Cosmos DB ai tipi SQL

Anche se l'archivio transazionale di Azure Cosmos DB è indipendente dallo schema, l'archivio analitico viene schematizzato per ottimizzare le prestazioni delle query analitiche. Con la funzionalità di sincronizzazione automatica di Collegamento ad Azure Synapse, Azure Cosmos DB gestisce la rappresentazione dello schema nell'archivio analitico predefinito, che include la gestione dei tipi di dati annidati. Poiché un pool SQL serverless esegue query sull'archivio analitico, è importante comprendere come eseguire il mapping dei tipi di dati di input di Azure Cosmos DB ai tipi di dati SQL.

Gli account Azure Cosmos DB dell'API SQL (Core) supportano i tipi di proprietà JSON di numero, stringa, booleano, null, oggetto annidato o matrice. Se si usa la clausola WITH in OPENROWSET, potrebbe essere necessario scegliere tipi SQL corrispondenti a questi tipi JSON. La tabella seguente illustra i tipi di colonna SQL che dovrebbero essere usati per tipi di proprietà diversi in Azure Cosmos DB.

Tipo di proprietà di Azure Cosmos DB Tipo di colonna SQL
Booleano bit
Intero bigint
Decimale float
String varchar (regole di confronto del database UTF-8)
Data/ora (stringa in formato ISO) varchar(30)
Data/ora (timestamp UNIX) bigint
Null any SQL type
Oggetto annidato o matrice varchar(max) (regole di confronto del database UTF-8), serializzato come testo JSON

Schema di massima fedeltà

Lo schema di massima fedeltà di Azure Cosmos DB registra sia i valori che i tipi di corrispondenza migliori per ogni proprietà in un contenitore. La funzione OPENROWSET in un contenitore con schema di massima fedeltà fornisce sia il tipo che il valore effettivo in ogni cella. Si supponga che la query seguente legga gli elementi da un contenitore con schema di massima fedeltà:

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

Il risultato di questa query restituisce tipi e valori formattati come testo JSON:

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

Per ogni valore è possibile visualizzare il tipo identificato in un elemento del contenitore di Azure Cosmos DB. La maggior parte dei valori per la proprietà date_rep contiene valori di date, ma alcuni di essi vengono archiviati erroneamente come stringhe in Azure Cosmos DB. Lo schema di fedeltà completa restituisce valori tipizzati date correttamente e valori formattati string in modo non corretto.

Il numero di case viene archiviato int32 come valore, ma esiste un valore immesso come numero decimale. Questo valore è di tipo float64. Se sono presenti alcuni valori che superano il numero massimo di int32, verranno archiviati come tipo int64. Tutti i valori geo_id in questo esempio vengono archiviati come tipi string.

Importante

La funzione OPENROWSET senza una clausola WITH espone entrambi i valori con i tipi e i valori previsti con tipi immessi in modo non corretto. Questa funzione è progettata per l'esplorazione dei dati e non per la creazione di report. Non analizzare i valori JSON restituiti da questa funzione per creare report. Usare una clausola WITH esplicita per creare i report. È necessario pulire i valori con tipi non corretti nel contenitore di Azure Cosmos DB per applicare correzioni nell'archivio analitico di massima fedeltà.

Per eseguire query sugli account Azure Cosmos DB for MongoDB, vedere altre informazioni sulla rappresentazione dello schema di massima fedeltà nell'archivio analitico e sui nomi delle proprietà estese da usare in Informazioni sull'archivio analitico di Azure Cosmos DB.

Eseguire query sugli elementi con schema di massima fedeltà

Durante l'esecuzione di query sullo schema di massima fedeltà, è necessario specificare in modo esplicito il tipo SQL e il tipo di proprietà di Azure Cosmos DB previsto nella clausola WITH.

Nell'esempio seguente si presuppone che string sia il tipo corretto per la geo_id proprietà ed int32 è il tipo corretto per la cases proprietà :

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

I valori per geo_id e cases con altri tipi vengono restituiti come NULL valori. Questa query fa riferimento solo a cases con il tipo specificato nell'espressione (cases.int32).

Se sono presenti valori con altri tipi (cases.int64, cases.float64) che non possono essere puliti in un contenitore di Azure Cosmos DB, è necessario farvi riferimento in modo esplicito in una clausola WITH e combinare i risultati. La query seguente aggrega int32, int64 e float64 archiviati nella colonna cases:

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

In questo esempio il numero di casi viene archiviato come valori int32, int64 o float64. Tutti i valori devono essere estratti per calcolare il numero di case per paese o area geografica.

Risoluzione dei problemi

Esaminare la pagina del Supporto self-help per individuare i problemi noti o i passaggi per la risoluzione dei problemi che consentono di risolvere potenziali problemi relativi alle query di Azure Cosmos DB.