pattern 语句pattern statement

模式是一种命名视图样式的构造,用于将预定义的字符串元组映射到无参数函数正文。A pattern is a named view-like construct that maps predefined string tuples to parameterless function bodies. 模式在两个方面是独一无二的:Patterns are unique in two aspects:

  • “调用”模式时使用的语法类似于具有作用域的表引用。Patterns are "invoked" by using a syntax that resembles scoped table references.
  • 模式具有一组可以映射的受控封闭式参数值,映射过程由 Kusto 完成。Patterns have a controlled, close-ended, set of argument values that can be mapped, and the mapping process is done by Kusto. 如果声明了某个模式但未定义它,则 Kusto 会识别对该模式的所有调用并将其标记为错误。If a pattern is declared but not defined, Kusto identifies and flags all invocations to the pattern as errors. 进行此识别后,中间层应用程序可以“解析”这些模式。This identification makes it possible to "resolve" these patterns by a middle-tier application.

模式声明Pattern declaration

pattern 语句用来声明或定义模式。The pattern statement is used to declare or define a pattern. 例如,某个 pattern 语句将 app 声明为模式。For example, a pattern statement that declares app to be a pattern.

declare pattern app;

此语句告诉 Kusto app 是一种模式,但并未告诉 Kusto 如何解析该模式。This statement tells Kusto that app is a pattern, but doesn't tell Kusto how to resolve the pattern. 因此,在查询中调用此模式的任何尝试都会导致特定的错误,并会列出所有此类调用。As a result, any attempt to invoke this pattern in the query will result in a specific error, and will list all such invocations. 例如:For example:

declare pattern app;
app("ApplicationX").StartEvents
| join kind=inner app("ApplicationX").StopEvents on CorrelationId
| count

此查询会在 Kusto 中生成错误,指示无法解析接下来的模式调用:app("ApplicationX")["StartEvents"]app("ApplicationX")["StopEvents"]This query will generate an error from Kusto, indicating that the next pattern invocations can't be resolved: app("ApplicationX")["StartEvents"] and app("ApplicationX")["StopEvents"].

语法Syntax

declare pattern PatternNamedeclare pattern PatternName

模式定义Pattern definition

pattern 语句还可以用来定义模式。The pattern statement can also be used to define a pattern. 在模式定义中,所有可能的模式调用都被显式列出,并给出相应的表格表达式。In a pattern definition, all possible invocations of the pattern are explicitly laid out, and the corresponding tabular expression given. 然后,当 Kusto 执行查询时,它会将每个模式调用替换为对应的模式正文。When Kusto then executes the query, it replaces each pattern invocation with the corresponding pattern body. 例如:For example:

declare pattern app = (applicationId:string)[eventType:string]
{
    ("ApplicationX").["StopEvents"] = { database("AppX").Events | where EventType == "StopEvent" };
    ("ApplicationX").["StartEvents"] = { database(applicationId).Events | where EventType == eventType } ;
};
app("ApplicationX").StartEvents
| join kind=inner app("ApplicationX").StopEvents on CorrelationId
| count

为每个匹配的模式提供的表达式是表名或对 let 语句的引用。The expression that is provided for each pattern that is matched, is either a table name or a reference to a let statement.

语法Syntax

declare pattern PatternName = (ArgName : ArgType [, ... ]) [[ PathName : PathArgType ]] {declare pattern PatternName = (ArgName : ArgType [, ... ]) [[ PathName : PathArgType ]] {      ( ArgValue1 [, ArgValue2 ... ] ) [ .[ *PathValue ] ] = { expression };      [      ( ArgValue1_2 [, ArgValue2_2 ... ] ) [ .[ PathValue_2 ] ] = { expression_2 };      ...      ] }     ( ArgValue1 [, ArgValue2 ... ] ) [ .[ *PathValue ] ] = { expression };      [      ( ArgValue1_2 [, ArgValue2_2 ... ] ) [ .[ PathValue_2 ] ] = { expression_2 };      ...      ] }

  • PatternName:模式关键字的名称。PatternName: Name of the pattern keyword. 仅允许使用定义关键字的语法:用于检测具有指定关键字的所有模式引用。Syntax that defines keyword only is allowed: for detecting all pattern references with a specified keyword.
  • ArgName:模式参数的名称。ArgName: Name of the pattern argument. 模式允许一个或多个参数名称。Patterns allow one or more argument names.
  • ArgType:模式参数的类型(当前仅允许 stringArgType: Type of the pattern argument (currently only string is allowed)
  • PathName:路径参数的名称。PathName: Name of the path argument. 模式允许零个或一个路径名称。Patterns allow zero or one path name.
  • PathType:路径参数的类型(当前仅允许 stringPathType: Type of the path argument (currently only string is allowed)
  • ArgValue1, ArgValue2, ... - 模式参数的值(当前仅允许 string 文本)ArgValue1, ArgValue2, ... - values of the pattern arguments (currently only string literals are allowed)
  • PathValue - 模式路径的值(当前仅允许 string 文本)PathValue - value of the pattern path (currently only string literals are allowed)
  • expression:expression 为表格表达式(例如 Logs | where Timestamp > ago(1h)),或者为引用某个函数的 lambda 表达式。expression: The expression - a tabular expression (for example, Logs | where Timestamp > ago(1h)), or a lambda expression that references a function.

模式调用Pattern invocation

模式调用语法类似于具有作用域的表引用语法。The pattern invocation syntax is similar to the scoped table reference syntax.

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

说明Notes

方案Scenario

pattern 语句是针对中间层应用程序设计的,这类应用程序接受用户查询然后将这些查询发送到 Kusto。The pattern statement is designed for middle-tier applications that accept user queries and then send these queries to Kusto. 这类应用程序通常以逻辑架构模型作为那些用户查询的前缀。Such applications often prefix those user queries with a logical schema model. 模型是一组 let 语句,可能以某个 restrict 语句作为后缀。The model is a set of let statements, possibly suffixed by a restrict statement.

某些应用程序需要可以为用户提供的语法。Some applications need a syntax that they can provide users. 语法用来引用在应用程序构造的逻辑架构中定义的实体。The syntax is used to reference entities that are defined in the logical schema that the applications construct. 但是,有时不会提前知道实体,或者潜在的实体数量太大,无法在逻辑架构中预定义。However, sometimes entities aren't known ahead of time, or the number of potential entities is too large to be pre-defined in the logical schema.

模式通过以下方式解决了这种情况。Pattern solves this scenario in the following way. 中间层应用程序将查询发送到 Kusto,并声明所有模式,但不定义。The middle-tier application sends the query to Kusto with all patterns declared, but not defined. 然后,Kusto 分析该查询。Kusto then parses the query. 如果有一个或多个模式调用,则 Kusto 会向中间层应用程序返回一个错误,其中会显式列出所有此类调用。If there are one or more pattern invocations, Kusto returns an error to the middle-tier application with all such invocations explicitly listed. 然后,中间层应用程序可以解析每个引用,然后重新运行查询。The middle-tier application can then resolve each of these references, and rerun the query. 这次将添加完整的细化模式定义作为前缀。This time, prefixing it with the fully elaborated pattern definition.

规范化Normalizations

Kusto 会自动将模式规范化。Kusto automatically normalizes the pattern. 例如,下面是对同一模式的所有调用,并报告了单个模式。For example, the following are all invocations of the same pattern, and a single one is reported back.

declare pattern app;
union
  app("ApplicationX").StartEvent,
  app('ApplicationX').StartEvent,
  app("ApplicationX").['StartEvent'],
  app("ApplicationX").["StartEvent"]

这也意味着,不能将它们一起定义,因为它们被视为是同一个。This also means that you can't define them together, since they're considered to be the same.

通配符Wildcards

Kusto 不会以任何特殊方式对模式中的通配符进行处理。Kusto doesn't treat wildcards in a pattern in any special way. 例如,在以下查询中:For example, in the following query.

declare pattern app;
union app("ApplicationX").*
| count

Kusto 会报告单个缺少的模式调用:app("ApplicationX").["*"]Kusto will report a single missing pattern invocation: app("ApplicationX").["*"].

示例Examples

基于多个模式调用进行查询。Queries over more than a single pattern invocation.

declare pattern A
{
    // ...
};
union (A('a1').Text), (A('a2').Text)
应用App SomeTextSomeText
应用 #1App #1 这是一个自由文本:1This is a free text: 1
应用 #1App #1 这是一个自由文本:2This is a free text: 2
应用 #1App #1 这是一个自由文本:3This is a free text: 3
应用 #1App #1 这是一个自由文本:4This is a free text: 4
应用 #1App #1 这是一个自由文本:5This is a free text: 5
应用 #2App #2 这是一个自由文本:9This is a free text: 9
应用 #2App #2 这是一个自由文本:8This is a free text: 8
应用 #2App #2 这是一个自由文本:7This is a free text: 7
应用 #2App #2 这是一个自由文本:6This is a free text: 6
应用 #2App #2 这是一个自由文本:5This is a free text: 5
declare pattern App;
union (App('a1').Text), (App('a2').Text)

语义错误Semantic error:

 SEM0036: One or more pattern references weren't declared. Detected pattern references: ["App('a1').['Text']","App('a2').['Text']"].
declare pattern App;
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').Metrics), (App('a3').Metrics) 

返回了语义错误Semantic error returned:

SEM0036: One or more pattern references weren't declared. Detected pattern references: ["App('a2').['Metrics']","App('a3').['Metrics']"].

Azure Monitor 不支持此功能This capability isn't supported in Azure Monitor