Pattern ステートメント

適用対象: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

パターン は、文字列タプルを表形式の式にマップするコンストラクトです。

各パターン パターン名 宣言し、必要に応じてパターン マッピング 定義 必要があります。 マッピングを定義するパターンは、呼び出されると表形式の式を返します。 任意の 2 つのステートメントをセミコロンで区切ります。

空のパターンは、宣言されているがマッピングを定義しないパターンです。 呼び出されると、エラー SEM0036 と、HTTP ヘッダーに存在しないパターン定義の詳細が返されます。

Kusto クエリ言語 (KQL) エクスペリエンスを提供する中間層アプリケーションでは、返された詳細をプロセスの一部として使用して、KQL クエリ結果を強化できます。 詳細については、「中間層アプリケーションの使用」を参照してください。

構文

• 空のパターンを宣言します。

  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"]

構文規則の詳細について説明します。

パラメーター

名前	種類	必須	形容
PatternName	string	✔️	パターンの名前。
ArgName を する	string	✔️	引数の名前。 パターンには、1 つ以上の引数を指定できます。
ArgType を する	string	✔️	ArgName 引数のスカラー データ型。 使用可能な値: string
PathName	string		path 引数の名前。 パターンには、パスまたは 1 つのパスを指定することはできません。
PathArgType	string		PathArgType 引数の型。 使用可能な値: string
ArgValue を する	string	✔️	ArgName と省略可能な PathName、式にマップされるタプル値です。
PathValue の	string		PathNameにマップする値。
式	string	✔️	表形式データを返す関数を参照する表形式またはラムダ式。 例: Logs | where Timestamp > ago(1h)

例

このセクションの例では、構文を使用して作業を開始する方法を示します。

この記事の例では、Weather Analytics StormEventsの テーブルなど、一般公開されているテーブルを使用します。

単純なパターンを定義する

この例では、州を、首都/大都市を返す式にマップするパターンを定義します。

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

出力

資本
エドモントン

スコープ付きパターンを定義する

この例では、アプリケーション データのデータとメトリックのスコープを設定するパターンを定義します。 このパターンは、データの和集合を返すために呼び出されます。

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

出力

アプリ	データ	メトリック
アプリ #2	9
アプリ #2	8
アプリ #2	7
アプリ #2	6
アプリ #2	5
アプリ #1		0.53674122855537532
アプリ #1		0.78304713305654439
アプリ #1		0.20168860732346555
アプリ #1		0.13249123867679469
アプリ #1		0.19388305330563443

正常化

パターンを呼び出すための構文のバリエーションがあります。 たとえば、次の共用体は、すべての呼び出しが同じパターンであるため、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"]

ワイルドカードなし

パターン内のワイルドカードには特別な扱いはありません。 たとえば、次のクエリでは、不足しているパターン呼び出しが 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 ヘッダーを解析して、不足しているパターン引数の値を取得します。 アプリケーションでは、これらの値を使用してエンリッチメント データを検索し、適切なエンリッチメント データ マッピングを定義する新しい宣言を作成します。

最後に、アプリケーションは新しい定義をクエリの先頭に追加し、処理のために再送信し、受信した結果をユーザーに返します。

例

例では、パターンが宣言され、定義され、呼び出されます。

空のパターンを宣言する

この例では、中間層アプリケーションは、経度/緯度の場所を使用してクエリを強化します。 アプリケーションは、内部サービスを使用して IP アドレスを経度/緯度の場所にマップし、map_ip_to_longlatというパターンを提供します。 クエリを実行すると、パターン定義が見つからないエラーが返されます。

map_ip_to_longlat("10.10.10.10")

パターンを宣言して定義する

アプリケーションはこのクエリを解析しないため、パターンに渡された IP アドレス (10.10.10.10) がわかりません。 そのため、空の 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')"]

パターンを呼び出す

アプリケーションはエラーを検査し、エラーがパターン参照が見つからないことを示し、不足している IP アドレス (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")

出力

Lat	Long
37.405992	-122.078515