Fabric 版 NotebookUtils Power Query 工具(預覽版)

使用此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 連線。