Utilità NotebookUtils Power Query per Fabric (anteprima)

Usa il notebookutils.powerquery modulo per eseguire query Power Query M da un notebook Fabric e carica i risultati in DataFrames per ulteriori analisi. Puoi riutilizzare connessioni Fabric esistenti, incluse quelle supportate da gateway, per sorgenti dati on-premises supportate che non sono direttamente accessibili dal calcolo Fabric.

Note

Power Query nei notebook è in anteprima. La release iniziale supporta operazioni di lettura dalle fonti dati supportate.

I seguenti esempi in questo articolo utilizzano PySpark (Python).

Come ottenere assistenza

Esegui questi comandi nel tuo notebook per visualizzare la panoramica del modulo e l'aiuto sui metodi:

notebookutils.powerquery.help()
notebookutils.powerquery.help("executeQuery")

Esegui una query

Usa executeQuery per eseguire una query nominata:

notebookutils.powerquery.executeQuery(query_name, script, connections=None)

La tabella seguente descrive i parametri Python:

Parametro Type Description
query_name Stringa o elenco di stringhe Il nome o i nomi della query da eseguire. I nomi delle query devono essere non vuoti e unici.
script Stringa Un'espressione M di Power Query o un documento M completo. Per eseguire più query, fornisci un documento completo che inizia con section e definisce le query nominate.
connections Stringa o elenco di stringhe, opzionale Nomi o ID delle connessioni Fabric esistenti. Ometti questo argomento, o passa None, o una lista vuota, per una query che non necessita di una connessione.

Passare un singolo nome di query come stringa per restituire un DataFrame PySpark. Passa un elenco di nomi di query per restituire un container QueryResults, anche se l'elenco contiene un solo nome.

Esegui una query senza connessione

Questo esempio crea una tabella con un'espressione M, quindi non ha bisogno di una fonte dati esterna né di una connessione Fabric:

script = """
let
    Source = #table(
        type table [Product = text, Quantity = Int64.Type],
        {{"Bike", 2}, {"Helmet", 5}}
    )
in
    Source
"""

df = notebookutils.powerquery.executeQuery("Products", script)
display(df)

Per una singola query, puoi passare direttamente un'espressione M. NotebookUtils incapsula l'espressione in un documento M e gli assegna il nome della query fornito.

Esegui una query con una connessione Fabric

Utilizza una connessione Fabric esistente per cui hai il permesso. Per informazioni sulla creazione e gestione delle connessioni, vedi Gestione delle sorgenti dati.

Il seguente esempio legge una tabella tramite una connessione SQL Server. Sostituisci i valori del server, del database, dello schema, della tabella e della connessione con i tuoi:

script = """
let
    Source = Sql.Database("<server>", "<database>"),
    Products = Source{[Schema = "<schema>", Item = "<table>"]}[Data]
in
    Products
"""

df = notebookutils.powerquery.executeQuery(
    "Products",
    script,
    connections=["<fabric-connection-id>"]
)
display(df)

Puoi usare un nome di connessione invece di un ID. Se più connessioni hanno lo stesso nome, usa l'ID della connessione per identificare la connessione in modo inequivocabile.

Lo script M specifica ancora l'origine dati. Assicurati che i dettagli della sua origine corrispondano alla connessione Fabric. Quando la sorgente richiede un gateway locale, fornisci la connessione Fabric supportata dal gateway tramite lo stesso connections parametro.

Per usare più di una connessione, passa un elenco di nomi o ID di connessione. L'elenco completo delle connessioni è disponibile per ogni query nel documento M; le connessioni non vengono assegnate alle query in base alla posizione dell'elenco.

Esegui più query

Per restituire più di una query, definisci le query in un documento M completo e passa i loro nomi come elenco. Questo esempio non richiede una connessione:

script = """
section Section1;
shared Products = #table(
    type table [Product = text, Quantity = Int64.Type],
    {{"Bike", 2}, {"Helmet", 5}}
);
shared SelectedProducts = Table.SelectRows(Products, each [Quantity] > 2);
"""

results = notebookutils.powerquery.executeQuery(
    ["Products", "SelectedProducts"],
    script
)

results.raise_if_failed()
display(results["Products"])
display(results["SelectedProducts"])

Se le query accedono a fonti dati esterne, passa le connessioni richieste dall'intero documento M nell'argomento connections .

Gestire i risultati delle query e gli errori

QueryResults Separa i risultati della query riusciti dagli errori per ogni query:

Membro Description
successes Un dizionario che mappa i nomi delle query riuscite a PySpark DataFrame.
failures Un dizionario che mappa i nomi delle query non riuscite a messaggi di errore.
results["QueryName"] Restituisce il DataFrame per una query riuscita. Genera QueryExecutionError se la query è fallita, o KeyError se il nome non compare nei risultati.
get("QueryName") Restituisce il DataFrame se la query è andata a buon fine, oppure None se è fallita o non è presente nei risultati.
is_all_success() Restituisce True se nessuna query è fallita.
raise_if_failed() Genera un'eccezione se una query è fallita.

Per elaborare query riuscite anche quando un'altra query fallisce, ispeziona entrambi i dizionari invece di chiamare raise_if_failed():

for query_name, frame in results.successes.items():
    print(query_name)
    display(frame)

for query_name, error in results.failures.items():
    print(f"{query_name}: {error}")

Una chiamata a query singola genera un'eccezione se l'esecuzione fallisce. Argomenti non validi, struttura di documento M non valida o fallimenti nella risoluzione della connessione possono anche generare un'eccezione prima che una chiamata multi-query restituisca QueryResults.

Limitazioni e considerazioni

  • La release iniziale supporta le letture, non le operazioni di scrittura verso sorgenti dati.
  • Il timeout per la valutazione della query è di 230 secondi. Per le valutazioni supportate dal gateway, il timeout è di 180 secondi.
  • I nomi delle query non possono superare gli 80 caratteri.
  • Il documento M completo non può superare i 512 KiB (524.288 byte) quando codificato come UTF-8. Per un'espressione grezza, questo limite include l'involucro del documento aggiunto da NotebookUtils.
  • Puoi fornire fino a 100 connessioni per un documento M.
  • Per eseguire più query, lo script deve iniziare con section. Definisci ogni query richiesta come shared membro di quel documento.
  • L'accesso supportato tramite gateway richiede una connessione Fabric configurata per la fonte dati on-premises supportata.