operador de varredura

Artigo
02/06/2025

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Analisa dados, faz correspondências e cria sequências com base nos predicados.

Os registros correspondentes são determinados de acordo com 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

step StepName [ output = all | last | none] :Condição [ =>Coluna=Atribuição [, ... ] ;

Saiba mais sobre convenções de sintaxe.

Parâmetros

Designação	Tipo	Necessário	Descrição
T	`string`	✔️	A fonte tabular de entrada.
MatchIdColumnName	`string`		O nome de uma coluna do tipo `long` que é anexada à 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 de condições e atribuições. O nome da etapa deve ser exclusivo.
Condição	`string`	✔️	Uma expressão avaliada como `true` ou `false` que define quais registros da entrada correspondem à etapa. Um registro corresponde à etapa quando a condição é `true` com o estado da etapa ou com o estado da etapa anterior.
Atribuiçã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` produz todos os registros correspondentes à etapa, `last` produz apenas o último registro de uma série de correspondências repetidas para a etapa e `none` não produz registros correspondentes à etapa. O padrão é `all`.

Devoluções

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

Lógica de varredura

scan analisa 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 operador scan pode ser considerado 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 mantém o ID de correspondência para a sequência em andamento.

Se um operador de varredura tiver n etapas nomeadas s_1, s_2, ..., s_n então a etapa s_k teria k registros em seu estado correspondente a s_1, s_2, ..., s_k. O StepName.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 é referida como tendo uma sequência ativa .

Lógica de correspondência

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

Verificação 1: Se o estado da etapa anterior (s_k-1) não estiver vazio e r atender ao de Condição de s_k, ocorrerá uma correspondência. A correspondência leva às seguintes ações:
1. O estado de s_k é apurado.
2. O estado de s_k-1 é promovido para se tornar o estado de s_k.
3. As atribuições de s_k são calculadas e se estendem r.
4. O de estendido é adicionado à saída e ao estado de s_k.
Observação

Se Check 1 resulta em uma partida, Check 2 é desconsiderado, e r passa a ser avaliado contra s_k-1.
Verificação 2: Se o estado de s_k tem uma sequência ativa ou s_k é o primeiro passo, e r atende ao Condição de s_k, então ocorre 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 estendido r.
3. Se s_k for definido como output=all, o de r estendido será adicionado à saída.
4. Se s_k for o primeiro passo, uma nova sequência começa e o ID de correspondência aumenta em 1. Isso só afeta a saída quando with_match_id é usada.

Uma vez concluídas as verificações de s_k, r passa a ser avaliado contra s_k-1.

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

Exemplos

O exemplo nesta seção mostra como usar a sintaxe para ajudá-lo a começar.

Os exemplos neste artigo usam tabelas disponíveis publicamente no de cluster de ajuda, como a tabela StormEvents no banco de dados Samples.

Os exemplos neste artigo usam tabelas disponíveis publicamente, como a tabela StormEvents na análise do tempo dados de exemplo.

Soma acumulada

Calcule a soma cumulativa de uma coluna de entrada. O resultado deste exemplo é equivalente ao uso de row_cumsum().

Executar a consulta

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

Output

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 acumulada para duas colunas de entrada, redefina o valor da soma para o valor de registro atual sempre que a soma acumulada atingir 10 ou mais.

Executar a consulta

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

Output

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

Preencher uma coluna

Preencha uma coluna de cadeia de caracteres. A cada valor vazio é atribuído o último valor não vazio visto.

Executar a consulta

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

Output

Ts	Evento	Event_filled
00:00:00	Um	Um
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 começa. 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 saída todos os registros da entrada, enquanto endSession captura registros que acontecem a mais de 30 m do valor sessionStart para a correspondência atual. A etapa endSession tem output=none significa que não produz registros de saída. A etapa endSession é usada para avançar o estado da partida atual de inSession para endSession, permitindo que uma nova partida (sessão) comece, a partir do registro atual.

Executar a consulta

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

Output

Ts	Evento	sessionStart	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 Iniciar e Parar

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

Executar a consulta

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

Output

Ts	Evento	m_id
00:01:00	Início	0
00:02:00	B	0
00:03:00	D	0
00:04:00	Parar	0
00:08:00	Início	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 por State com limites personalizados nos tempos entre os eventos (Tornado dentro de 1h e Thunderstorm Wind dentro de 2h). Este exemplo é semelhante ao plugin funnel_sequence_completion, mas permite maior flexibilidade.

Executar a consulta

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

Output

Tipo de Evento	dcount_State
Salve	50
Tornado	34
Vento Trovoada	32

Passo a passo da lógica de varredura

Esta seção demonstra a lógica de verificação de usando um passo a passo do Eventos entre iniciar e parar exemplo:

Executar a consulta

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

Output

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

O Estado

Pense no estado do operador scan 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 State.

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

passo a passo	s2. Ts	s2. Evento	s3. Ts	s3. Evento
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 através de cada registro da tabela Events, 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 em ordem inversa, da última etapa (s3) para a primeira etapa (s1).

Recorde 1

Ts	Evento
0 metros	"A"

Registar a avaliação em cada etapa:

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

Estado:

passo a passo	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1	X	X	X	X
s2			X	X
s3

Recorde 2

Ts	Evento
1 milhão	"Início"

Registar a avaliação em cada etapa:

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

Estado:

passo a passo	m_id	s1. Ts	s1. Evento	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1	0	00:01:00	"Início"	X	X	X	X
s2						X	X
s3

Recorde 3

Ts	Evento
2 milhões	"B"

Registar a avaliação em cada etapa:

s3: Verificação 1 não é passada porque o estado de s2 está vazio e Verificação 2 não é passada porque s3 falta uma sequência ativa.
s2: Verificação 1 é passado 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. Record 3 e seus m_id (0) são adicionados ao estado e à saída.
s1: de Verificação 1 é irrelevante porque não há nenhuma etapa anterior e Verificação 2 não é aprovada porque o registro não atende à condição de Event == "Start".

Estado:

passo a passo	m_id	s1. Ts	s1. Evento	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1				X	X	X	X
s2	0	00:01:00	"Início"	00:02:00	"B"	X	X
s3

Recorde 4

Ts	Evento
3 milhões	"D"

Registar a avaliação em cada etapa:

s3: Verificação 1 não é passada porque o registro não atende à condição de Event == "Stop"e Verificação 2 não é passada porque s3 não tem uma sequência ativa.
s2: Verificação 1 não é passado porque o estado de s1 está vazio. ele passa Verificação 2 porque atende à condição de Ts - s1.Ts < 5m. Record 4 e seus 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: de Verificação 1 é irrelevante porque não há nenhuma etapa anterior e Verificação 2 não é aprovada porque o registro não atende à condição de Event == "Start".

Estado:

passo a passo	m_id	s1. Ts	s1. Evento	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1				X	X	X	X
s2	0	00:01:00	"Início"	00:03:00	"D"	X	X
s3

Recorde 5

Ts	Evento
4 milhões	"Parar"

Registar a avaliação em cada etapa:

s3: Verificação 1 é passado porque s2 não está vazio e atende à condição s3 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. Record 5 e seus m_id (0) são adicionados ao estado e à saída.
s2: Verificação 1 não é passada porque o estado de s1 está vazio e Verificação 2 não é passada porque s2 falta uma sequência ativa.
s1: Verificação 1 é irrelevante porque não há nenhuma etapa anterior. Verificação 2 não é aprovada porque o registro não atende à condição de Event == "Start".

Estado:

passo a passo	m_id	s1. Ts	s1. Evento	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1				X	X	X	X
s2						X	X
s3	0	00:01:00	"Início"	00:03:00	"D"	00:04:00	"Parar"

Recorde 6

Ts	Evento
6 metros	"C"

Registar a avaliação em cada etapa:

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

Estado:

passo a passo	m_id	s1. Ts	s1. Evento	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1				X	X	X	X
s2						X	X
s3	0	00:01:00	"Início"	00:03:00	"D"	00:04:00	"Parar"

Recorde 7

Ts	Evento
8 milhões	"Início"

Registar a avaliação em cada etapa:

s3: Verificação 1 não é passada porque o estado de s2 está vazio e Verificação 2 não é aprovada porque não atende à condição de Event == "Stop".
s2: Verificação 1 não é passada porque o estado de s1 está vazio e Verificação 2 não é passada porque s2 falta uma sequência ativa.
s1: Verificação 1 não é aprovada porque não há nenhuma etapa anterior. ele passa Verificação 2 porque atende à condição de Event == "Start". Esta partida inicia uma nova sequência em s1 com um novo m_id. Record 7 e seu m_id (1) são adicionados ao estado e à saída.

Estado:

passo a passo	m_id	s1. Ts	s1. Evento	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1	1	00:08:00	"Início"	X	X	X	X
s2						X	X
s3	0	00:01:00	"Início"	00:03:00	"D"	00:04:00	"Parar"

Observação

Agora há duas sequências ativas no estado.

Recorde 8

Ts	Evento
11 milhões	"E"

Registar a avaliação em cada etapa:

s3: Verificação 1 não é passada porque o estado de s2 está vazio e Verificação 2 não é aprovada porque não atende à condição s3 de Event == "Stop".
s2: Verificação 1 é passado 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. Record 8 e seu m_id (1) são adicionados ao estado e à saída.
s1: de Verificação 1 é irrelevante porque não há nenhuma etapa anterior e Verificação 2 não é aprovada porque o registro não atende à condição de Event == "Start".

Estado:

passo a passo	m_id	s1. Ts	s1. Evento	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1				X	X	X	X
s2	1	00:08:00	"Início"	00:11:00	"E"	X	X
s3	0	00:01:00	"Início"	00:03:00	"D"	00:04:00	"Parar"

Recorde 9

Ts	Evento
12 milhões	"Parar"

Registar a avaliação em cada etapa:

s3: Verificação 1 é passado porque s2 não está vazio e atende à condição s3 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. Record 9 e seu m_id (1) são adicionados ao estado e à saída.
s2: Verificação 1 não é passada porque o estado de s1 está vazio e Verificação 2 não é passada porque s2 falta uma sequência ativa.
s1: Verificação 1 não é aprovada porque não há nenhuma etapa anterior. ele passa Verificação 2 porque atende à condição de Event == "Start". Esta partida inicia uma nova sequência em s1 com um novo m_id.

Estado:

passo a passo	m_id	s1. Ts	s1. Evento	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1				X	X	X	X
s2						X	X
s3	1	00:08:00	"Início"	00:11:00	"E"	00:12:00	"Parar"

Produção final

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

Partilhar via

operador de varredura

Sintaxe

sintaxe ColumnDeclarations

sintaxe StepDefinition

Parâmetros

Devoluções

Lógica de varredura

Estado

Lógica de correspondência

Exemplos

Soma acumulada

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

Preencher uma coluna

Marcação de sessões

Eventos entre Iniciar e Parar

Calcular um funil personalizado de eventos

Passo a passo da lógica de varredura

O Estado

A lógica de correspondência

Recorde 1

Recorde 2

Recorde 3

Recorde 4

Recorde 5

Recorde 6

Recorde 7

Recorde 8

Recorde 9

Produção final

Comentários

Recursos adicionais