使用英语阅读

通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

macro-expand 运算符

  • 项目

适用于：✅Microsoft Fabric✅Azure 数据资源管理器

macro-expand 运算符简化了在一组 实体（例如群集、数据库或表）上运行子查询，然后将结果合并为单个输出。

当数据分散在多个群集、数据库或表之间时，运算符非常有用。 例如，当数据与其源位于同一全局区域中时，可以在不同位置的单个查询中使用 macro-expand 运算符，而不是为每个实体运行单独的查询并手动合并结果。

要查询的实体集称为 实体组。 可以存储实体组，以便在数据库中重复使用，也可以直接在查询文本中定义。 有关存储实体组的详细信息，请参阅 实体组。

macro-expand 运算符为组中的每个实体单独运行子查询，然后将所有结果合并到单个输出中。 子查询可以包含嵌套 macro-expand 运算符。 但是，内部 macro-expand 的标识符必须与外部 macro-expand 的标识符不同，才能清楚地区分每个 macro-expand 的范围和引用。

语法

macro-expand [kind=Kind] [isfuzzy=IsFuzzy] EntityGroupasEntityIdentifier(Subquery)

macro-expand [kind=Kind] [isfuzzy=IsFuzzy] entity_group[EntityReference [, ...] asEntityIdentifier(Subquery)``]

macro-expand EntityIdentifierinEntityGroupIdentifier(子查询)

备注

macro-expand 运算符的作可以通过使用 set statement 或通过 客户端请求属性来将 best_effort 请求属性设置为 true来修改。 当此属性设置为 true时，macro-expand 运算符将忽略模糊解析和连接失败，以执行正在联合的任何子表达式，并在查询状态结果中发出警告。

变化

可通过多种方式指定 macro-expand 运算符使用的实体组：

  • 内联： 运算符调用本身的文本中显式定义所有元素。 有关示例，请参阅 计算错误。

  • Via let 语句： 使用语法 macro-expand 运算符外部的 let 语句在查询中指定实体组：

    let EntityGroupIdentifier=entity_group[EntityReference [, ...]]

    有关示例，请参阅 使用 let 语句计算 SKU 错误。

  • 使用存储实体组： 查询使用存储在数据库中的实体组，而不是在查询中定义。

    有关示例，请参阅 使用上下文标量函数扩展表。

参数

名字 类型 必填 描述
Kind string inner 或 outer（默认值）。 当 kind 设置为 inner时，结果仅包括所有访问的作用域实体共有的列。 如果设置为 outer，则结果包括任何输入中发生的所有列。 输入行未定义的单元格设置为 null。
IsFuzzy 设置为 true时，它只考虑当前存在且可访问的实体源。 如果找到至少一个实体，查询将运行，并且任何缺失的实体在查询状态结果中生成警告。 如果未找到任何实体，查询将无法解析任何指定的实体并返回错误。 默认值为 false。
EntityGroup ✔️ 一组 EntityIdentifier 的实体 在运行查询时展开。 实体组可以是存储的实体组或定义的组。 它表示 EntityIdentifier 扩展到的同一类型的一个或多个实体。
EntityIdentifier string ✔️ 一个标识符，用作子查询中实体的占位符，并在运行查询时将其扩展为实际实体。 假定实体在 EntityIdentifier 中未显式限定为当前作用域数据库中的一部分。 查询中包含的任何特定标识符将替代默认假设。
EntityReference string 实体组中包含的实体。 如果未指定 EntityGroup，则需要一个或多个 EntityReference。
子查询 string ✔️ 不直接获取输入数据的单个表格表达式。 它可能包括通过 EntityIdentifier对实体的引用，并使用表达式（例如 let 语句、存储函数或其他数据库中的元素）。 子查询 前面可以有一个或多个 let 语句。 它还可以引用子查询上下文函数 。

备注

查询只能引用在查询文本或当前数据库中定义的实体组。 不能直接或间接引用其他数据库或群集中的实体组。

子查询上下文函数

macro-expand 子查询可以引用两个专用标量函数，就像它们是所引用实体的一部分一样：

  • $current_database - 返回实体引用的数据库名称。
  • $current_cluster_endpoint - 返回实体引用群集的 URL。

例子

以下示例演示如何使用 macro-expand运算符。

计算错误

以下示例使用 内联变体 实体组来计算每个库存保留单位（SKU）生成的错误数。 它定义一个 entity_group（X），其中包括两个群集中名为 MyDatabase 的数据库。 然后，该查询执行子查询以筛选错误日志，并通过 Source对错误进行计数。 接下来，它会使用 DimCluster 表对 Source 执行 inner 联接，以获取每个源的 SKU。 最后，它通过 SKU对错误计数求和。

Kusto 
macro-expand entity_group [cluster('C1').database('MyDatabase'), cluster('C2').database('MyDatabase')] as X
(
    X.Logs
    | where Level == 'Error'
    | summarize Count=count() by Source
    | join kind=inner (X.DimCluster | project SKU, Source) on Source
)
| summarize Sum=sum(Count) by SKU

  • summarize 运算符适用于所有展开的子查询的组合结果，而 macro-expand 运算符仅应用于括号之间的子查询，因此明确了哪个范围已展开。

  • join 运算符针对 entity_group中的每个实体单独执行。 在此示例中，join 在同一实体中的两个表之间执行，由 X表示。 这意味着没有跨群集 join。

若要在不使用 macro-expand的情况下编写相同的查询，其外观可能如下所示：

Kusto 
union
  (
    cluster('C1').database('MyDatabase').Logs
    | where Level == 'Error'
    | summarize Count=count() by Source
    | join kind=inner (cluster('C1').database('MyDatabase').DimCluster | project SKU, Source) on Source
  ),
  (
    cluster('C2').database('MyDatabase').Logs
    | where Level == 'Error'
    | summarize Count=count() by Source
    | join kind=inner (cluster('C2').database('MyDatabase').DimCluster | project SKU, Source) on Source
  )
| summarize Sum=sum(Count) by SKU

使用 let 语句计算 SKU 错误

以下示例使用 let 语句 在名为 Greater 的变量中定义实体组，其中包括 C1 和 C2 群集中的 MyDatabase 数据库。 然后，此实体组用于在上一个示例 中执行相同的查询， 计算每个 SKU 生成的错误数。 macro-expand 运算符用于引用 Greater 实体组（别名 X）。

Kusto 
let GreaterDatabase = entity_group [cluster('C1').database('MyDatabase'), cluster('C2').database('MyDatabase')];
macro-expand GreaterDatabase as X
(
    X.Logs
    | where Level == 'Error'
    | summarize Count=count() by Source
    | join kind=inner (X.DimCluster | project SKU, Source) on Source
)
| summarize Sum=sum(Count) by SKU

使用上下文标量函数扩展表

以下查询使用 存储实体组 变体。 它使用存储的实体组 MyEntityGroup对每个实体的 Admins 表运行子查询。 有关如何创建存储实体的详细信息，请参阅 .create entity_group 命令。 它使用 $current_database 和 $current_cluster_endpoint 来扩展表，为每个行添加当前数据库和当前群集。 然后，它通过计算 current_cluster 和 current_database的每个组合的行数来汇总结果。

Kusto 
macro-expand MyEntityGroup as X
(
    X.Admins
    | extend current_database = X.$current_database, current_cluster = X.$current_cluster_endpoint
)
| summarize count() by current_cluster, current_database

嵌套宏扩展查询

以下查询运行嵌套子查询，其中包含外部实体组 MyEntityGroup_Outer（别名 X）和内部实体组 MyEntityGroup_Inner（别名 Y）。 它将外部（X）和内部（Y）实体组中的每个实体联接 Admins 表。 查询筛选过去一小时内的日志。 然后，它扩展表以使用 $current_database 和 $current_cluster_endpoint包含每行的当前数据库和群集。 查询对 Source 列执行 join，以合并内部和外部实体组。 前缀 lhs（左侧）和 rhs（右侧）分别表示 X 和 Y 实体组。 最后，它通过计算 lhs_cluster、lhs_database、rhs_cluster和 rhs_database的每个组合的行数来汇总结果。

Kusto 
macro-expand MyEntityGroup_Outer as X
(
    macro-expand  MyEntityGroup_Inner as Y
    (
        X.Admins
        | where Timestamp > ago(1h)
        | extend lhs_database = X.$current_database, lhs_cluster = X.$current_cluster_endpoint
        | join (
            Y.Admins
            | where Timestamp > ago(1h)
            | extend rhs_database = Y.$current_database, rhs_cluster = Y.$current_cluster_endpoint
        ) on Source
    )
)
| summarize count() by lhs_cluster, lhs_database, rhs_cluster, rhs_database

相关内容