macro-expand operator

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

The macro-expand operator simplifies running a subquery on a set of entities, such as clusters, databases, or tables, and then combining the results into a single output.

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

The set of entities you want to query is called an entity group. 可以存储实体组，以便在数据库中重复使用，也可以直接在查询文本中定义。 For more information about stored entity groups, see Entity groups.

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

Syntax

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

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

macro-expand EntityIdentifierinEntityGroupIdentifier(Subquery)

Variations

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

• Inline: All elements are explicitly defined in the text of the operator invocation itself. For an example, see Calculate errors.

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

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

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

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

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

Parameters

子查询上下文标量

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

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

Examples

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

Calculate errors

The following example uses an inline variation entity group to calculate the number of errors produced by each Stock Keeping Unit (SKU). 它定义一个 entity_group（X），其中包括两个群集中名为 MyDatabase 的数据库。 然后，该查询执行子查询以筛选错误日志，并通过 Source对错误进行计数。 接下来，它会使用 inner 表对 Source 执行 DimCluster 联接，以获取每个源的 SKU。 最后，它通过 SKU对错误计数求和。

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的情况下编写相同的查询，其外观可能如下所示：

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 的变量中定义实体组，其中包括 MyDatabase 和 C1 群集中的 C2 数据库。 This entity group is then used to perform the same query in the previous example to calculate the number of errors produced by each SKU. macro-expand 运算符用于引用 Greater 实体组（别名 X）。

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

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

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

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

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

Related content

• Entity groups
• join operator
• union operator
• .show entity_group（s） 命令
• current_database()
• current_cluster_endpoint()