Compartilhar via


operador scan

Aplica-se a: ✅Microsoft FabricAzure Data Explorer✅Azure MonitorMicrosoft Sentinel

Examina dados, faz a correspondência e cria sequências com base nos predicados.

Os registros correspondentes são determinados de acordo com os predicados definidos nas etapas do operador. Um predicado pode depender do estado gerado pelas etapas anteriores. A saída para o registro correspondente é determinada pelo registro de entrada e atribuições definidas nas etapas do operador.

Sintaxe

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

Sintaxe ColumnDeclarations

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

Sintaxe StepDefinition

stepStepName [last | output = allnone | ] : Condição [ => Atribuição de Coluna = [, ... ] ];

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome Digitar Obrigatória Descrição
T string ✔️ A fonte tabular de entrada.
MatchIdColumnName string O nome de uma coluna do tipo long que é acrescentada à saída como parte da execução da verificação. Indica o índice baseado em 0 da correspondência para o registro.
ColumnDeclarations string Declara uma extensão para o esquema de T. Essas colunas recebem valores nas etapas. Se não for atribuído, o DefaultValue será retornado. A menos que especificado de outra forma, DefaultValue é null.
StepName string ✔️ Usado para referenciar valores no estado de verificação para condições e atribuições. O nome da etapa deve ser exclusivo.
Condição string ✔️ Uma expressão que avalia true ou false define quais registros da entrada correspondem à etapa. Um registro corresponde à etapa quando a condição está true com o estado da etapa ou com o estado da etapa anterior.
Cessão string Uma expressão escalar que é atribuída à coluna correspondente quando um registro corresponde a uma etapa.
output string Controla a lógica de saída da etapa em correspondências repetidas. all gera todos os registros que correspondem à etapa, last gera apenas o último registro em uma série de correspondências repetidas para a etapa e none não gera registros que correspondem à etapa. O padrão é all.

Devoluções

Um registro para cada correspondência de um registro da entrada para uma etapa. O esquema da saída é o esquema da fonte estendida com a coluna na declare cláusula.

Lógica de varredura

scan examina os dados de entrada serializados, registro por registro, comparando cada registro com a condição de cada etapa, levando em consideração o estado atual de cada etapa.

Estado

O estado subjacente do scan operador pode ser pensado como uma tabela com uma linha para cada step. Cada etapa mantém seu próprio estado com os valores mais recentes das colunas e variáveis declaradas de todas as etapas anteriores e da etapa atual. Se relevante, ele também contém a ID de correspondência para a sequência em andamento.

Se um operador de varredura tiver n etapas chamadas s_1, s_2, ..., s_n a etapa s_k terá k registros em seu estado correspondente a s_1, s_2, ..., s_k. O StepName.O formato ColumnName é usado para fazer referência a um valor no estado. Por exemplo, s_2.col1 faria referência à coluna col1 que pertence à etapa s_2 no estado de s_k. Para obter um exemplo detalhado, consulte o passo a passo da lógica de verificação.

O estado começa vazio e é atualizado sempre que um registro de entrada digitalizado corresponde a uma etapa. Quando o estado da etapa atual não está vazio, a etapa é chamada de tendo uma sequência ativa.

Lógica de correspondência

Cada registro de entrada é avaliado em relação a todas as etapas na ordem inversa, da última etapa à primeira. Quando um registro r é avaliado em relação a algum s_k de etapa, a seguinte lógica é aplicada:

  • Verificação 1: Se o estado da etapa anterior (s_k-1) não estiver vazio e r atender à Condição de s_k, ocorrerá uma correspondência. A correspondência leva às seguintes ações:

    1. O estado de s_k é limpo.
    2. O estado de s_k-1 é promovido a se tornar o estado de s_k.
    3. As atribuições de s_k são calculadas e se estendem r.
    4. O r estendido é adicionado à saída e ao estado de s_k.

    Observação

    Se o Check 1 resultar em uma correspondência, o Check 2 será desconsiderado e r passará a ser avaliado contra s_k-1.

  • Verificação 2: Se o estado de s_k tiver uma sequência ou s_k ativa for a primeira etapa e r atender à Condição de s_k, ocorrerá uma correspondência. A correspondência leva às seguintes ações:

    1. As atribuições de s_k são calculadas e se estendem r.
    2. Os valores que representam s_k no estado de s_k são substituídos pelos valores do r estendido.
    3. Se s_k for definido como output=all, o r estendido será adicionado à saída.
    4. Se s_k for a primeira etapa, uma nova sequência será iniciada e o ID da correspondência aumentará em 1. Isso afeta apenas a saída quando with_match_id é usado.

Depois que as verificações de s_k forem concluídas, r passará a ser avaliado em relação a s_k-1.

Para obter um exemplo detalhado dessa lógica, consulte o passo a passo da lógica de verificação.

Exemplos

Soma cumulativa

Calcule a soma cumulativa de uma coluna de entrada. O resultado deste exemplo é equivalente ao uso de 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;
)

Saída

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

Soma cumulativa em várias colunas com uma condição de redefinição

Calcule a soma cumulativa para duas colunas de entrada, redefina o valor da soma para o valor do registro atual sempre que a soma cumulativa atingir 10 ou mais.

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

Saída

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

Preencher uma coluna

Preencha uma coluna de string. Cada valor vazio recebe o último valor não vazio visto.

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

Saída

Ts Evento Event_filled
00:00:00 A A
00:01:00 Um
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

Marcação de sessões

Divida a entrada em sessões: uma sessão termina 30 minutos após o primeiro evento da sessão, após o qual uma nova sessão é iniciada. Observe o uso de with_match_id sinalizador, que atribui um valor exclusivo para cada correspondência distinta (sessão) de varredura. Observe também o uso especial de duas etapas neste exemplo, inSession tem true como condição para capturar e gerar todos os registros da entrada enquanto endSession captura registros que acontecem a mais de 30m do sessionStart valor da correspondência atual. A endSession etapa significa output=none que não produz registros de saída. A endSession etapa é usada para avançar o estado da correspondência atual de inSession para endSession, permitindo que uma nova correspondência (sessão) seja iniciada, a partir do registro atual.

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

Saída

Ts Evento sessãoInício session_id
00:00:00 Um 00:00:00 0
00:01:00 Um 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 Um 01:15:00 2

Eventos entre Início e Parada

Encontre todas as sequências de eventos entre o evento Start e o evento Stop que ocorrem em 5 minutos. Atribua uma ID de correspondência para cada sequência.

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

Saída

Ts Evento m_id
00:01:00 Iniciar 0
00:02:00 B 0
00:03:00 D 0
00:04:00 Parar 0
00:08:00 Iniciar 1
00:11:00 E 1
00:12:00 Parar 1

Calcular um funil personalizado de eventos

Calcule uma conclusão de funil da sequência Hail ->Tornado ->Thunderstorm Wind com State limites personalizados nos tempos entre os eventos (Tornado dentro 1h e Thunderstorm Wind dentro 2h). Este exemplo é semelhante ao plugin funnel_sequence_completion, mas permite maior flexibilidade.

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

Saída

EventType dcount_State
Granizo 50
Tornado 34
Thunderstorm Wind 32

Passo a passo da lógica de varredura

Esta seção demonstra a lógica de verificação usando um passo a passo do exemplo Eventos entre o início e a parada :

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

O estado

Pense no estado do scan operador como uma tabela com uma linha para cada etapa, na qual cada etapa tem seu próprio estado. Esse estado contém os valores mais recentes das colunas e variáveis declaradas de todas as etapas anteriores e da etapa atual. Para saber mais, consulte Estado.

Para este exemplo, o estado pode ser representado com a seguinte tabela:

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

O "X" indica que um campo específico é irrelevante para essa etapa.

A lógica de correspondência

Esta seção segue a lógica de correspondência em cada registro da Events tabela, explicando a transformação do estado e da saída em cada etapa.

Observação

Um registro de entrada é avaliado em relação às etapas na ordem inversa, da última etapa (s3) à primeira etapa (s1).

Registro 1

Ts Evento
0m "A"

Registre a avaliação em cada etapa:

  • s3: A verificação 1 não é passada porque o estado de s2 está vazio e a verificação 2 não é passada porque s3 não tem uma sequência ativa.
  • s2: A verificação 1 não é passada porque o estado de s1 está vazio e a verificação 2 não é passada porque s2 não tem uma sequência ativa.
  • s1: A verificação 1 é irrelevante porque não há etapa anterior. A verificação 2 não foi aprovada porque o registro não atende à condição de Event == "Start". O registro 1 é descartado sem afetar o estado ou a saída.

Estado:

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

Registro 2

Ts Evento
1 minuto "Começar"

Registre a avaliação em cada etapa:

  • s3: A verificação 1 não é passada porque o estado de s2 está vazio e a verificação 2 não é passada porque s3 não tem uma sequência ativa.
  • s2: A verificação 1 não é passada porque o estado de s1 está vazio e a verificação 2 não é passada porque s2 não tem uma sequência ativa.
  • s1: A verificação 1 é irrelevante porque não há etapa anterior. A verificação 2 é aprovada porque o registro atende à condição de Event == "Start". Essa correspondência inicia uma nova sequência e é m_id atribuída. O registro 2 e seu m_id (0) são adicionados ao estado e à saída.

Estado:

step m_id s1. Ts s1. Acontecimento s2. Ts s2. Acontecimento s3. Ts s3. Acontecimento
s1 0 00:01:00 "Começar" X X X X
s2 X X
s3

Registro 3

Ts Evento
2 minutos "B"

Registre a avaliação em cada etapa:

  • s3: A verificação 1 não é passada porque o estado de s2 está vazio e a verificação 2 não é passada porque s3 não tem uma sequência ativa.
  • s2: A verificação 1 é aprovada porque o estado de s1 não está vazio e o registro atende à condição de Ts - s1.Ts < 5m. Essa correspondência faz com que o estado de s1 seja limpo e a sequência em s1 seja promovida para s2. O registro 3 e seu m_id (0) são adicionados ao estado e à saída.
  • s1: A verificação 1 é irrelevante porque não há nenhuma etapa anterior e a verificação 2 não é aprovada porque o registro não atende à condição de Event == "Start".

Estado:

step m_id s1. Ts s1. Acontecimento s2. Ts s2. Acontecimento s3. Ts s3. Acontecimento
s1 X X X X
s2 0 00:01:00 "Começar" 00:02:00 "B" X X
s3

Registro 4

Ts Evento
3 minutos "D"

Registre a avaliação em cada etapa:

  • s3: A verificação 1 não é passada porque o registro não atende à condição de Event == "Stop", e a verificação 2 não é passada porque s3 não tem uma sequência ativa.
  • s2: A verificação 1 não foi aprovada porque o estado de s1 está vazio. ele passa na Verificação 2 porque atende à condição de Ts - s1.Ts < 5m. O registro 4 e seu m_id (0) são adicionados ao estado e à saída. Os valores desse registro substituem os valores de estado anteriores para s2.Ts e s2.Event.
  • s1: A verificação 1 é irrelevante porque não há nenhuma etapa anterior e a verificação 2 não é aprovada porque o registro não atende à condição de Event == "Start".

Estado:

step m_id s1. Ts s1. Acontecimento s2. Ts s2. Acontecimento s3. Ts s3. Acontecimento
s1 X X X X
s2 0 00:01:00 "Começar" 00:03:00 "D" X X
s3

Registro 5

Ts Evento
4 minutos "Parar"

Registre a avaliação em cada etapa:

  • s3: A verificação 1 é aprovada porque s2 não está vazia e atende à s3 condição de Event == "Stop". Essa correspondência faz com que o estado de s2 seja limpo e a sequência em s2 seja promovida para s3. O registro 5 e seu m_id (0) são adicionados ao estado e à saída.
  • s2: A verificação 1 não é passada porque o estado de s1 está vazio e a verificação 2 não é passada porque s2 não tem uma sequência ativa.
  • s1: A verificação 1 é irrelevante porque não há etapa anterior. A verificação 2 não foi aprovada porque o registro não atende à condição de Event == "Start".

Estado:

step m_id s1. Ts s1. Acontecimento s2. Ts s2. Acontecimento s3. Ts s3. Acontecimento
s1 X X X X
s2 X X
s3 0 00:01:00 "Começar" 00:03:00 "D" 00:04:00 "Parar"

Registro 6

Ts Evento
6m "C"

Registre a avaliação em cada etapa:

  • s3: A verificação 1 não foi aprovada porque o estado de s2 está vazio e a verificação 2 não foi aprovada porque s3 não atende à s3 condição de Event == "Stop".
  • s2: A verificação 1 não é passada porque o estado de s1 está vazio e a verificação 2 não é passada porque s2 não tem uma sequência ativa.
  • s1: a verificação 1 não foi aprovada porque não há nenhuma etapa anterior e a verificação 2 não foi aprovada porque não atende à condição de Event == "Start". O registro 6 é descartado sem afetar o estado ou a saída.

Estado:

step m_id s1. Ts s1. Acontecimento s2. Ts s2. Acontecimento s3. Ts s3. Acontecimento
s1 X X X X
s2 X X
s3 0 00:01:00 "Começar" 00:03:00 "D" 00:04:00 "Parar"

Registro 7

Ts Evento
8 milhões "Começar"

Registre a avaliação em cada etapa:

  • s3: A verificação 1 não foi aprovada porque o estado de s2 está vazio e a verificação 2 não foi aprovada porque não atende à condição de Event == "Stop".
  • s2: A verificação 1 não é passada porque o estado de s1 está vazio e a verificação 2 não é passada porque s2 não tem uma sequência ativa.
  • s1: a verificação 1 não foi aprovada porque não há nenhuma etapa anterior. ele passa na Verificação 2 porque atende à condição de Event == "Start". Essa correspondência inicia uma nova sequência com s1 um novo m_id. O registro 7 e seu m_id (1) são adicionados ao estado e à saída.

Estado:

step m_id s1. Ts s1. Acontecimento s2. Ts s2. Acontecimento s3. Ts s3. Acontecimento
s1 1 00:08:00 "Começar" X X X X
s2 X X
s3 0 00:01:00 "Começar" 00:03:00 "D" 00:04:00 "Parar"

Observação

Existem agora duas sequências ativas no estado.

Registro 8

Ts Evento
11 minutos "E"

Registre a avaliação em cada etapa:

  • s3: A verificação 1 não foi aprovada porque o estado de s2 está vazio e a verificação 2 não foi aprovada porque não atende à s3 condição de Event == "Stop".
  • s2: A verificação 1 é aprovada porque o estado de s1 não está vazio e o registro atende à condição de Ts - s1.Ts < 5m. Essa correspondência faz com que o estado de s1 seja limpo e a sequência em s1 seja promovida para s2. O registro 8 e seu m_id (1) são adicionados ao estado e à saída.
  • s1: A verificação 1 é irrelevante porque não há nenhuma etapa anterior e a verificação 2 não é aprovada porque o registro não atende à condição de Event == "Start".

Estado:

step m_id s1. Ts s1. Acontecimento s2. Ts s2. Acontecimento s3. Ts s3. Acontecimento
s1 X X X X
s2 1 00:08:00 "Começar" 00:11:00 "E" X X
s3 0 00:01:00 "Começar" 00:03:00 "D" 00:04:00 "Parar"

Registro 9

Ts Evento
12 milhões "Parar"

Registre a avaliação em cada etapa:

  • s3: A verificação 1 é aprovada porque s2 não está vazia e atende à s3 condição de Event == "Stop". Essa correspondência faz com que o estado de s2 seja limpo e a sequência em s2 seja promovida para s3. O registro 9 e seu m_id (1) são adicionados ao estado e à saída.
  • s2: A verificação 1 não é passada porque o estado de s1 está vazio e a verificação 2 não é passada porque s2 não tem uma sequência ativa.
  • s1: a verificação 1 não foi aprovada porque não há nenhuma etapa anterior. ele passa na Verificação 2 porque atende à condição de Event == "Start". Essa correspondência inicia uma nova sequência com s1 um novo m_id.

Estado:

step m_id s1. Ts s1. Acontecimento s2. Ts s2. Acontecimento s3. Ts s3. Acontecimento
s1 X X X X
s2 X X
s3 1 00:08:00 "Começar" 00:11:00 "E" 00:12:00 "Parar"

Saída final

Ts Evento m_id
00:01:00 Iniciar 0
00:02:00 B 0
00:03:00 D 0
00:04:00 Parar 0
00:08:00 Iniciar 1
00:11:00 E 1
00:12:00 Parar 1