使用此notebookutils.powerquery模組從 Fabric 筆記本執行 Power Query M 查詢,並將結果載入 DataFrames 以供進一步分析。 您可以重複利用現有的 Fabric 連線,包括支援的本地端資料來源由閘道支援的連線,這些資料來源無法直接從 Fabric 運算存取。
Note
筆記本中的 Power Query 目前處於預覽階段。 初版版本支援從支援的資料來源進行讀取操作。
本文中的以下範例使用 PySpark(Python)。
尋求幫助
在您的筆記本中執行以下指令,以檢視模組概述及方法說明:
notebookutils.powerquery.help()
notebookutils.powerquery.help("executeQuery")
執行查詢
使用 executeQuery 執行命名查詢:
notebookutils.powerquery.executeQuery(query_name, script, connections=None)
下表說明 Python 參數:
| Parameter | 類型 | Description |
|---|---|---|
query_name |
字串或字串清單 | 要執行的查詢名稱或多個名稱。 查詢名稱必須非空且唯一。 |
script |
String | 一個 Power Query M 表達式或完整的 M 文件。 若要執行多個查詢,請提供一份以 section 開頭並定義這些具名查詢的完整文件。 |
connections |
字串或字串清單,選填 | 現有的 Fabric 連線名稱或 ID。 對於不需要連線的查詢,請省略此參數,或傳遞 None 或空白清單。 |
將單一查詢名稱以字串傳遞,以傳回 PySpark DataFrame。 傳遞查詢名稱清單以傳回 QueryResults 容器,即使該清單只包含一個名稱。
在沒有連線的情況下執行查詢
此範例建立一個具有 M 表達式的資料表,因此不需要外部資料來源或 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)
對於單一查詢,您可以直接傳遞 M 運算式。 NotebookUtils 會將該表達式包裹在 M 文件中,並指定您提供的查詢名稱。
使用 Fabric 連線執行查詢
使用您已授權使用的現有 Fabric 連線。 有關建立與管理連線的資訊,請參閱 資料來源管理。
以下範例透過 SQL Server 連線讀取資料表。 將伺服器、資料庫、結構、資料表及連線值替換為您自己的:
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)
您可以使用連線名稱代替 ID。 如果多個連線名稱相同,請使用連線 ID 來明確識別該連線。
M 腳本仍指定資料來源。 請確保其來源細節與 Fabric 連線相符。 當來源需要本地閘道時,請透過相同connections參數提供由閘道支援的 Fabric 連線。
若要使用多個連線,請傳遞連線名稱或 ID 清單。 完整的連線清單可供 M 文件中的每個查詢查詢使用;連線不會依列表位置分配給查詢。
執行多個查詢
若要回傳多個查詢,請在完整的 M 文件中定義這些查詢,並以清單形式傳入其名稱。 此範例不需要連線:
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"])
如果查詢存取外部資料來源,請在 connections 參數中傳遞整個 M 文件所需的連線。
處理查詢結果與失敗案例
QueryResults 將成功查詢結果與每次查詢失敗區分開來:
| 會員 | Description |
|---|---|
successes |
一個將成功查詢名稱對應至 PySpark DataFrames 的字典。 |
failures |
一個字典,用來將失敗的查詢名稱對應到錯誤訊息。 |
results["QueryName"] |
回傳成功查詢的 DataFrame。 若查詢失敗,則會引發 KeyError;若名稱未出現在結果中,則會引發 QueryExecutionError。 |
get("QueryName") |
如果查詢成功,則回傳 DataFrame;如果查詢失敗或不在結果中,則回傳 None。 |
is_all_success() |
若無查詢失敗,則回傳 True 。 |
raise_if_failed() |
若任何查詢失敗,則引發例外。 |
若要在另一查詢失敗時仍能處理成功查詢,請檢查兩個字典,而非呼叫 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}")
若執行失敗,單一查詢呼叫會觸發例外。 無效的參數、無效的 M 文件結構,或連線解析失敗,也可能在多查詢呼叫回傳 QueryResults前引發例外。
限制與考量
- 初版版本支援讀取,而非對資料來源的回寫操作。
- 查詢評估逾時時間為 230 秒。 對於由閘道提供支援的評估,逾時時間為 180 秒。
- 查詢名稱不得超過 80 個字元。
- 完整 M 文件在以 UTF-8 編碼時,不得超過 512 KiB(524,288 位元組)。 對於原始運算式,此限制包含由 NotebookUtils 新增的文件包裝器。
- 您最多可為一份 M 文件提供 100 個連線。
- 若要執行多個查詢,腳本必須以
section開頭。 將每個請求的查詢定義為該文件的shared成員。 - 由閘道支援的存取需要為支援的內部部署資料來源設定 Fabric 連線。