Udostępnij za pośrednictwem


operator skanowania

Dotyczy: ✅Microsoft Fabric✅Azure Data ExplorerAzure MonitorMicrosoft Sentinel

Skanuje dane, dopasowania i kompiluje sekwencje na podstawie predykatów.

Zgodne rekordy są określane zgodnie z predykatami zdefiniowanymi w krokach operatora. Predykat może zależeć od stanu wygenerowanego przez poprzednie kroki. Dane wyjściowe pasującego rekordu są określane przez rekord wejściowy i przypisania zdefiniowane w krokach operatora.

Składnia

T | scan [ with_match_id = MatchIdColumnName ] [ declare ( ColumnDeclarations ] with ( StepDefinitions ) )

Składnia columnDeclarations

ColumnName : ColumnType[= DefaultValue ] [, ]

Składnia krokuDefinition

stepStepName [ output | = alllastnone | ] : Warunek [ => Przypisanie kolumny = [, ... ] ];

Dowiedz się więcej na temat konwencji składni.

Parametry

Nazwisko Type Wymagania opis
T string ✔️ Źródło tabelaryczne danych wejściowych.
MatchIdColumnName string Nazwa kolumny typu long , która jest dołączana do danych wyjściowych w ramach wykonywania skanowania. Wskazuje 0-oparty na indeksie dopasowania rekordu.
Dekodacje kolumn string Deklaruje rozszerzenie do schematu języka T. Te kolumny są przypisywane wartości w krokach. Jeśli nie zostanie przypisana, zostanie zwrócona wartość DefaultValue . Chyba że określono inaczej, wartość DefaultValue to null.
StepName string ✔️ Służy do odwołowania się do wartości w stanie skanowania pod kątem warunków i przypisań. Nazwa kroku musi być unikatowa.
Warunek string ✔️ Wyrażenie, które oblicza wartość true lub false określa, które rekordy z danych wejściowych są zgodne z krokiem. Rekord pasuje do kroku, gdy warunek jest true ze stanem kroku lub stanem poprzedniego kroku.
Przypisanie string Wyrażenie skalarne przypisane do odpowiedniej kolumny, gdy rekord pasuje do kroku.
output string Steruje logiką wyjściową kroku w przypadku powtarzających się dopasowań. all Zwraca wszystkie rekordy pasujące do kroku, last generuje tylko ostatni rekord w serii powtarzających się dopasowań dla kroku i none nie generuje rekordów wyjściowych pasujących do kroku. Wartość domyślna to all.

Zwraca

Rekord dla każdego dopasowania rekordu z danych wejściowych do kroku. Schemat danych wyjściowych jest schematem źródła rozszerzonego z kolumną w klauzuli declare .

Logika skanowania

scan przechodzi przez serializowane dane wejściowe, rejestruj według rekordu, porównując każdy rekord z warunkiem każdego kroku, biorąc pod uwagę bieżący stan każdego kroku.

Stan

Podstawowy stan scan operatora można traktować jako tabelę z wierszem dla każdego stepelementu . Każdy krok zachowuje swój własny stan z najnowszymi wartościami kolumn i zadeklarowanymi zmiennymi ze wszystkich poprzednich kroków i bieżącego kroku. W razie potrzeby przechowuje również identyfikator dopasowania dla trwającej sekwencji.

Jeśli operator skanowania ma n kroków o nazwie s_1, s_2, ..., s_n następnie krok s_k będzie miał k rekordów w stanie odpowiadającym s_1, s_2, ..., s_k. StepName.Format ColumnName służy do odwołowania się do wartości w stanie. Na przykład s_2.col1 odwołanie do kolumny col1 , która należy do kroku s_2 w stanie s_k. Szczegółowy przykład można znaleźć w przewodniku logiki skanowania.

Stan jest pusty i jest aktualizowany za każdym razem, gdy zeskanowany rekord wejściowy pasuje do kroku. Gdy stan bieżącego kroku nie jest żaden, krok jest określany jako mający aktywną sekwencję.

Dopasowywanie logiki

Każdy rekord wejściowy jest oceniany względem wszystkich kroków w odwrotnej kolejności, od ostatniego kroku do pierwszego. Gdy rekord r jest obliczany względem określonego kroku s_k, zostanie zastosowana następująca logika:

  • Sprawdź 1: Jeśli stan poprzedniego kroku (s_k-1) nie jest nieprawidłowy, a r spełnia warunek s_k, następuje dopasowanie. Dopasowanie prowadzi do następujących akcji:

    1. Stan s_k jest czyszczone.
    2. Stan s_k-1 jest promowany, aby stać się stanem s_k.
    3. Przypisania s_k są obliczane i rozszerzane r.
    4. Rozszerzony r jest dodawany do danych wyjściowych i do stanu s_k.

    Uwaga

    Jeśli sprawdzanie 1 powoduje dopasowanie, sprawdzanie 2 jest ignorowane, a r przechodzi do oceny względem s_k-1.

  • Sprawdź 2: Jeśli stan s_k ma aktywną sekwencję lub s_k jest pierwszym krokiem, a r spełnia warunek s_k, następuje dopasowanie. Dopasowanie prowadzi do następujących akcji:

    1. Przypisania s_k są obliczane i rozszerzane r.
    2. Wartości reprezentujące s_k w stanie s_k są zastępowane wartościami rozszerzonego r.
    3. Jeśli s_k jest zdefiniowana jako output=all, rozszerzony r zostanie dodany do danych wyjściowych.
    4. Jeśli s_k jest pierwszym krokiem, rozpoczyna się nowa sekwencja, a identyfikator dopasowania zwiększa się o 1. Ma to wpływ tylko na dane wyjściowe, gdy with_match_id jest używany.

Po zakończeniu sprawdzania s_k r przechodzi do oceny pod kątem s_k-1.

Szczegółowy przykład tej logiki można znaleźć w przewodniku logiki skanowania.

Przykłady

Suma skumulowana

Oblicz sumę skumulowaną dla kolumny wejściowej. Wynik tego przykładu jest odpowiednikiem użycia row_cumsum().

range x from 1 to 5 step 1 
| scan declare (cumulative_x:long=0) with 
(
    step s1: true => cumulative_x = x + s1.cumulative_x;
)

Wyjście

x cumulative_x
1 1
2 3
3 6
4 10
5 15

Suma zbiorcza dla wielu kolumn z warunkiem resetowania

Oblicz sumę skumulowaną dla dwóch kolumn wejściowych, zresetuj wartość sumy do bieżącej wartości rekordu, gdy suma skumulowana osiągnęła 10 lub więcej.

range x from 1 to 5 step 1
| extend y = 2 * x
| scan declare (cumulative_x:long=0, cumulative_y:long=0) with 
(
    step s1: true => cumulative_x = iff(s1.cumulative_x >= 10, x, x + s1.cumulative_x), 
                     cumulative_y = iff(s1.cumulative_y >= 10, y, y + s1.cumulative_y);
)

Wyjście

x t cumulative_x cumulative_y
1 2 1 2
2 4 3 6
3 6 6 12
4 8 10 8
5 10 5 18

Wypełnianie kolumny do przodu

Wypełnij kolumnę ciągu do przodu. Każda pusta wartość jest przypisywana ostatnio widziana wartość brak.

let Events = datatable (Ts: timespan, Event: string) [
    0m, "A",
    1m, "",
    2m, "B",
    3m, "",
    4m, "",
    6m, "C",
    8m, "",
    11m, "D",
    12m, ""
]
;
Events
| sort by Ts asc
| scan declare (Event_filled: string="") with 
(
    step s1: true => Event_filled = iff(isempty(Event), s1.Event_filled, Event);
)

Wyjście

Ts Zdarzenie Event_filled
00:00:00 A A
00:01:00 A
00:02:00 B B
00:03:00 B
00:04:00 B
00:06:00 C C
00:08:00 C
00:11:00 D D
00:12:00 D

Tagowanie sesji

Podziel dane wejściowe na sesje: sesja kończy się 30 minut po pierwszym zdarzeniu sesji, po którym rozpocznie się nowa sesja. Zwróć uwagę na użycie flagi with_match_id , która przypisuje unikatową wartość dla każdego unikatowego dopasowania (sesji ) skanowania. Zwróć również uwagę na specjalne użycie dwóch kroków w tym przykładzie, który ma true jako warunek, inSession dzięki czemu przechwytuje i generuje wszystkie rekordy z danych wejściowych, podczas gdy endSession przechwytuje rekordy, które mają miejsce ponad 30 m od sessionStart wartości bieżącego dopasowania. Krok endSession ma output=none znaczenie, że nie generuje rekordów wyjściowych. Krok endSession służy do przechodzenia stanu bieżącego dopasowania z inSession do endSession, co umożliwia rozpoczęcie nowego dopasowania (sesji) rozpoczynającego się od bieżącego rekordu.

let Events = datatable (Ts: timespan, Event: string) [
    0m, "A",
    1m, "A",
    2m, "B",
    3m, "D",
    32m, "B",
    36m, "C",
    38m, "D",
    41m, "E",
    75m, "A"
]
;
Events
| sort by Ts asc
| scan with_match_id=session_id declare (sessionStart: timespan) with 
(
    step inSession: true => sessionStart = iff(isnull(inSession.sessionStart), Ts, inSession.sessionStart);
    step endSession output=none: Ts - inSession.sessionStart > 30m;
)

Wyjście

Ts Zdarzenie sesjaStart session_id
00:00:00 A 00:00:00 0
00:01:00 A 00:00:00 0
00:02:00 B 00:00:00 0
00:03:00 D 00:00:00 0
00:32:00 B 00:32:00 1
00:36:00 C 00:32:00 1
00:38:00 D 00:32:00 1
00:41:00 E 00:32:00 1
01:15:00 A 01:15:00 2

Zdarzenia między uruchamianiem i zatrzymywaniem

Znajdź wszystkie sekwencje zdarzeń między zdarzeniem Start a zdarzeniem Stop , które występuje w ciągu 5 minut. Przypisz identyfikator dopasowania dla każdej sekwencji.

let Events = datatable (Ts: timespan, Event: string) [
    0m, "A",
    1m, "Start",
    2m, "B",
    3m, "D",
    4m, "Stop",
    6m, "C",
    8m, "Start",
    11m, "E",
    12m, "Stop"
]
;
Events
| sort by Ts asc
| scan with_match_id=m_id with 
(
    step s1: Event == "Start";
    step s2: Event != "Start" and Event != "Stop" and Ts - s1.Ts <= 5m;
    step s3: Event == "Stop" and Ts - s1.Ts <= 5m;
)

Wyjście

Ts Zdarzenie m_id
00:01:00 Rozpocznij 0
00:02:00 B 0
00:03:00 D 0
00:04:00 Zatrzymaj 0
00:08:00 Rozpocznij 1
00:11:00 E 1
00:12:00 Zatrzymaj 1

Obliczanie niestandardowego lejka zdarzeń

Oblicz ukończenie lejka sekwencji HailThunderstorm Wind>Tornado> za pomocą State progów niestandardowych w czasie między zdarzeniami (Tornado w obrębie i Thunderstorm Wind w obrębie ).1h 2h Ten przykład jest podobny do wtyczki funnel_sequence_completion, ale zapewnia większą elastyczność.

StormEvents
| partition hint.strategy=native by State 
    (
    sort by StartTime asc
    | scan with 
    (
        step hail: EventType == "Hail";
        step tornado: EventType == "Tornado" and StartTime - hail.StartTime <= 1h;
        step thunderstormWind: EventType == "Thunderstorm Wind" and StartTime - tornado.StartTime <= 2h;
    )
    )
| summarize dcount(State) by EventType

Wyjście

EventType dcount_State
Grad 50
Tornado 34
Wiatr i burza 32

Przewodnik po logice skanowania

W tej sekcji przedstawiono logikę skanowania przy użyciu szczegółowego przewodnika dotyczącego zdarzeń między rozpoczęciem i zatrzymaniem przykładu:

let Events = datatable (Ts: timespan, Event: string) [
    0m, "A",
    1m, "Start",
    2m, "B",
    3m, "D",
    4m, "Stop",
    6m, "C",
    8m, "Start",
    11m, "E",
    12m, "Stop"
]
;
Events
| sort by Ts asc
| scan with_match_id=m_id with 
(
    step s1: Event == "Start";
    step s2: Event != "Start" and Event != "Stop" and Ts - s1.Ts <= 5m;
    step s3: Event == "Stop" and Ts - s1.Ts <= 5m;
)

Stan

Pomyśl o stanie scan operatora jako tabeli z wierszem dla każdego kroku, w którym każdy krok ma swój własny stan. Ten stan zawiera najnowsze wartości kolumn i zadeklarowane zmienne ze wszystkich poprzednich kroków i bieżącego kroku. Aby dowiedzieć się więcej, zobacz Stan.

W tym przykładzie stan można przedstawić przy użyciu następującej tabeli:

step m_id s1. Ts s1. Zdarzenie s2. Ts s2. Zdarzenie s3. Ts s3. Zdarzenie
s1 X X X X
s2 X X
s3

Znak "X" wskazuje, że określone pole nie ma znaczenia dla tego kroku.

Zgodna logika

Ta sekcja jest zgodna z logiką poszczególnych rekordów Events tabeli, wyjaśniając przekształcenie stanu i danych wyjściowych w każdym kroku.

Uwaga

Rekord wejściowy jest oceniany względem kroków w odwrotnej kolejności, od ostatniego kroku (s3) do pierwszego kroku (s1).

Rekord 1

Ts Zdarzenie
0 m "A"

Ocena rekordów w każdym kroku:

  • s3: Sprawdzanie 1 nie zostało przekazane, ponieważ stan s2 jest pusty, a sprawdzanie 2 nie zostało przekazane, ponieważ s3 nie ma aktywnej sekwencji.
  • s2: Sprawdzanie 1 nie zostało przekazane, ponieważ stan s1 jest pusty, a sprawdzanie 2 nie zostało przekazane, ponieważ s2 nie ma aktywnej sekwencji.
  • s1: Sprawdź 1 nie ma znaczenia, ponieważ nie ma poprzedniego kroku. Sprawdzanie 2 nie zostało przekazane, ponieważ rekord nie spełnia warunku Event == "Start". Rekord 1 jest odrzucany bez wpływu na stan lub dane wyjściowe.

Stan:

step m_id s1. Ts s1. Zdarzenie s2. Ts s2. Zdarzenie s3. Ts s3. Zdarzenie
s1 X X X X
s2 X X
s3

Rekord 2

Ts Zdarzenie
1 min "Rozpocznij"

Ocena rekordów w każdym kroku:

  • s3: Sprawdzanie 1 nie zostało przekazane, ponieważ stan s2 jest pusty, a sprawdzanie 2 nie zostało przekazane, ponieważ s3 nie ma aktywnej sekwencji.
  • s2: Sprawdzanie 1 nie zostało przekazane, ponieważ stan s1 jest pusty, a sprawdzanie 2 nie zostało przekazane, ponieważ s2 nie ma aktywnej sekwencji.
  • s1: Sprawdź 1 nie ma znaczenia, ponieważ nie ma poprzedniego kroku. Sprawdzanie 2 jest przekazywane, ponieważ rekord spełnia warunek Event == "Start". To dopasowanie inicjuje nową sekwencję i jest przypisywana m_id . Rekord 2 i jego m_id (0) są dodawane do stanu i danych wyjściowych.

Stan:

step m_id s1. Ts s1. Zdarzenie s2. Ts s2. Zdarzenie s3. Ts s3. Zdarzenie
s1 0 00:01:00 "Rozpocznij" X X X X
s2 X X
s3

Rekord 3

Ts Zdarzenie
2 m "B"

Ocena rekordów w każdym kroku:

  • s3: Sprawdzanie 1 nie zostało przekazane, ponieważ stan s2 jest pusty, a sprawdzanie 2 nie zostało przekazane, ponieważ s3 nie ma aktywnej sekwencji.
  • s2: Sprawdzanie wartości 1 jest przekazywane, ponieważ stan parametru s1 nie ma wartości , a rekord spełnia warunek Ts - s1.Ts < 5m. To dopasowanie powoduje wyczyszczenie stanu s1 i sekwencję w s1 celu podwyższenia poziomu do s2. Rekord 3 i jego m_id (0) są dodawane do stanu i danych wyjściowych.
  • s1: Sprawdź 1 nie ma znaczenia, ponieważ nie ma poprzedniego Event == "Start"kroku, a sprawdzanie 2 nie zostało przekazane, ponieważ rekord nie spełnia warunku .

Stan:

step m_id s1. Ts s1. Zdarzenie s2. Ts s2. Zdarzenie s3. Ts s3. Zdarzenie
s1 X X X X
s2 0 00:01:00 "Rozpocznij" 00:02:00 "B" X X
s3

Rekord 4

Ts Zdarzenie
3 miesiące „D”

Ocena rekordów w każdym kroku:

  • s3: Sprawdzanie 1 nie zostało przekazane, ponieważ rekord nie spełnia warunku Event == "Stop", a sprawdzanie 2 nie zostało przekazane, ponieważ s3 nie ma aktywnej sekwencji.
  • s2: Sprawdzanie wartości 1 nie jest przekazywane, ponieważ stan s1 jest pusty. przekazuje wartość Check 2 , ponieważ spełnia warunek Ts - s1.Ts < 5m. Rekord 4 i jego m_id (0) są dodawane do stanu i danych wyjściowych. Wartości z tego rekordu zastępują poprzednie wartości stanu dla s2.Ts i s2.Event.
  • s1: Sprawdź 1 nie ma znaczenia, ponieważ nie ma poprzedniego Event == "Start"kroku, a sprawdzanie 2 nie zostało przekazane, ponieważ rekord nie spełnia warunku .

Stan:

step m_id s1. Ts s1. Zdarzenie s2. Ts s2. Zdarzenie s3. Ts s3. Zdarzenie
s1 X X X X
s2 0 00:01:00 "Rozpocznij" 00:03:00 „D” X X
s3

Rekord 5

Ts Zdarzenie
4 m "Zatrzymaj"

Ocena rekordów w każdym kroku:

  • s3: Sprawdzanie 1 jest przekazywane, ponieważ s2 nie ma wartości i spełnia s3 warunek Event == "Stop". To dopasowanie powoduje wyczyszczenie stanu s2 i sekwencję w s2 celu podwyższenia poziomu do s3. Rekord 5 i jego m_id (0) są dodawane do stanu i danych wyjściowych.
  • s2: Sprawdzanie 1 nie zostało przekazane, ponieważ stan s1 jest pusty, a sprawdzanie 2 nie zostało przekazane, ponieważ s2 nie ma aktywnej sekwencji.
  • s1: Sprawdź 1 nie ma znaczenia, ponieważ nie ma poprzedniego kroku. Sprawdzanie 2 nie zostało przekazane, ponieważ rekord nie spełnia warunku Event == "Start".

Stan:

step m_id s1. Ts s1. Zdarzenie s2. Ts s2. Zdarzenie s3. Ts s3. Zdarzenie
s1 X X X X
s2 X X
s3 0 00:01:00 "Rozpocznij" 00:03:00 „D” 00:04:00 "Zatrzymaj"

Rekord 6

Ts Zdarzenie
6 m "C"

Ocena rekordów w każdym kroku:

  • s3: Sprawdzanie wartości 1 nie jest przekazywane, ponieważ stan s2 jest pusty, a sprawdzanie 2 nie jest przekazywane, ponieważ s3 nie spełnia s3 warunku Event == "Stop".
  • s2: Sprawdzanie 1 nie zostało przekazane, ponieważ stan s1 jest pusty, a sprawdzanie 2 nie zostało przekazane, ponieważ s2 nie ma aktywnej sekwencji.
  • s1: Sprawdzanie 1 nie zostało przekazane, ponieważ nie ma poprzedniego Event == "Start"kroku, a sprawdzanie 2 nie zostało przekazane, ponieważ nie spełnia warunku . Rekord 6 jest odrzucany bez wpływu na stan lub dane wyjściowe.

Stan:

step m_id s1. Ts s1. Zdarzenie s2. Ts s2. Zdarzenie s3. Ts s3. Zdarzenie
s1 X X X X
s2 X X
s3 0 00:01:00 "Rozpocznij" 00:03:00 „D” 00:04:00 "Zatrzymaj"

Rekord 7

Ts Zdarzenie
8 m "Rozpocznij"

Ocena rekordów w każdym kroku:

  • s3: Sprawdzanie 1 nie zostało przekazane, ponieważ stan s2 jest pusty, a sprawdzanie 2 nie zostało przekazane, ponieważ nie spełnia warunku Event == "Stop".
  • s2: Sprawdzanie 1 nie zostało przekazane, ponieważ stan s1 jest pusty, a sprawdzanie 2 nie zostało przekazane, ponieważ s2 nie ma aktywnej sekwencji.
  • s1: Sprawdzanie 1 nie zostało przekazane, ponieważ nie ma poprzedniego kroku. przekazuje wartość Check 2 , ponieważ spełnia warunek Event == "Start". To dopasowanie inicjuje nową sekwencję przy s1 użyciu nowego m_idelementu . Rekord 7 i jego m_id (1) są dodawane do stanu i danych wyjściowych.

Stan:

step m_id s1. Ts s1. Zdarzenie s2. Ts s2. Zdarzenie s3. Ts s3. Zdarzenie
s1 1 00:08:00 "Rozpocznij" X X X X
s2 X X
s3 0 00:01:00 "Rozpocznij" 00:03:00 „D” 00:04:00 "Zatrzymaj"

Uwaga

Teraz istnieją dwie aktywne sekwencje w stanie .

Rekord 8

Ts Zdarzenie
11 m "E"

Ocena rekordów w każdym kroku:

  • s3: Sprawdzanie 1 nie zostało przekazane, ponieważ stan s2 jest pusty, a sprawdzanie 2 nie zostało przekazane, ponieważ nie spełnia s3 warunku Event == "Stop".
  • s2: Sprawdzanie wartości 1 jest przekazywane, ponieważ stan parametru s1 nie ma wartości , a rekord spełnia warunek Ts - s1.Ts < 5m. To dopasowanie powoduje wyczyszczenie stanu s1 i sekwencję w s1 celu podwyższenia poziomu do s2. Rekord 8 i jego m_id (1) są dodawane do stanu i danych wyjściowych.
  • s1: Sprawdź 1 nie ma znaczenia, ponieważ nie ma poprzedniego Event == "Start"kroku, a sprawdzanie 2 nie zostało przekazane, ponieważ rekord nie spełnia warunku .

Stan:

step m_id s1. Ts s1. Zdarzenie s2. Ts s2. Zdarzenie s3. Ts s3. Zdarzenie
s1 X X X X
s2 1 00:08:00 "Rozpocznij" 00:11:00 "E" X X
s3 0 00:01:00 "Rozpocznij" 00:03:00 „D” 00:04:00 "Zatrzymaj"

Rekord 9

Ts Zdarzenie
12 m "Zatrzymaj"

Ocena rekordów w każdym kroku:

  • s3: Sprawdzanie 1 jest przekazywane, ponieważ s2 nie ma wartości i spełnia s3 warunek Event == "Stop". To dopasowanie powoduje wyczyszczenie stanu s2 i sekwencję w s2 celu podwyższenia poziomu do s3. Rekord 9 i jego m_id (1) są dodawane do stanu i danych wyjściowych.
  • s2: Sprawdzanie 1 nie zostało przekazane, ponieważ stan s1 jest pusty, a sprawdzanie 2 nie zostało przekazane, ponieważ s2 nie ma aktywnej sekwencji.
  • s1: Sprawdzanie 1 nie zostało przekazane, ponieważ nie ma poprzedniego kroku. przekazuje wartość Check 2 , ponieważ spełnia warunek Event == "Start". To dopasowanie inicjuje nową sekwencję przy s1 użyciu nowego m_idelementu .

Stan:

step m_id s1. Ts s1. Zdarzenie s2. Ts s2. Zdarzenie s3. Ts s3. Zdarzenie
s1 X X X X
s2 X X
s3 1 00:08:00 "Rozpocznij" 00:11:00 "E" 00:12:00 "Zatrzymaj"

Końcowe dane wyjściowe

Ts Zdarzenie m_id
00:01:00 Rozpocznij 0
00:02:00 B 0
00:03:00 D 0
00:04:00 Zatrzymaj 0
00:08:00 Rozpocznij 1
00:11:00 E 1
00:12:00 Zatrzymaj 1