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. Muster, die eine Zuordnung definieren, geben beim Aufrufen einen tabellarischen Ausdruck zurück. Trennen Sie zwei beliebige Anweisungen durch ein Semikolon.

Leere Muster sind Muster, die deklariert werden, aber keine Zuordnung definieren. When invoked, they return error SEM0036 along with the details of the missing pattern definitions in the HTTP header.

Middle-Tier-Anwendungen, die eine Kusto Query Language (KQL)-Erfahrung bereitstellen, können die zurückgegebenen Details als Teil ihres Prozesses verwenden, um KQL-Abfrageergebnisse zu erweitern. Weitere Informationen finden Sie unter Arbeiten mit Anwendungen auf mittlerer Ebene.

Syntax

• Deklarieren Sie ein leeres Muster:

  declare pattern PatternName;

• Deklarieren und Definieren eines Musters:

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

  {

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

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

  } ;

• Aufrufen eines Musters:

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

Learn more about syntax conventions.

Parameters

Name	Type	Required	Description
PatternName	string	✔️	Der Name des Musters.
ArgName	string	✔️	Der Name des Arguments. Muster können ein oder mehrere Argumente enthalten.
ArgType	string	✔️	The scalar data type of the ArgName argument. Mögliche Werte: string
PathName	string		Der Name des Pfadarguments. Muster können keinen Pfad oder einen Pfad haben.
PathArgType	string		The type of the PathArgType argument. Mögliche Werte: string
ArgValue	string	✔️	The ArgName and optional PathName tuple values to be mapped to an expression.
PathValue	string		The value to map for PathName.
expression	string	✔️	Ein tabellarischer oder Lambda-Ausdruck, der auf eine Funktion verweist, die tabellarische Daten zurückgibt. Beispiel: Logs | where Timestamp > ago(1h)

Examples

Die Beispiele in diesem Abschnitt zeigen, wie Sie die Syntax verwenden, um Ihnen den Einstieg zu erleichtern.

The examples in this article use publicly available tables, such as the Weather table in the Weather analytics sample gallery. Möglicherweise müssen Sie den Tabellennamen in der Beispielabfrage so ändern, dass er der Tabelle in Ihrem Arbeitsbereich entspricht.

Definieren eines einfachen Musters

In diesem Beispiel wird ein Muster definiert, das Zustände einem Ausdruck zuordnet, der seine Hauptstadt/Hauptstadt zurückgibt.

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

Capital
Edmonton

Definieren eines bereichsbezogenen Musters

In diesem Beispiel wird ein Muster zum Bereich von Daten und Metriken von Anwendungsdaten definiert. Das Muster wird aufgerufen, um eine Vereinigung der Daten zurückzugeben.

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

App	Data	Metrics
App #2	9
App #2	8
App #2	7
App #2	6
App #2	5
App #1		0.53674122855537532
App #1		0.78304713305654439
App #1		0.20168860732346555
App #1		0.13249123867679469
App #1		0.19388305330563443

Normalization

Es gibt Syntaxvariationen für das Aufrufen von Mustern. Beispielsweise gibt die folgende Union einen einzelnen Musterausdruck zurück, da alle Aufrufe dasselbe Muster aufweisen.

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

Es gibt keine spezielle Behandlung für Wildcards in einem Muster. Die folgende Abfrage gibt beispielsweise einen einzelnen fehlenden Musteraufruf zurück.

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

Ausgabesemantikfehler

Mindestens ein Musterverweise wurden nicht deklariert. Erkannte Musterverweise: ["app('ApplicationX').[' *']"]

Arbeiten mit Anwendungen auf mittlerer Ebene

Eine Anwendung auf mittlerer Ebene bietet ihren Benutzern die Möglichkeit, KQL zu verwenden und die Erfahrung zu verbessern, indem sie die Abfrageergebnisse mit erweiterten Daten aus dem internen Dienst bereichern.

Zu diesem Zweck stellt die Anwendung Benutzern eine Muster-Anweisung bereit, die tabellarische Daten zurückgibt, die ihre Benutzer in ihren Abfragen verwenden können. Die Argumente des Musters sind die Schlüssel, die die Anwendung zum Abrufen der Anreicherungsdaten verwendet.

Wenn der Benutzer die Abfrage ausführt, analysiert die Anwendung die Abfrage nicht selbst, sondern verwendet stattdessen den von einem leeren Muster zurückgegebenen Fehler, um die benötigten Schlüssel abzurufen. Daher stellt sie die Abfrage der leeren Musterdeklaration voran, sendet sie zur Verarbeitung an den Cluster und analysiert dann den zurückgegebenen HTTP-Header, um die Werte fehlender Musterargumente abzurufen. Die Anwendung verwendet diese Werte, um die Anreicherungsdaten nachzuschlagen, und erstellt eine neue Deklaration, die die entsprechende Anreicherungsdatenzuordnung definiert.

Schließlich stellt die Anwendung der Abfrage die neue Definition voran, sendet sie erneut zur Verarbeitung und gibt das Ergebnis zurück, das sie an den Benutzer erhält.

Example

In den Beispielen wird ein Muster deklariert, definiert und anschließend aufgerufen.

Deklarieren eines leeren Musters

In diesem Beispiel erweitert eine Anwendung auf mittlerer Ebene Abfragen mit Längen-/Breitengradpositionen. Die Anwendung verwendet einen internen Dienst zum Zuordnen von IP-Adressen zu Längen-/Breitengradstandorten und stellt ein Muster namens map_ip_to_longlatbereit. Wenn die Abfrage ausgeführt wird, wird ein Fehler mit fehlenden Musterdefinitionen zurückgegeben:

map_ip_to_longlat("10.10.10.10")

Deklarieren und Definieren eines Musters

The application does not parse this query and hence does not know which IP address (10.10.10.10) was passed to the pattern. Daher wird der Benutzerabfrage eine leere map_ip_to_longlat Musterdeklaration vorangestellt und zur Verarbeitung gesendet:

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

Die Anwendung empfängt den folgenden Fehler als Antwort.

Mindestens ein Musterverweise wurden nicht deklariert. Erkannte Musterverweise: ["map_ip_to_longlat('10.10.10.10')"]

Aufrufen eines Musters

The application inspects the error, determines that the error indicates a missing pattern reference, and retrieves the missing IP address (10.10.10.10). Es verwendet die IP-Adresse, um die Anreicherungsdaten in seinem internen Dienst nachzuschlagen und ein neues Muster zu erstellen, das die Zuordnung der IP-Adresse zu den entsprechenden Längengrad- und Breitengraddaten definiert. Das neue Muster wird der Abfrage des Benutzers vorangestellt und erneut ausgeführt.

Dieses Mal ist die Abfrage erfolgreich, da die Anreicherungsdaten jetzt in der Abfrage deklariert sind und das Ergebnis an den Benutzer gesendet wird.

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

Lat	Long
37.405992	-122.078515