Delen via

scanoperator

  • Artikel

Van toepassing op: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel-

Scant gegevens, overeenkomsten en buildsreeksen op basis van de predicaten.

Overeenkomende records worden bepaald volgens de predicaten die zijn gedefinieerd in de stappen van de operator. Een predicaat kan afhankelijk zijn van de status die wordt gegenereerd door vorige stappen. De uitvoer voor de overeenkomende record wordt bepaald door de invoerrecord en toewijzingen die zijn gedefinieerd in de stappen van de operator.

Syntaxis

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

ColumnDeclarations syntaxis

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

StepDefinition syntaxis

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

Meer informatie over syntaxisconventies.

Parameters

Naam Type Vereist Beschrijving
T- string ✔️ De bron in tabelvorm van invoer.
MatchIdColumnName string De naam van een kolom van het type long die wordt toegevoegd aan de uitvoer als onderdeel van de scanuitvoering. Geeft de index op basis van 0 aan van de overeenkomst voor de record.
ColumnDeclarations string Declareert een extensie voor het schema van T. Deze kolommen zijn toegewezen waarden in de stappen. Als dit niet is toegewezen, wordt de DefaultValue- geretourneerd. Tenzij anders opgegeven, wordt DefaultValue-null.
StepName string ✔️ Wordt gebruikt om te verwijzen naar waarden in de status van de scan op voorwaarden en toewijzingen. De naam van de stap moet uniek zijn.
voorwaarde string ✔️ Een expressie die resulteert in true of false waarmee wordt gedefinieerd welke records uit de invoer overeenkomen met de stap. Een record komt overeen met de stap wanneer de voorwaarde wordt true met de status van de stap of met de status van de vorige stap.
toewijzing string Een scalaire expressie die is toegewezen aan de bijbehorende kolom wanneer een record overeenkomt met een stap.
output string Hiermee bepaalt u de uitvoerlogica van de stap voor herhaalde overeenkomsten. all alle records uitvoert die overeenkomen met de stap, last alleen de laatste record uitvoert in een reeks herhalende overeenkomsten voor de stap en none geen records uitvoert die overeenkomen met de stap. De standaardwaarde is all.

Retourneert

Een record voor elke overeenkomst van een record uit de invoer naar een stap. Het schema van de uitvoer is het schema van de bron dat is uitgebreid met de kolom in de declare-component.

Scanlogica

scan gaat over de geserialiseerde invoergegevens, record per record, waarbij elke record wordt vergeleken met de voorwaarde van elke stap, waarbij rekening wordt gehouden met de huidige status van elke stap.

Staat

De onderliggende status van de operator scan kan worden beschouwd als een tabel met een rij voor elke step. Elke stap behoudt een eigen status met de meest recente waarden van de kolommen en gedeclareerde variabelen uit alle vorige stappen en de huidige stap. Indien relevant, bevat het ook de overeenkomst-id voor de doorlopende reeks.

Als een scanoperator n stappen heeft met de naam s_1, s_2, ..., s_n dan s_kk records in de status die overeenkomt met s_1, s_2, ..., s_k. De StepName.ColumnName-indeling wordt gebruikt om te verwijzen naar een waarde in de status. s_2.col1 verwijst bijvoorbeeld naar kolom col1 die deel uitmaakt van stap s_2 in de status van s_k. Zie het overzicht van de scanlogicavoor een gedetailleerd voorbeeld.

De status wordt leeg gestart en wordt bijgewerkt wanneer een gescande invoerrecord overeenkomt met een stap. Wanneer de status van de huidige stap nietmpty is, wordt de stap aangeduid als een actieve reeks.

Overeenkomende logica

Elke invoerrecord wordt geëvalueerd op basis van alle stappen in omgekeerde volgorde, van de laatste stap tot de eerste. Wanneer een record r wordt geëvalueerd op basis van een bepaalde stap s_k, wordt de volgende logica toegepast:

  • Controle 1: Als de status van de vorige stap (s_k-1) niet volledig is en r voldoet aan de Voorwaarde van s_k, treedt er een overeenkomst op. De overeenkomst leidt tot de volgende acties:

    1. De status van s_k wordt gewist.
    2. De staat van s_k-1 wordt gepromoveerd tot de staat van s_k.
    3. De toewijzingen van s_k worden berekend en uitgebreid r.
    4. De uitgebreide r- wordt toegevoegd aan de uitvoer en aan de status van s_k.

    Notitie

    Als Controle 1 resulteert in een overeenkomst, wordt Controle 2 genegeerd en wordt r geëvalueerd op basis van s_k-1.

  • Controleren 2: Als de status van s_k een actieve reeks of s_k de eerste stap is en r voldoet aan de Voorwaarde van s_k, treedt er een overeenkomst op. De overeenkomst leidt tot de volgende acties:

    1. De toewijzingen van s_k worden berekend en uitgebreid r.
    2. De waarden die s_k in de status van s_k vertegenwoordigen, worden vervangen door de waarden van de uitgebreide r.
    3. Als s_k is gedefinieerd als output=all, wordt de uitgebreide r- toegevoegd aan de uitvoer.
    4. Als s_k de eerste stap is, begint een nieuwe reeks en neemt de overeenkomst-id toe met 1. Dit is alleen van invloed op de uitvoer wanneer with_match_id wordt gebruikt.

Zodra de controles voor s_k zijn voltooid, gaat r verder om te worden geëvalueerd op basis van s_k-1.

Zie het overzicht van de scanlogicavoor een gedetailleerd voorbeeld van deze logica.

Voorbeelden

In het voorbeeld in deze sectie ziet u hoe u de syntaxis gebruikt om aan de slag te gaan.

In de voorbeelden in dit artikel worden openbaar beschikbare tabellen gebruikt in de Help-cluster, zoals de StormEvents tabel in de Voorbeelden database.

In de voorbeelden in dit artikel worden openbaar beschikbare tabellen gebruikt, zoals de tabel StormEvents in de weather analytics voorbeeldgegevens.

Cumulatieve som

Bereken de cumulatieve som voor een invoerkolom. Het resultaat van dit voorbeeld is gelijk aan het gebruik van 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;
)

uitvoer

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

Cumulatieve som voor meerdere kolommen met een resetvoorwaarde

Bereken de cumulatieve som voor twee invoerkolommen, stel de somwaarde opnieuw in op de huidige recordwaarde wanneer de cumulatieve som 10 of meer heeft bereikt.

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

uitvoer

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

Een kolom vooruitvullen

Vul een tekenreekskolom in. Aan elke lege waarde wordt de laatst geziene lege waarde toegewezen.

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

uitvoer

Ts Gebeurtenis Event_filled
00:00:00 Een Een
00:01:00 Een
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

Sessies taggen

Verdeel de invoer in sessies: een sessie eindigt 30 minuten na de eerste gebeurtenis van de sessie, waarna een nieuwe sessie wordt gestart. Let op het gebruik van with_match_id vlag, die een unieke waarde toewijst voor elke afzonderlijke overeenkomst (sessie) van scan. Let ook op het speciale gebruik van twee stappen in dit voorbeeld, inSessiontrue als voorwaarde heeft, zodat alle records uit de invoer worden vastgelegd en uitgevoerd terwijl endSession records vastlegt die meer dan 30m van de sessionStart-waarde voor de huidige overeenkomst plaatsvinden. De endSession stap heeft output=none wat betekent dat er geen uitvoerrecords worden geproduceerd. De endSession stap wordt gebruikt om de status van de huidige overeenkomst van inSession naar endSessionte gaan, zodat een nieuwe overeenkomst (sessie) kan beginnen, beginnend vanaf de huidige record.

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

uitvoer

Ts Gebeurtenis sessionStart session_id
00:00:00 Een 00:00:00 0
00:01:00 Een 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 Een 01:15:00 2

Gebeurtenissen tussen starten en stoppen

Zoek alle reeksen gebeurtenissen tussen de gebeurtenis Start en de gebeurtenis Stop die binnen 5 minuten plaatsvinden. Wijs een overeenkomst-id toe voor elke reeks.

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

uitvoer

Ts Gebeurtenis m_id
00:01:00 Beginnen 0
00:02:00 B 0
00:03:00 D 0
00:04:00 Stoppen 0
00:08:00 Beginnen 1
00:11:00 E 1
00:12:00 Stoppen 1

Een aangepaste trechter van gebeurtenissen berekenen

Bereken een trechtervoltooiing van de reeks Hail ->Tornado ->Thunderstorm Wind door State met aangepaste drempelwaarden op de tijden tussen de gebeurtenissen (Tornado binnen 1h en Thunderstorm Wind binnen 2h). Dit voorbeeld is vergelijkbaar met de funnel_sequence_completion plugin, maar biedt meer flexibiliteit.

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

uitvoer

EventType dcount_State
Hagel 50
Tornado 34
Onweer wind 32

Overzicht van scanlogica

In deze sectie ziet u de scanlogica met behulp van een stapsgewijze procedure voor het gebeurtenissen tussen het starten en stoppen van voorbeeld:

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

uitvoer

Ts Gebeurtenis m_id
00:01:00 Beginnen 0
00:02:00 B 0
00:03:00 D 0
00:04:00 Stoppen 0
00:08:00 Beginnen 1
00:11:00 E 1
00:12:00 Stoppen 1

De status

U kunt de status van de operator scan beschouwen als een tabel met een rij voor elke stap, waarin elke stap een eigen status heeft. Deze status bevat de meest recente waarden van de kolommen en gedeclareerde variabelen uit alle vorige stappen en de huidige stap. Zie Statevoor meer informatie.

In dit voorbeeld kan de status worden weergegeven met de volgende tabel:

stap m_id s1. Ts s1. Gebeurtenis s2. Ts s2. Gebeurtenis s3. Ts s3. Gebeurtenis
s1 X X X X
s2 X X
s3

De X geeft aan dat een specifiek veld niet relevant is voor die stap.

De overeenkomende logica

Deze sectie volgt de overeenkomende logica door elke record van de Events tabel, waarin de transformatie van de status en uitvoer bij elke stap wordt uitgelegd.

Notitie

Een invoerrecord wordt geëvalueerd op basis van de stappen in omgekeerde volgorde, van de laatste stap (s3) tot de eerste stap (s1).

Record 1

Ts Gebeurtenis
0 min. "A"

Evaluatie van records bij elke stap:

  • s3: controle 1 niet wordt doorgegeven omdat de status van s2 leeg is en controle 2 niet wordt doorgegeven omdat s3 geen actieve reeks heeft.
  • s2: controle 1 niet wordt doorgegeven omdat de status van s1 leeg is en controle 2 niet wordt doorgegeven omdat s2 geen actieve reeks heeft.
  • s1: Controleren 1 is niet relevant omdat er geen vorige stap is. Controle 2 niet wordt doorgegeven omdat de record niet voldoet aan de voorwaarde van Event == "Start". record 1 wordt verwijderd zonder dat dit van invloed is op de status of uitvoer.

status:

stap m_id s1. Ts s1. Gebeurtenis s2. Ts s2. Gebeurtenis s3. Ts s3. Gebeurtenis
s1 X X X X
s2 X X
s3

Record 2

Ts Gebeurtenis
1 min. "Start"

Evaluatie van records bij elke stap:

  • s3: controle 1 niet wordt doorgegeven omdat de status van s2 leeg is en controle 2 niet wordt doorgegeven omdat s3 geen actieve reeks heeft.
  • s2: controle 1 niet wordt doorgegeven omdat de status van s1 leeg is en controle 2 niet wordt doorgegeven omdat s2 geen actieve reeks heeft.
  • s1: Controleren 1 is niet relevant omdat er geen vorige stap is. Controle 2 wordt doorgegeven omdat de record voldoet aan de voorwaarde van Event == "Start". Deze overeenkomst initieert een nieuwe reeks en de m_id wordt toegewezen. Record 2 en de bijbehorende m_id (0) worden toegevoegd aan de status en de uitvoer.

status:

stap m_id s1. Ts s1. Gebeurtenis s2. Ts s2. Gebeurtenis s3. Ts s3. Gebeurtenis
s1 0 00:01:00 "Start" X X X X
s2 X X
s3

Record 3

Ts Gebeurtenis
2 min. "B"

Evaluatie van records bij elke stap:

  • s3: controle 1 niet wordt doorgegeven omdat de status van s2 leeg is en controle 2 niet wordt doorgegeven omdat s3 geen actieve reeks heeft.
  • s2: Controle 1 wordt doorgegeven omdat de status van s1 niet volledig is en de record voldoet aan de voorwaarde van Ts - s1.Ts < 5m. Deze overeenkomst zorgt ervoor dat de status van s1 wordt gewist en dat de volgorde in s1 wordt gepromoveerd tot s2. Record 3 en de bijbehorende m_id (0) worden toegevoegd aan de status en de uitvoer.
  • s1: Controle 1 is niet relevant omdat er geen vorige stap is en Controle 2 niet wordt doorgegeven omdat de record niet voldoet aan de voorwaarde van Event == "Start".

status:

stap m_id s1. Ts s1. Gebeurtenis s2. Ts s2. Gebeurtenis s3. Ts s3. Gebeurtenis
s1 X X X X
s2 0 00:01:00 "Start" 00:02:00 "B" X X
s3

Record 4

Ts Gebeurtenis
3 min. "D"

Evaluatie van records bij elke stap:

  • s3: Controle 1 niet wordt doorgegeven omdat de record niet voldoet aan de voorwaarde van Event == "Stop"en Controle 2 niet wordt doorgegeven omdat s3 geen actieve volgorde mist.
  • s2: Controle 1 niet wordt doorgegeven omdat de status van s1 leeg is. het passeert Check 2 omdat deze voldoet aan de voorwaarde van Ts - s1.Ts < 5m. Record 4 en de bijbehorende m_id (0) worden toegevoegd aan de status en de uitvoer. De waarden uit deze record overschrijven de vorige statuswaarden voor s2.Ts en s2.Event.
  • s1: Controle 1 is niet relevant omdat er geen vorige stap is en Controle 2 niet wordt doorgegeven omdat de record niet voldoet aan de voorwaarde van Event == "Start".

status:

stap m_id s1. Ts s1. Gebeurtenis s2. Ts s2. Gebeurtenis s3. Ts s3. Gebeurtenis
s1 X X X X
s2 0 00:01:00 "Start" 00:03:00 "D" X X
s3

Record 5

Ts Gebeurtenis
4 min. "Stoppen"

Evaluatie van records bij elke stap:

  • s3: Controle 1 wordt doorgegeven omdat s2 niet-volledig is en voldoet aan de s3 voorwaarde van Event == "Stop". Deze overeenkomst zorgt ervoor dat de status van s2 wordt gewist en dat de volgorde in s2 wordt gepromoveerd tot s3. Record 5 en de bijbehorende m_id (0) worden toegevoegd aan de status en de uitvoer.
  • s2: controle 1 niet wordt doorgegeven omdat de status van s1 leeg is en controle 2 niet wordt doorgegeven omdat s2 geen actieve reeks heeft.
  • s1: Controleren 1 is niet relevant omdat er geen vorige stap is. Controle 2 niet wordt doorgegeven omdat de record niet voldoet aan de voorwaarde van Event == "Start".

status:

stap m_id s1. Ts s1. Gebeurtenis s2. Ts s2. Gebeurtenis s3. Ts s3. Gebeurtenis
s1 X X X X
s2 X X
s3 0 00:01:00 "Start" 00:03:00 "D" 00:04:00 "Stoppen"

Record 6

Ts Gebeurtenis
6 min. "C"

Evaluatie van records bij elke stap:

  • s3: Controle 1 niet wordt doorgegeven omdat de status van s2 leeg is en Controle 2 niet wordt doorgegeven omdat s3 niet voldoet aan de s3 voorwaarde van Event == "Stop".
  • s2: controle 1 niet wordt doorgegeven omdat de status van s1 leeg is en controle 2 niet wordt doorgegeven omdat s2 geen actieve reeks heeft.
  • s1: Controle 1 niet wordt doorgegeven omdat er geen vorige stap is en Controle 2 niet wordt doorgegeven omdat deze niet voldoet aan de voorwaarde van Event == "Start". Record 6 wordt verwijderd zonder dat dit van invloed is op de status of uitvoer.

status:

stap m_id s1. Ts s1. Gebeurtenis s2. Ts s2. Gebeurtenis s3. Ts s3. Gebeurtenis
s1 X X X X
s2 X X
s3 0 00:01:00 "Start" 00:03:00 "D" 00:04:00 "Stoppen"

Record 7

Ts Gebeurtenis
8 min. "Start"

Evaluatie van records bij elke stap:

  • s3: Controle 1 niet wordt doorgegeven omdat de status van s2 leeg is en controle 2 niet wordt doorgegeven omdat deze niet voldoet aan de voorwaarde van Event == "Stop".
  • s2: controle 1 niet wordt doorgegeven omdat de status van s1 leeg is en controle 2 niet wordt doorgegeven omdat s2 geen actieve reeks heeft.
  • s1: controle 1 niet is doorgegeven omdat er geen vorige stap is. het passeert Check 2 omdat deze voldoet aan de voorwaarde van Event == "Start". Deze overeenkomst initieert een nieuwe reeks in s1 met een nieuwe m_id. Record 7 en de bijbehorende m_id (1) worden toegevoegd aan de status en de uitvoer.

status:

stap m_id s1. Ts s1. Gebeurtenis s2. Ts s2. Gebeurtenis s3. Ts s3. Gebeurtenis
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 "Stoppen"

Notitie

Er zijn nu twee actieve reeksen in de status.

Record 8

Ts Gebeurtenis
11 min. "E"

Evaluatie van records bij elke stap:

  • s3: Controle 1 niet wordt doorgegeven omdat de status van s2 leeg is en Controle 2 niet wordt doorgegeven omdat deze niet voldoet aan de s3 voorwaarde van Event == "Stop".
  • s2: Controle 1 wordt doorgegeven omdat de status van s1 niet volledig is en de record voldoet aan de voorwaarde van Ts - s1.Ts < 5m. Deze overeenkomst zorgt ervoor dat de status van s1 wordt gewist en dat de volgorde in s1 wordt gepromoveerd tot s2. Record 8 en de bijbehorende m_id (1) worden toegevoegd aan de status en de uitvoer.
  • s1: Controle 1 is niet relevant omdat er geen vorige stap is en Controle 2 niet wordt doorgegeven omdat de record niet voldoet aan de voorwaarde van Event == "Start".

status:

stap m_id s1. Ts s1. Gebeurtenis s2. Ts s2. Gebeurtenis s3. Ts s3. Gebeurtenis
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 "Stoppen"

Record 9

Ts Gebeurtenis
12 min. "Stoppen"

Evaluatie van records bij elke stap:

  • s3: Controle 1 wordt doorgegeven omdat s2 niet-volledig is en voldoet aan de s3 voorwaarde van Event == "Stop". Deze overeenkomst zorgt ervoor dat de status van s2 wordt gewist en dat de volgorde in s2 wordt gepromoveerd tot s3. Record 9- en de bijbehorende m_id (1) worden toegevoegd aan de status en de uitvoer.
  • s2: controle 1 niet wordt doorgegeven omdat de status van s1 leeg is en controle 2 niet wordt doorgegeven omdat s2 geen actieve reeks heeft.
  • s1: controle 1 niet is doorgegeven omdat er geen vorige stap is. het passeert Check 2 omdat deze voldoet aan de voorwaarde van Event == "Start". Deze overeenkomst initieert een nieuwe reeks in s1 met een nieuwe m_id.

status:

stap m_id s1. Ts s1. Gebeurtenis s2. Ts s2. Gebeurtenis s3. Ts s3. Gebeurtenis
s1 X X X X
s2 X X
s3 1 00:08:00 "Start" 00:11:00 "E" 00:12:00 "Stoppen"

Uiteindelijke uitvoer

Ts Gebeurtenis m_id
00:01:00 Beginnen 0
00:02:00 B 0
00:03:00 D 0
00:04:00 Stoppen 0
00:08:00 Beginnen 1
00:11:00 E 1
00:12:00 Stoppen 1