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. マッピングを定義するパターンは、呼び出されると表形式の式を返します。 任意の 2 つのステートメントをセミコロンで区切ります。

空のパターンは、宣言されているがマッピングを定義しないパターンです。 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

パターンを呼び出すための構文のバリエーションがあります。 たとえば、次の共用体は、すべての呼び出しが同じパターンであるため、1 つのパターン式を返します。

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

パターン内のワイルドカードには特別な扱いはありません。 たとえば、次のクエリでは、不足しているパターン呼び出しが 1 つ返されます。

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

出力セマンティック エラー

1 つ以上のパターン参照が宣言されませんでした。 検出されたパターン参照: ["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")

アプリケーションは、応答として次のエラーを受け取ります。

1 つ以上のパターン参照が宣言されませんでした。 検出されたパターン参照: ["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