Pattern statement

Applies to: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

A pattern is a construct that maps string tuples to tabular expressions.

Each pattern must declare a pattern name and optionally define a pattern mapping. 定义映射的模式在调用时返回表格表达式。 用分号分隔任意两个语句。

空模式是声明但未定义映射的模式。 When invoked, they return error SEM0036 along with the details of the missing pattern definitions in the HTTP header.

提供 Kusto 查询语言（KQL）体验的中间层应用程序可以使用返回的详细信息作为其过程的一部分来扩充 KQL 查询结果。 有关详细信息，请参阅 使用中间层应用程序。

Syntax

• 声明空模式：

  declare pattern PatternName;

• 声明和定义模式：

  declare pattern PatternName = (ArgName:ArgType [, ... ]) [[PathName:PathArgType]]

  {

         ( ArgValue1_1 [,ArgValue2_1, ... ] ) [ .[PathValue_1] ] ={expression1};

      [ (ArgValue1_2 [,ArgValue2_2, ... ] ) [ .[PathValue_2] ] ={expression2}; ... ]

  } ;

• 调用模式：

  • PatternName(ArgValue1 [,ArgValue2 ...] ).PathValue
  • PatternName(ArgValue1 [,ArgValue2 ...] ).["PathValue"]

Learn more about syntax conventions.

Parameters

Examples

本节中的示例演示如何使用语法帮助你入门。

定义简单模式

此示例定义一种模式，该模式将状态映射到返回其首都/主要城市的表达式。

declare pattern country = (name:string)[state:string]
{
  ("USA").["New York"] = { print Capital = "Albany" };
  ("USA").["Washington"] = { print Capital = "Olympia" };
  ("Canada").["Alberta"] = { print Capital = "Edmonton" };
};
country("Canada").Alberta

Output

定义作用域内模式

此示例定义了一个模式来限定应用程序数据的数据和指标的范围。 调用该模式以返回数据的并集。

declare pattern App = (applicationId:string)[scope:string]
{
    ('a1').['Data']    = { range x from 1 to 5 step 1 | project App = "App #1", Data    = x };
    ('a1').['Metrics'] = { range x from 1 to 5 step 1 | project App = "App #1", Metrics = rand() };
    ('a2').['Data']    = { range x from 1 to 5 step 1 | project App = "App #2", Data    = 10 - x };
    ('a3').['Metrics'] = { range x from 1 to 5 step 1 | project App = "App #3", Metrics = rand() };
};
union App('a2').Data, App('a1').Metrics

Output

Normalization

调用模式有语法变体。 例如，以下联合返回单个模式表达式，因为所有调用都是相同的模式。

declare pattern app = (applicationId:string)[eventType:string]
{
    ("ApplicationX").["StopEvents"] = { database("AppX").Events | where EventType == "StopEvent" };
    ("ApplicationX").["StartEvents"] = { database("AppX").Events | where EventType == "StartEvent" };
};
union
  app("ApplicationX").StartEvents,
  app('ApplicationX').StartEvents,
  app("ApplicationX").['StartEvents'],
  app("ApplicationX").["StartEvents"]

No wildcards

模式中没有对通配符进行特殊处理。 例如，以下查询返回单个缺失的模式调用。

declare pattern app = (applicationId:string)[eventType:string]
{
    ("ApplicationX").["StopEvents"] = { database("AppX").Events | where EventType == "StopEvent" };
    ("ApplicationX").["StartEvents"] = { database("AppX").Events | where EventType == "StartEvent" };
};
union app("ApplicationX").["*"]
| count

输出语义错误

未声明一个或多个模式引用。 检测到的模式引用：[“app（'ApplicationX'）。['*']"]

使用中间层应用程序

中间层应用程序为用户提供了使用 KQL 的能力，并希望通过从其内部服务扩充查询结果来增强体验。

为此，应用程序为用户提供了一个模式语句，该语句返回其用户可以在其查询中使用的表格数据。 模式的参数是应用程序用于检索扩充数据的键。

当用户运行查询时，应用程序不会分析查询本身，而是使用空模式返回的错误来检索它所需的密钥。 因此，它将查询前面带有空模式声明，将其发送到群集进行处理，然后分析返回的 HTTP 标头以检索缺少的模式参数的值。 应用程序使用这些值来查找扩充数据，并生成一个新声明来定义适当的扩充数据映射。

最后，应用程序将新定义追加到查询前面，重新发送它进行处理，并返回它向用户接收的结果。

Example

在示例中，声明、定义并调用模式。

声明空模式

在此示例中，中间层应用程序使用经度/纬度位置扩充查询。 应用程序使用内部服务将 IP 地址映射到经度/纬度位置，并提供称为 map_ip_to_longlat的模式。 运行查询时，它将返回缺少模式定义的错误：

map_ip_to_longlat("10.10.10.10")

声明和定义模式

The application does not parse this query and hence does not know which IP address (10.10.10.10) was passed to the pattern. 因此，它会使用空的 map_ip_to_longlat 模式声明追加用户查询，并发送它进行处理：

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

应用程序在响应中收到以下错误。

未声明一个或多个模式引用。 检测到的模式引用：[“map_ip_to_longlat（'10.10.10.10'）”]

调用模式

The application inspects the error, determines that the error indicates a missing pattern reference, and retrieves the missing IP address (10.10.10.10). 它使用 IP 地址在其内部服务中查找扩充数据，并构建一种新模式，用于定义 IP 地址与相应经度和纬度数据的映射。 新模式将追加到用户的查询前面，然后再次运行。

这次查询成功，因为扩充数据现在在查询中声明，结果将发送给用户。

declare pattern map_ip_to_longlat = (address:string)
{
  ("10.10.10.10") = { print Lat=37.405992, Long=-122.078515 };
};
map_ip_to_longlat("10.10.10.10")

Output