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. Wzorce definiujące mapowanie zwracają wyrażenie tabelaryczne podczas wywoływania. Rozdziel wszystkie dwie instrukcje średnikami.

Puste wzorce to wzorce zadeklarowane, ale nie definiują mapowania. When invoked, they return error SEM0036 along with the details of the missing pattern definitions in the HTTP header.

Aplikacje warstwy środkowej, które zapewniają środowisko języka KQL (Kusto Query Language), mogą używać zwróconych szczegółów w ramach procesu w celu wzbogacania wyników zapytań języka KQL. Aby uzyskać więcej informacji, zobacz Praca z aplikacjami warstwy środkowej.

Syntax

• Zadeklaruj pusty wzorzec:

  declare pattern PatternName;

• Deklarowanie i definiowanie wzorca:

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

  {

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

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

  } ;

• Wywołaj wzorzec:

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

Learn more about syntax conventions.

Parameters

Examples

W przykładach w tej sekcji pokazano, jak używać składni, aby ułatwić rozpoczęcie pracy.

Definiowanie prostego wzorca

W tym przykładzie zdefiniowano wzorzec mapujący stany na wyrażenie zwracające jego stolicę/główne miasto.

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

Definiowanie wzorca o określonym zakresie

W tym przykładzie zdefiniowano wzorzec określający zakres danych i metryk danych aplikacji. Wzorzec jest wywoływany w celu zwrócenia unii danych.

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

Istnieją odmiany składni dotyczące wywoływania wzorców. Na przykład następująca unia zwraca pojedyncze wyrażenie wzorca, ponieważ wszystkie wywołania są tego samego wzorca.

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

Nie ma specjalnego traktowania dla symboli wieloznacznych w wzorcu. Na przykład następujące zapytanie zwraca jedno brakujące wywołanie wzorca.

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

błąd semantyczny danych wyjściowych

Nie zadeklarowano co najmniej jednego odwołania do wzorca. Wykryte odwołania do wzorca: ["app('ApplicationX').[" *']"]

Praca z aplikacjami warstwy środkowej

Aplikacja warstwy środkowej zapewnia swoim użytkownikom możliwość korzystania z języka KQL i chce ulepszyć środowisko, wzbogacając wyniki zapytania o rozszerzone dane z wewnętrznej usługi.

W tym celu aplikacja udostępnia użytkownikom instrukcję wzorca zwracającą dane tabelaryczne, których użytkownicy mogą używać w zapytaniach. Argumenty wzorca to klucze, których aplikacja będzie używać do pobierania danych wzbogacania.

Gdy użytkownik uruchamia zapytanie, aplikacja nie analizuje samego zapytania, ale używa błędu zwróconego przez pusty wzorzec, aby pobrać wymagane klucze. Dlatego poprzedza zapytanie z pustą deklaracją wzorca, wysyła je do klastra do przetwarzania, a następnie analizuje zwrócony nagłówek HTTP, aby pobrać wartości brakujących argumentów wzorca. Aplikacja używa tych wartości do wyszukiwania danych wzbogacania i tworzy nową deklarację, która definiuje odpowiednie mapowanie danych wzbogacania.

Na koniec aplikacja poprzedza nową definicję zapytania, ponownie wysyła ją do przetwarzania i zwraca wynik otrzymany do użytkownika.

Example

W przykładach wzorzec jest zadeklarowany, zdefiniowany, a następnie wywoływany.

Deklarowanie pustego wzorca

W tym przykładzie aplikacja warstwy środkowej wzbogaca zapytania o lokalizacje długości/szerokości geograficznej. Aplikacja używa usługi wewnętrznej do mapowania adresów IP na lokalizacje długości/szerokości geograficznej i udostępnia wzorzec o nazwie map_ip_to_longlat. Po uruchomieniu zapytania zwraca błąd z brakującymi definicjami wzorca:

map_ip_to_longlat("10.10.10.10")

Deklarowanie i definiowanie wzorca

The application does not parse this query and hence does not know which IP address (10.10.10.10) was passed to the pattern. Dlatego poprzedza zapytanie użytkownika pustą deklaracją wzorca map_ip_to_longlat i wysyła je do przetwarzania:

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

Aplikacja otrzymuje następujący błąd w odpowiedzi.

Nie zadeklarowano co najmniej jednego odwołania do wzorca. Wykryte odwołania do wzorca: ["map_ip_to_longlat('10.10.10.10')"]

Wywoływanie wzorca

The application inspects the error, determines that the error indicates a missing pattern reference, and retrieves the missing IP address (10.10.10.10). Używa ona adresu IP do wyszukiwania danych wzbogacania w usłudze wewnętrznej i tworzy nowy wzorzec definiujący mapowanie adresu IP na odpowiednie dane długości geograficznej i szerokości geograficznej. Nowy wzorzec jest poprzedzany zapytaniem użytkownika i uruchamiany ponownie.

Tym razem zapytanie powiedzie się, ponieważ dane wzbogacania są teraz zadeklarowane w zapytaniu, a wynik jest wysyłany do użytkownika.

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