Dela via

skanningsoperator

  • Artikel

Gäller för: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Söker igenom data, matchar och bygger sekvenser baserat på predikaten.

Matchande poster bestäms enligt predikat som definieras i operatorns steg. Ett predikat kan bero på tillståndet som genereras av föregående steg. Utdata för matchande post bestäms av indataposten och tilldelningarna som definieras i operatorns steg.

Syntax

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

ColumnDeclarations syntax

ColumnName:ColumnType[=DefaultValue ] [, ... ]

StepDefinition syntax

step StepName [ output = all | last | none] :Condition [ =>Column=Assignment [, ... ] ] ] ;

Läs mer om syntaxkonventioner.

Parametrar

Namn Typ Krävs Beskrivning
T string ✔️ Tabellkällan för indata.
MatchIdColumnName string Namnet på en kolumn av typen long som läggs till i utdata som en del av genomsökningskörningen. Anger det 0-baserade indexet för matchningen för posten.
ColumnDeclarations string Deklarerar ett tillägg till schemat för T-. Dessa kolumner tilldelas värden i stegen. Om den inte tilldelas returneras DefaultValue-. Om inget annat anges är DefaultValuenull.
StepName string ✔️ Används för att referera till värden i genomsökningstillståndet för villkor och tilldelningar. Stegnamnet måste vara unikt.
Villkor string ✔️ Ett uttryck som utvärderas till true eller false som definierar vilka poster från indata som matchar steget. En post matchar steget när villkoret är true med stegets tillstånd eller med föregående stegs tillstånd.
Tilldelning string Ett skalärt uttryck som tilldelas motsvarande kolumn när en post matchar ett steg.
output string Styr utdatalogik för steget vid upprepade matchningar. all matar ut alla poster som matchar steget, last endast matar ut den sista posten i en serie upprepade matchningar för steget, och none matar inte ut poster som matchar steget. Standardvärdet är all.

Returnerar

En post för varje matchning av en post från indata till ett steg. Schemat för utdata är schemat för källan som utökas med kolumnen i declare-satsen.

Genomsökningslogik

scan går igenom serialiserade indata, registrerar efter post, jämför varje post med varje stegs villkor samtidigt som hänsyn tas till det aktuella tillståndet för varje steg.

Stat

Det underliggande tillståndet för scan-operatorn kan betraktas som en tabell med en rad för varje step. Varje steg upprätthåller sitt eget tillstånd med de senaste värdena för kolumnerna och deklarerade variabler från alla föregående steg och det aktuella steget. Om det är relevant innehåller det även matchnings-ID för den pågående sekvensen.

Om en genomsökningsoperator har n steg med namnet s_1, s_2, ..., s_n sedan steg s_k skulle ha k poster i dess tillstånd som motsvarar s_1, s_2, ..., s_k. StepName.ColumnName- format används för att referera till ett värde i tillståndet. Till exempel skulle s_2.col1 referera till kolumn col1 som tillhör steg s_2 i tillståndet för s_k. Ett detaljerat exempel finns i genomgången genomsökningslogik.

Tillståndet börjar tomt och uppdateras när en skannad indatapost matchar ett steg. När tillståndet för det aktuella steget inte är snålt kallas steget för att ha en aktiv sekvens.

Matchande logik

Varje indatapost utvärderas mot alla steg i omvänd ordning, från det sista steget till det första. När en post r utvärderas mot något steg s_ktillämpas följande logik:

  • Kontrollera 1: Om tillståndet för föregående steg (s_k-1) inte är något och r uppfyller Villkor för s_kinträffar en matchning. Matchningen leder till följande åtgärder:

    1. Tillståndet för s_k är avmarkerat.
    2. Tillståndet för s_k-1 befordras till att bli tillståndet för s_k.
    3. Tilldelningarna av s_k beräknas och utökas r.
    4. Den utökade r läggs till i utdata och tillståndet för s_k.

    Not

    Om kontroll 1 resulterar i en matchning ignoreras kontroll 2 och r går vidare för att utvärderas mot s_k-1.

  • Kontroll 2: Om tillståndet för s_k har en aktiv sekvens eller s_k är det första steget, och r uppfyller Villkor för s_k, inträffar en matchning. Matchningen leder till följande åtgärder:

    1. Tilldelningarna av s_k beräknas och utökas r.
    2. Värdena som representerar s_k i tillståndet för s_k ersätts med värdena för den utökade r.
    3. Om s_k definieras som output=allläggs den utökade r till i utdata.
    4. Om s_k är det första steget börjar en ny sekvens och matchnings-ID:t ökar med 1. Detta påverkar bara utdata när with_match_id används.

När kontrollerna för s_k har slutförts går r vidare för att utvärderas mot s_k-1.

Ett detaljerat exempel på den här logiken finns i genomgången genomsökningslogik.

Exempel

Exemplet i det här avsnittet visar hur du använder syntaxen för att komma igång.

Exemplen i den här artikeln använder offentligt tillgängliga tabeller i hjälpkluster, till exempel tabellen StormEvents i databasen Samples.

Exemplen i den här artikeln använder offentligt tillgängliga tabeller, till exempel tabellen StormEvents i Väderanalys exempeldata.

Kumulativ summa

Beräkna den kumulativa summan för en indatakolumn. Resultatet av det här exemplet motsvarar att använda 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;
)

utdata

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

Kumulativ summa för flera kolumner med ett återställningsvillkor

Beräkna den kumulativa summan för två indatakolumner, återställ summavärdet till det aktuella postvärdet när den kumulativa summan nådde 10 eller mer.

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);
)

utdata

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

Fyll framåt i en kolumn

Fyll framåt en strängkolumn. Varje tomt värde tilldelas det senast sedda icke-sedda värdet.

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);
)

utdata

Ts Händelse 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

Sessionstaggning

Dela upp indata i sessioner: en session slutar 30 minuter efter den första händelsen i sessionen, varefter en ny session startar. Observera användningen av flaggan with_match_id, som tilldelar ett unikt värde för varje distinkt matchning (session) för genomsökning. Observera också den speciella användningen av två steg i det här exemplet, inSession har true som villkor så att den samlar in och matar ut alla poster från indata medan endSession samlar in poster som inträffar mer än 30 m från sessionStart-värdet för den aktuella matchningen. Det endSession steget har output=none vilket innebär att det inte producerar utdataposter. Det endSession steget används för att öka statusen för den aktuella matchningen från inSession till endSession, så att en ny matchning (session) kan börja, med början från den aktuella posten.

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;
)

utdata

Ts Händelse sessionStart 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

Händelser mellan Start och Stopp

Hitta alla sekvenser av händelser mellan händelsen Start och händelsen Stop som inträffar inom 5 minuter. Tilldela ett matchnings-ID för varje sekvens.

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;
)

utdata

Ts Händelse m_id
00:01:00 Starta 0
00:02:00 B 0
00:03:00 D 0
00:04:00 Stanna 0
00:08:00 Starta 1
00:11:00 E 1
00:12:00 Stanna 1

Beräkna en anpassad tratt med händelser

Beräkna en trattavslutning av sekvensen Hail –>Tornado –>Thunderstorm Wind efter State med anpassade tröskelvärden för tiden mellan händelserna (Tornado inom 1h och Thunderstorm Wind inom 2h). Det här exemplet liknar det funnel_sequence_completion plugin-programmet, men ger större flexibilitet.

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

utdata

EventType dcount_State
Hagel 50
Tromb 34
Åskväder 32

Genomgång av logik

Det här avsnittet visar genomsökningslogik med hjälp av en stegvis genomgång av händelser mellan start och stopp exempel:

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;
)

utdata

Ts Händelse m_id
00:01:00 Starta 0
00:02:00 B 0
00:03:00 D 0
00:04:00 Stanna 0
00:08:00 Starta 1
00:11:00 E 1
00:12:00 Stanna 1

Tillståndet

Tänk på tillståndet för scan-operatorn som en tabell med en rad för varje steg, där varje steg har sitt eget tillstånd. Det här tillståndet innehåller de senaste värdena för kolumnerna och deklarerade variabler från alla föregående steg och det aktuella steget. Mer information finns i State.

I det här exemplet kan tillståndet representeras med följande tabell:

steg m_id s1. Ts s1. Händelse s2. Ts s2. Händelse s3. Ts s3. Händelse
s1 X X X X
s2 X X
s3

"X" anger att ett specifikt fält är irrelevant för det steget.

Matchningslogik

Det här avsnittet följer matchande logik genom varje post i tabellen Events och förklarar omvandlingen av tillståndet och utdata i varje steg.

Not

En indatapost utvärderas mot stegen i omvänd ordning, från det sista steget (s3) till det första steget (s1).

Post 1

Ts Händelse
0m "A"

Registrera utvärdering i varje steg:

  • s3: Kontroll 1 skickas inte eftersom tillståndet för s2 är tomt och Kontroll 2 inte skickas eftersom s3 saknar en aktiv sekvens.
  • s2: Kontroll 1 skickas inte eftersom tillståndet för s1 är tomt och Kontroll 2 inte skickas eftersom s2 saknar en aktiv sekvens.
  • s1: Kontrollera 1 är irrelevant eftersom det inte finns något föregående steg. Kontroll 2 skickas inte eftersom posten inte uppfyller villkoret för Event == "Start". Post 1 ignoreras utan att påverka tillståndet eller utdata.

tillstånd:

steg m_id s1. Ts s1. Händelse s2. Ts s2. Händelse s3. Ts s3. Händelse
s1 X X X X
s2 X X
s3

Post 2

Ts Händelse
1 m "Start"

Registrera utvärdering i varje steg:

  • s3: Kontroll 1 skickas inte eftersom tillståndet för s2 är tomt och Kontroll 2 inte skickas eftersom s3 saknar en aktiv sekvens.
  • s2: Kontroll 1 skickas inte eftersom tillståndet för s1 är tomt och Kontroll 2 inte skickas eftersom s2 saknar en aktiv sekvens.
  • s1: Kontrollera 1 är irrelevant eftersom det inte finns något föregående steg. Kontroll 2 skickas eftersom posten uppfyller villkoret för Event == "Start". Den här matchningen initierar en ny sekvens och m_id tilldelas. Post 2 och dess m_id (0) läggs till i tillståndet och utdata.

tillstånd:

steg m_id s1. Ts s1. Händelse s2. Ts s2. Händelse s3. Ts s3. Händelse
s1 0 00:01:00 "Start" X X X X
s2 X X
s3

Post 3

Ts Händelse
2 m "B"

Registrera utvärdering i varje steg:

  • s3: Kontroll 1 skickas inte eftersom tillståndet för s2 är tomt och Kontroll 2 inte skickas eftersom s3 saknar en aktiv sekvens.
  • s2: Kontrollera 1 skickas eftersom tillståndet för s1 inte är fel och posten uppfyller villkoret för Ts - s1.Ts < 5m. Den här matchningen gör att tillståndet för s1 rensas och sekvensen i s1 befordras till s2. Post 3 och dess m_id (0) läggs till i tillståndet och utdata.
  • s1: Kontrollera 1 är irrelevant eftersom det inte finns något föregående steg och Kontroll 2 inte skickas eftersom posten inte uppfyller villkoret för Event == "Start".

tillstånd:

steg m_id s1. Ts s1. Händelse s2. Ts s2. Händelse s3. Ts s3. Händelse
s1 X X X X
s2 0 00:01:00 "Start" 00:02:00 "B" X X
s3

Post 4

Ts Händelse
3 m "D"

Registrera utvärdering i varje steg:

  • s3: Kontroll 1 skickas inte eftersom posten inte uppfyller villkoret för Event == "Stop"och Kontroll 2 inte skickas eftersom s3 saknar en aktiv sekvens.
  • s2: Kontrollera 1 skickas inte eftersom tillståndet för s1 är tomt. den skickar kontroll 2 eftersom den uppfyller villkoret för Ts - s1.Ts < 5m. Post 4 och dess m_id (0) läggs till i tillståndet och utdata. Värdena från den här posten skriver över de tidigare tillståndsvärdena för s2.Ts och s2.Event.
  • s1: Kontrollera 1 är irrelevant eftersom det inte finns något föregående steg och Kontroll 2 inte skickas eftersom posten inte uppfyller villkoret för Event == "Start".

tillstånd:

steg m_id s1. Ts s1. Händelse s2. Ts s2. Händelse s3. Ts s3. Händelse
s1 X X X X
s2 0 00:01:00 "Start" 00:03:00 "D" X X
s3

Post 5

Ts Händelse
4 m "Stopp"

Registrera utvärdering i varje steg:

  • s3: Kontroll 1 skickas eftersom s2 inte är s3 villkoret för Event == "Stop". Den här matchningen gör att tillståndet för s2 rensas och sekvensen i s2 befordras till s3. Post 5 och dess m_id (0) läggs till i tillståndet och utdata.
  • s2: Kontroll 1 skickas inte eftersom tillståndet för s1 är tomt och Kontroll 2 inte skickas eftersom s2 saknar en aktiv sekvens.
  • s1: Kontrollera 1 är irrelevant eftersom det inte finns något föregående steg. Kontroll 2 skickas inte eftersom posten inte uppfyller villkoret för Event == "Start".

tillstånd:

steg m_id s1. Ts s1. Händelse s2. Ts s2. Händelse s3. Ts s3. Händelse
s1 X X X X
s2 X X
s3 0 00:01:00 "Start" 00:03:00 "D" 00:04:00 "Stopp"

Post 6

Ts Händelse
6 m "C"

Registrera utvärdering i varje steg:

  • s3: Kontroll 1 skickas inte eftersom tillståndet för s2 är tomt och Kontrollera 2 inte skickas eftersom s3 inte uppfyller s3 villkoret för Event == "Stop".
  • s2: Kontroll 1 skickas inte eftersom tillståndet för s1 är tomt och Kontroll 2 inte skickas eftersom s2 saknar en aktiv sekvens.
  • s1: Kontrollera 1 skickas inte eftersom det inte finns något föregående steg och Kontrollera 2 inte skickas eftersom det inte uppfyller villkoret för Event == "Start". Post 6 ignoreras utan att påverka tillståndet eller utdata.

tillstånd:

steg m_id s1. Ts s1. Händelse s2. Ts s2. Händelse s3. Ts s3. Händelse
s1 X X X X
s2 X X
s3 0 00:01:00 "Start" 00:03:00 "D" 00:04:00 "Stopp"

Post 7

Ts Händelse
8 m "Start"

Registrera utvärdering i varje steg:

  • s3: Kontroll 1 skickas inte eftersom tillståndet för s2 är tomt och Kontrollera 2 inte skickas eftersom det inte uppfyller villkoret för Event == "Stop".
  • s2: Kontroll 1 skickas inte eftersom tillståndet för s1 är tomt och Kontroll 2 inte skickas eftersom s2 saknar en aktiv sekvens.
  • s1: Kontrollera 1 skickas inte eftersom det inte finns något föregående steg. den skickar kontroll 2 eftersom den uppfyller villkoret för Event == "Start". Den här matchning initierar en ny sekvens i s1 med en ny m_id. Post 7 och dess m_id (1) läggs till i tillståndet och utdata.

tillstånd:

steg m_id s1. Ts s1. Händelse s2. Ts s2. Händelse s3. Ts s3. Händelse
s1 1 00:08:00 "Start" X X X X
s2 X X
s3 0 00:01:00 "Start" 00:03:00 "D" 00:04:00 "Stopp"

Not

Det finns nu två aktiva sekvenser i tillståndet.

Post 8

Ts Händelse
11 m "E"

Registrera utvärdering i varje steg:

  • s3: Kontroll 1 skickas inte eftersom tillståndet för s2 är tomt och Kontrollera 2 inte skickas eftersom det inte uppfyller s3 villkoret för Event == "Stop".
  • s2: Kontrollera 1 skickas eftersom tillståndet för s1 inte är fel och posten uppfyller villkoret för Ts - s1.Ts < 5m. Den här matchningen gör att tillståndet för s1 rensas och sekvensen i s1 befordras till s2. Post 8 och dess m_id (1) läggs till i tillståndet och utdata.
  • s1: Kontrollera 1 är irrelevant eftersom det inte finns något föregående steg och Kontroll 2 inte skickas eftersom posten inte uppfyller villkoret för Event == "Start".

tillstånd:

steg m_id s1. Ts s1. Händelse s2. Ts s2. Händelse s3. Ts s3. Händelse
s1 X X X X
s2 1 00:08:00 "Start" 00:11:00 "E" X X
s3 0 00:01:00 "Start" 00:03:00 "D" 00:04:00 "Stopp"

Post 9

Ts Händelse
12 m "Stopp"

Registrera utvärdering i varje steg:

  • s3: Kontroll 1 skickas eftersom s2 inte är s3 villkoret för Event == "Stop". Den här matchningen gör att tillståndet för s2 rensas och sekvensen i s2 befordras till s3. Post 9 och dess m_id (1) läggs till i tillståndet och utdata.
  • s2: Kontroll 1 skickas inte eftersom tillståndet för s1 är tomt och Kontroll 2 inte skickas eftersom s2 saknar en aktiv sekvens.
  • s1: Kontrollera 1 skickas inte eftersom det inte finns något föregående steg. den skickar kontroll 2 eftersom den uppfyller villkoret för Event == "Start". Den här matchning initierar en ny sekvens i s1 med en ny m_id.

tillstånd:

steg m_id s1. Ts s1. Händelse s2. Ts s2. Händelse s3. Ts s3. Händelse
s1 X X X X
s2 X X
s3 1 00:08:00 "Start" 00:11:00 "E" 00:12:00 "Stopp"

Slutliga utdata

Ts Händelse m_id
00:01:00 Starta 0
00:02:00 B 0
00:03:00 D 0
00:04:00 Stanna 0
00:08:00 Starta 1
00:11:00 E 1
00:12:00 Stanna 1