使用该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 连接。