operador scan
Examina dados, faz a correspondência 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 do registro correspondente é determinada pelo registro de entrada e pelas atribuições definidas nas etapas do operador.
Syntax
T| scan
[ with_match_id
=
MatchIdColumnName ] [ declare
(
ColumnDeclarations)
] with
(
StepDefinitions)
Sintaxe ColumnDeclarations
Columnname:
ColumnType[=
DefaultValue ] [,
... ]
Sintaxe StepDefinition
step
StepName [ output
| last
all
| none
= ] :
Condition [ =>
Column=
Assignment [,
... ] ];
Saiba mais sobre as convenções de sintaxe.
Parâmetros
Nome | Tipo | Obrigatório | Descrição |
---|---|---|---|
T | string |
✔️ | A origem 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 são valores atribuídos 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 que é avaliada como true ou false que 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 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 correspondentes à etapa. O padrão é all . |
Retornos
Um registro para cada correspondência de um registro da entrada para uma etapa. O esquema da saída é o esquema da origem estendido com a coluna na declare
cláusula .
Lógica de verificação
scan
examina os dados de entrada serializados, registra por registro, comparando cada registro com a condição de cada etapa, levando em conta o estado atual de cada etapa.
Estado
O estado subjacente do scan
operador 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 contém a ID de correspondência para a sequência em andamento.
Se um operador de verificação tiver n etapas denominadas s_1, s_2, ..., s_ns_k teria k registros em seu estado correspondentes 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
referenciaria a 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 verificado corresponde a uma etapa. Quando o estado da etapa atual não está vazio, a etapa é conhecida como 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 até a primeira. Quando um registro r é avaliado em relação a alguma etapa s_k, a seguinte lógica é aplicada:
Verifique 1: Se o estado da etapa anterior (s_k-1) não for vazio e r atender à Condição de s_k, ocorrerá uma correspondência. A correspondência leva às seguintes ações:
- O estado de s_k está limpo.
- O estado de s_k-1 é promovido para se tornar o estado de s_k.
- As atribuições de s_k são calculadas e estendem r.
- O r estendido é adicionado à saída e ao estado de s_k.
Observação
Se a Verificação 1 resultar em uma correspondência, a Verificação 2 será desconsiderada e r passará a ser avaliado em relação a s_k-1.
Verifique 2: Se o estado de s_k tiver uma sequência ativa ou s_k for a primeira etapa e r atender à Condição de s_k, ocorrerá uma correspondência. A correspondência leva às seguintes ações:
- As atribuições de s_k são calculadas e estendem r.
- Os valores que representam s_k no estado de s_k são substituídos pelos valores do r estendido.
- Se s_k for definido como
output=all
, o r estendido será adicionado à saída. - Se s_k for a primeira etapa, uma nova sequência começará e a ID de correspondência aumentará em
1
. Isso afeta apenas a saída quandowith_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 a usar 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 de 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 cadeia de caracteres. Cada valor vazio é atribuído ao ú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 | 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 |
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 do with_match_id
sinalizador , que atribui um valor exclusivo para cada correspondência distinta (sessão) de verificação. 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 ocorrem a mais de 30m do sessionStart
valor da correspondência atual. A endSession
etapa tem output=none
o significado de 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) comece, começando pelo 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 | 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 |
Eventos entre Iniciar e Parar
Localize todas as sequências de eventos entre o evento Start
e o evento Stop
que ocorrem dentro de 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 | Stop | 0 |
00:08:00 | Iniciar | 1 |
00:11:00 | E | 1 |
00:12:00 | Stop | 1 |
Calcular um funil personalizado de eventos
Calcule uma conclusão de funil da sequência Hail
– –Thunderstorm Wind
Tornado
>> com State
limites personalizados nos horários entre os eventos (Tornado
dentro 1h
e Thunderstorm Wind
dentro 2h
de ). Este exemplo é semelhante ao plug-in 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 verificação
Esta seção demonstra a lógica de verificação usando um passo a passo dos eventos entre o exemplo de início e 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, confira Estado.
Para este exemplo, o estado pode ser representado com a seguinte tabela:
Etapa | m_id | s1. Ts | s1. Evento | 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 correspondente
Esta seção segue a lógica de correspondência por meio de 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 em 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 des2
está vazio e a Verificação 2 não é passada porques3
não tem uma sequência ativa.s2
: a verificação 1 não é passada porque o estado des1
está vazio e a Verificação 2 não é passada porques2
não tem uma sequência ativa.s1
: verifique se 1 é irrelevante porque não há nenhuma etapa anterior. A verificação 2 não foi passada porque o registro não atende à condição deEvent == "Start"
. O registro 1 é descartado sem afetar o estado ou a saída.
Estado:
Etapa | m_id | s1. Ts | s1. Evento | s2. Ts | s2. Evento | s3. Ts | s3. Evento |
---|---|---|---|---|---|---|---|
s1 | X | X | X | X | |||
s2 | X | X | |||||
s3 |
Registro 2
Ts | Evento |
---|---|
1m | "Iniciar" |
Registre a avaliação em cada etapa:
s3
: a verificação 1 não é passada porque o estado des2
está vazio e a Verificação 2 não é passada porques3
não tem uma sequência ativa.s2
: a verificação 1 não é passada porque o estado des1
está vazio e a Verificação 2 não é passada porques2
não tem uma sequência ativa.s1
: a verificação 1 é irrelevante porque não há nenhuma etapa anterior. A verificação 2 é passada porque o registro atende à condição deEvent == "Start"
. Essa correspondência inicia uma nova sequência e am_id
é atribuída. O registro 2 e seum_id
(0
) são adicionados ao estado e à saída.
Estado:
Etapa | m_id | s1. Ts | s1. Evento | s2. Ts | s2. Evento | s3. Ts | s3. Evento |
---|---|---|---|---|---|---|---|
s1 | 0 | 00:01:00 | "Iniciar" | X | X | X | X |
s2 | X | X | |||||
s3 |
Registro 3
Ts | Evento |
---|---|
2m | "B" |
Registre a avaliação em cada etapa:
s3
: a verificação 1 não é passada porque o estado des2
está vazio e a Verificação 2 não é passada porques3
não tem uma sequência ativa.s2
: a verificação 1 é passada porque o estado des1
é inompty e o registro atende à condição deTs - s1.Ts < 5m
. Essa correspondência faz com que o estado des1
seja limpo e a sequência ems1
seja promovida paras2
. O registro 3 e seum_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 é passada porque o registro não atende à condição deEvent == "Start"
.
Estado:
Etapa | m_id | s1. Ts | s1. Evento | s2. Ts | s2. Evento | s3. Ts | s3. Evento |
---|---|---|---|---|---|---|---|
s1 | X | X | X | X | |||
s2 | 0 | 00:01:00 | "Iniciar" | 00:02:00 | "B" | X | X |
s3 |
Registro 4
Ts | Evento |
---|---|
3m | "D" |
Registre a avaliação em cada etapa:
s3
: a verificação 1 não é passada porque o registro não atende à condição deEvent == "Stop"
e a Verificação 2 não é passada porques3
não tem uma sequência ativa.s2
: verifique se 1 não foi passado porque o estado des1
está vazio. ele passa a Verificação 2 porque atende à condição deTs - s1.Ts < 5m
. O registro 4 e seum_id
(0
) são adicionados ao estado e à saída. Os valores desse registro substituem os valores de estado anteriores paras2.Ts
es2.Event
.s1
: a verificação 1 é irrelevante porque não há nenhuma etapa anterior e a Verificação 2 não é passada porque o registro não atende à condição deEvent == "Start"
.
Estado:
Etapa | m_id | s1. Ts | s1. Evento | s2. Ts | s2. Evento | s3. Ts | s3. Evento |
---|---|---|---|---|---|---|---|
s1 | X | X | X | X | |||
s2 | 0 | 00:01:00 | "Iniciar" | 00:03:00 | "D" | X | X |
s3 |
Registro 5
Ts | Evento |
---|---|
4m | "Parar" |
Registre a avaliação em cada etapa:
s3
: verifique se 1 foi passado porques2
não está vazio e atende às3
condição deEvent == "Stop"
. Essa correspondência faz com que o estado des2
seja limpo e a sequência ems2
seja promovida paras3
. O registro 5 e seum_id
(0
) são adicionados ao estado e à saída.s2
: a verificação 1 não é passada porque o estado des1
está vazio e a Verificação 2 não é passada porques2
não tem uma sequência ativa.s1
: verifique se 1 é irrelevante porque não há nenhuma etapa anterior. A verificação 2 não foi passada porque o registro não atende à condição deEvent == "Start"
.
Estado:
Etapa | 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 | "Iniciar" | 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 passada porque o estado des2
está vazio e a Verificação 2 não é passada porques3
não atende às3
condição deEvent == "Stop"
.s2
: a verificação 1 não é passada porque o estado des1
está vazio e a Verificação 2 não é passada porques2
não tem uma sequência ativa.s1
: a verificação 1 não foi passada porque não há nenhuma etapa anterior e a Verificação 2 não foi passada porque não atende à condição deEvent == "Start"
. O registro 6 é descartado sem afetar o estado ou a saída.
Estado:
Etapa | 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 | "Iniciar" | 00:03:00 | "D" | 00:04:00 | "Parar" |
Registro 7
Ts | Evento |
---|---|
8m | "Iniciar" |
Registre a avaliação em cada etapa:
s3
: a verificação 1 não foi passada porque o estado des2
está vazio e a Verificação 2 não é passada porque não atende à condição deEvent == "Stop"
.s2
: a verificação 1 não é passada porque o estado des1
está vazio e a Verificação 2 não é passada porques2
não tem uma sequência ativa.s1
: a verificação 1 não foi passada porque não há nenhuma etapa anterior. ele passa a Verificação 2 porque atende à condição deEvent == "Start"
. Essa correspondência inicia uma nova sequência nos1
com um novom_id
. O registro 7 e seum_id
(1
) são adicionados ao estado e à saída.
Estado:
Etapa | m_id | s1. Ts | s1. Evento | s2. Ts | s2. Evento | s3. Ts | s3. Evento |
---|---|---|---|---|---|---|---|
s1 | 1 | 00:08:00 | "Iniciar" | X | X | X | X |
s2 | X | X | |||||
s3 | 0 | 00:01:00 | "Iniciar" | 00:03:00 | "D" | 00:04:00 | "Parar" |
Observação
Agora há duas sequências ativas no estado .
Registro 8
Ts | Evento |
---|---|
11m | "E" |
Registre a avaliação em cada etapa:
s3
: a verificação 1 não foi passada porque o estado des2
está vazio e a Verificação 2 não é passada porque não atende às3
condição deEvent == "Stop"
.s2
: verifique se 1 foi passado porque o estado des1
não está vazio e o registro atende à condição deTs - s1.Ts < 5m
. Essa correspondência faz com que o estado des1
seja limpo e a sequência ems1
seja promovida paras2
. O registro 8 e seum_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 é passada porque o registro não atende à condição deEvent == "Start"
.
Estado:
Etapa | m_id | s1. Ts | s1. Evento | s2. Ts | s2. Evento | s3. Ts | s3. Evento |
---|---|---|---|---|---|---|---|
s1 | X | X | X | X | |||
s2 | 1 | 00:08:00 | "Iniciar" | 00:11:00 | "E" | X | X |
s3 | 0 | 00:01:00 | "Iniciar" | 00:03:00 | "D" | 00:04:00 | "Parar" |
Registro 9
Ts | Evento |
---|---|
12m | "Parar" |
Registre a avaliação em cada etapa:
s3
: verifique se 1 foi passado porques2
não está vazio e atende às3
condição deEvent == "Stop"
. Essa correspondência faz com que o estado des2
seja limpo e a sequência ems2
seja promovida paras3
. O registro 9 e seum_id
(1
) são adicionados ao estado e à saída.s2
: a verificação 1 não é passada porque o estado des1
está vazio e a Verificação 2 não é passada porques2
não tem uma sequência ativa.s1
: a verificação 1 não foi passada porque não há nenhuma etapa anterior. ele passa a Verificação 2 porque atende à condição deEvent == "Start"
. Essa correspondência inicia uma nova sequência nos1
com um novom_id
.
Estado:
Etapa | 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 | "Iniciar" | 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 | Stop | 0 |
00:08:00 | Iniciar | 1 |
00:11:00 | E | 1 |
00:12:00 | Stop | 1 |
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de