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"])

如果查询访问外部数据源,请在参数中传递整个 M 文档 connections 所需的连接。

处理查询结果和查询失败

QueryResults 将成功的查询结果与每次查询失败区分开来:

成员 Description
successes 一个将成功查询名称映射到 PySpark DataFrames 的字典。
failures 一个将失败查询名称映射到错误消息的字典。
results["QueryName"] 返回查询成功的 DataFrame。 如果查询失败,则引发KeyError;如果名称未出现在结果中,则引发QueryExecutionError。
get("QueryName") 如果查询成功,则返回数据帧;如果失败或未在结果中,则返回 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 连接。