Operador scan

Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Examina los datos, las coincidencias y crea secuencias en función de los predicados.

Los registros coincidentes se determinan según los predicados definidos en los pasos del operador. Un predicado puede depender del estado generado por los pasos anteriores. La salida del registro coincidente viene determinada por el registro de entrada y las asignaciones definidas en los pasos del operador.

Sintaxis

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

Sintaxis columnDeclarations

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

Sintaxis stepDefinition

stepStepName [ output | nonealllast = | ] : Condition [ => Column = Assignment [, ... ] ];

Obtenga más información sobre las convenciones de sintaxis.

Parámetros

Nombre	Type	Obligatorio	Descripción
T	string	✔️	Origen tabular de entrada.
MatchIdColumnName	string		Nombre de una columna de tipo long que se anexa a la salida como parte de la ejecución del examen. Indica el índice basado en 0 de la coincidencia del registro.
ColumnDeclarations	string		Declara una extensión en el esquema de T. Estas columnas se asignan valores en los pasos. Si no se asigna, se devuelve DefaultValue . A menos que se especifique lo contrario, DefaultValue es null.
StepName	string	✔️	Se usa para hacer referencia a valores en el estado del examen de condiciones y asignaciones. El nombre del paso debe ser único.
Condición	string	✔️	Expresión que se evalúa como true o false que define qué registros de la entrada coinciden con el paso. Un registro coincide con el paso cuando la condición está true con el estado del paso o con el estado del paso anterior.
Cesión	string		Expresión escalar que se asigna a la columna correspondiente cuando un registro coincide con un paso.
output	string		Controla la lógica de salida del paso en coincidencias repetidas. all genera todos los registros que coinciden con el paso, last genera solo el último registro de una serie de coincidencias de repetición para el paso y none no genera registros que coincidan con el paso. El valor predeterminado es all.

Devoluciones

Un registro para cada coincidencia de un registro de la entrada a un paso. El esquema de la salida es el esquema del origen extendido con la columna de la declare cláusula .

Lógica de examen

scan pasa por los datos de entrada serializados, registra por registro, comparando cada registro con la condición de cada paso, teniendo en cuenta el estado actual de cada paso.

Valor

El estado subyacente del scan operador se puede considerar como una tabla con una fila para cada step. Cada paso mantiene su propio estado con los valores más recientes de las columnas y las variables declaradas de todos los pasos anteriores y el paso actual. Si procede, también contiene el identificador de coincidencia de la secuencia en curso.

Si un operador de examen tiene n pasos denominados s_1, s_2, ..., s_n, el paso s_k tendría registros k en su estado correspondiente a s_1, s_2, ..., s_k. StepName.El formato ColumnName se usa para hacer referencia a un valor en el estado. Por ejemplo, s_2.col1 haría referencia a la columna col1 que pertenece al paso s_2 en el estado de s_k. Para obtener un ejemplo detallado, consulte el tutorial de lógica de examen.

El estado comienza vacío y se actualiza cada vez que un registro de entrada escaneado coincide con un paso. Cuando el estado del paso actual no es desempty, el paso se conoce como tener una secuencia activa.

Lógica de coincidencia

Cada registro de entrada se evalúa en todos los pasos en orden inverso, desde el último paso hasta el primero. Cuando se evalúa un registro r en algún paso s_k, se aplica la siguiente lógica:

• Comprobación 1: si el estado del paso anterior (s_k-1) no esempty y r cumple la condición de s_k, se produce una coincidencia. La coincidencia conduce a las siguientes acciones:

  1. Se borra el estado de s_k .
  2. El estado de s_k-1 se promueve para convertirse en el estado de s_k.
  3. Las asignaciones de s_k se calculan y extienden r.
  4. La r extendida se agrega a la salida y al estado de s_k.

  Nota:

  Si Check 1 da como resultado una coincidencia, se omita check 2 y r se mueve para evaluarse con s_k-1.

• Comprobación 2: si el estado de s_k tiene una secuencia activa o s_k es el primer paso y r cumple la condición de s_k, se produce una coincidencia. La coincidencia conduce a las siguientes acciones:

  1. Las asignaciones de s_k se calculan y extienden r.
  2. Los valores que representan s_k en el estado de s_k se reemplazan por los valores de la r extendida.
  3. Si s_k se define como output=all, se agrega el valor de r extendido a la salida.
  4. Si s_k es el primer paso, comienza una nueva secuencia y el identificador de coincidencia aumenta en 1. Esto solo afecta a la salida cuando with_match_id se usa.

Una vez completadas las comprobaciones de s_k , r pasa a evaluarse con s_k-1.

Para obtener un ejemplo detallado de esta lógica, consulte el tutorial de lógica de examen.

Ejemplos

Suma acumulativa

Calcule la suma acumulativa de una columna de entrada. El resultado de este ejemplo es equivalente al uso de row_cumsum()..

Ejecución de la 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;
)

Salida

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

Suma acumulativa en varias columnas con una condición de restablecimiento

Calcule la suma acumulativa de dos columnas de entrada, restablezca el valor de suma al valor de registro actual cada vez que la suma acumulativa alcanzó 10 o más.

Ejecución de la 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);
)

Salida

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

Rellenar hacia delante una columna

Rellene una columna de cadena. A cada valor vacío se le asigna el último valor no desempty visto.

Ejecución de la 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);
)

Salida

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

Etiquetado de sesiones

Dividir la entrada en sesiones: una sesión finaliza 30 minutos después del primer evento de la sesión, después de la cual se inicia una nueva sesión. Tenga en cuenta el uso de with_match_id la marca , que asigna un valor único para cada coincidencia distinta (sesión) del examen. Tenga en cuenta también el uso especial de dos pasos en este ejemplo, inSession tiene true como condición para capturar y generar todos los registros de la entrada mientras endSession captura los registros que se producen más de 30m del valor de la sessionStart coincidencia actual. El endSession paso tiene output=none significado que no genera registros de salida. El endSession paso se usa para avanzar el estado de la coincidencia actual de inSession a endSession, lo que permite que comience una nueva coincidencia (sesión), empezando por el registro actual.

Ejecución de la 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;
)

Salida

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 Start y Stop

Busque todas las secuencias de eventos entre el evento Start y el evento Stop que se produce en un plazo de 5 minutos. Asigne un identificador de coincidencia para cada secuencia.

Ejecución de la 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;
)

Salida

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

Cálculo de un embudo personalizado de eventos

Calcular una finalización del embudo de la secuencia Hail :Thunderstorm Wind>Tornado> mediante State umbrales personalizados en las horas entre los eventos (Tornado dentro 1h y Thunderstorm Wind dentro de ).2h Este ejemplo es similar al complemento funnel_sequence_completion, pero permite una mayor flexibilidad.

Ejecución de la 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

Salida

EventType	dcount_State
Granizo	50
Tornado	34
Viento de tormenta	32

Tutorial de lógica de examen

En esta sección se muestra la lógica de examen mediante un tutorial paso a paso de los eventos entre el ejemplo de inicio y detención :

Ejecución de la 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;
)

El estado

Piense en el estado del scan operador como una tabla con una fila para cada paso, en el que cada paso tiene su propio estado. Este estado contiene los valores más recientes de las columnas y las variables declaradas de todos los pasos anteriores y el paso actual. Para más información, consulte Estado.

En este ejemplo, el estado se puede representar con la tabla siguiente:

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

El "X" indica que un campo específico es irrelevante para ese paso.

La lógica coincidente

En esta sección se sigue la lógica de coincidencia a través de cada registro de la Events tabla, que explica la transformación del estado y la salida en cada paso.

Nota:

Un registro de entrada se evalúa con los pasos en orden inverso, desde el último paso (s3) hasta el primer paso (s1).

Registro 1

Ts	Evento
0 m	"A"

Registre la evaluación en cada paso:

• s3: no se pasa la comprobación 1 porque el estado de s2 está vacío y check 2 no se pasa porque s3 carece de una secuencia activa.
• s2: no se pasa la comprobación 1 porque el estado de s1 está vacío y check 2 no se pasa porque s2 carece de una secuencia activa.
• s1: compruebe que 1 es irrelevante porque no hay ningún paso anterior. La comprobación 2 no se pasa porque el registro no cumple la condición de Event == "Start". El registro 1 se descarta sin afectar al estado o a la salida.

Estado:

step	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
1 min	"Inicio"

Registre la evaluación en cada paso:

• s3: no se pasa la comprobación 1 porque el estado de s2 está vacío y check 2 no se pasa porque s3 carece de una secuencia activa.
• s2: no se pasa la comprobación 1 porque el estado de s1 está vacío y check 2 no se pasa porque s2 carece de una secuencia activa.
• s1: compruebe que 1 es irrelevante porque no hay ningún paso anterior. La comprobación 2 se pasa porque el registro cumple la condición de Event == "Start". Esta coincidencia inicia una nueva secuencia y m_id se asigna . El registro 2 y su m_id (0) se agregan al estado y a la salida.

Estado:

step	m_id	s1. Ts	s1. Evento	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1	0	00:01:00	"Inicio"	X	X	X	X
s2						X	X
s3

Registro 3

Ts	Evento
2 m	"B"

Registre la evaluación en cada paso:

• s3: no se pasa la comprobación 1 porque el estado de s2 está vacío y check 2 no se pasa porque s3 carece de una secuencia activa.
• s2: se pasa la comprobación 1 porque el estado de s1 es no vacío y el registro cumple la condición de Ts - s1.Ts < 5m. Esta coincidencia hace que el estado de s1 se borre y la secuencia de s1 se promueva a s2. El registro 3 y su m_id (0) se agregan al estado y a la salida.
• s1: compruebe que 1 no es irrelevante porque no hay ningún paso anterior y Comprobar 2 no se pasa porque el registro no cumple la condición de Event == "Start".

Estado:

step	m_id	s1. Ts	s1. Evento	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1				X	X	X	X
s2	0	00:01:00	"Inicio"	00:02:00	"B"	X	X
s3

Registro 4

Ts	Evento
3 m	"D"

Registre la evaluación en cada paso:

• s3: no se pasa la comprobación 1 porque el registro no cumple la condición de Event == "Stop"y check 2 no se pasa porque s3 carece de una secuencia activa.
• s2: no se pasa la comprobación 1 porque el estado de s1 está vacío. pasa check 2 porque cumple la condición de Ts - s1.Ts < 5m. El registro 4 y su m_id (0) se agregan al estado y a la salida. Los valores de este registro sobrescriben los valores de estado anteriores para s2.Ts y s2.Event.
• s1: compruebe que 1 no es irrelevante porque no hay ningún paso anterior y Comprobar 2 no se pasa porque el registro no cumple la condición de Event == "Start".

Estado:

step	m_id	s1. Ts	s1. Evento	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1				X	X	X	X
s2	0	00:01:00	"Inicio"	00:03:00	"D"	X	X
s3

Registro 5

Ts	Evento
4 m	"Detener"

Registre la evaluación en cada paso:

• s3: se pasa la comprobación 1 porque s2 no es desempty y cumple la s3 condición de Event == "Stop". Esta coincidencia hace que el estado de s2 se borre y la secuencia de s2 se promueva a s3. El registro 5 y su m_id (0) se agregan al estado y a la salida.
• s2: no se pasa la comprobación 1 porque el estado de s1 está vacío y check 2 no se pasa porque s2 carece de una secuencia activa.
• s1: compruebe que 1 es irrelevante porque no hay ningún paso anterior. La comprobación 2 no se pasa porque el registro no cumple la condición de Event == "Start".

Estado:

step	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	"Inicio"	00:03:00	"D"	00:04:00	"Detener"

Registro 6

Ts	Evento
6 meses	"C"

Registre la evaluación en cada paso:

• s3: no se pasa la comprobación 1 porque el estado de s2 está vacío y check 2 no se pasa porque s3 no cumple la s3 condición de Event == "Stop".
• s2: no se pasa la comprobación 1 porque el estado de s1 está vacío y check 2 no se pasa porque s2 carece de una secuencia activa.
• s1: no se pasa la comprobación 1 porque no hay ningún paso anterior y Comprobar 2 no se pasa porque no cumple la condición de Event == "Start". El registro 6 se descarta sin afectar al estado o a la salida.

Estado:

step	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	"Inicio"	00:03:00	"D"	00:04:00	"Detener"

Registro 7

Ts	Evento
8 m	"Inicio"

Registre la evaluación en cada paso:

• s3: no se pasa la comprobación 1 porque el estado de s2 está vacío y check 2 no se pasa porque no cumple la condición de Event == "Stop".
• s2: no se pasa la comprobación 1 porque el estado de s1 está vacío y check 2 no se pasa porque s2 carece de una secuencia activa.
• s1: compruebe que no se pasa 1 porque no hay ningún paso anterior. pasa check 2 porque cumple la condición de Event == "Start". Esta coincidencia inicia una nueva secuencia en s1 con un nuevo m_id. El registro 7 y su m_id (1) se agregan al estado y a la salida.

Estado:

step	m_id	s1. Ts	s1. Evento	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1	1	00:08:00	"Inicio"	X	X	X	X
s2						X	X
s3	0	00:01:00	"Inicio"	00:03:00	"D"	00:04:00	"Detener"

Nota:

Ahora hay dos secuencias activas en el estado.

Registro 8

Ts	Evento
11 m	"E"

Registre la evaluación en cada paso:

• s3: no se pasa la comprobación 1 porque el estado de s2 está vacío y check 2 no se pasa porque no cumple la s3 condición de Event == "Stop".
• s2: se pasa la comprobación 1 porque el estado de s1 es no vacío y el registro cumple la condición de Ts - s1.Ts < 5m. Esta coincidencia hace que el estado de s1 se borre y la secuencia de s1 se promueva a s2. El registro 8 y su m_id (1) se agregan al estado y a la salida.
• s1: compruebe que 1 no es irrelevante porque no hay ningún paso anterior y Comprobar 2 no se pasa porque el registro no cumple la condición de Event == "Start".

Estado:

step	m_id	s1. Ts	s1. Evento	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1				X	X	X	X
s2	1	00:08:00	"Inicio"	00:11:00	"E"	X	X
s3	0	00:01:00	"Inicio"	00:03:00	"D"	00:04:00	"Detener"

Registro 9

Ts	Evento
12 m	"Detener"

Registre la evaluación en cada paso:

• s3: se pasa la comprobación 1 porque s2 no es desempty y cumple la s3 condición de Event == "Stop". Esta coincidencia hace que el estado de s2 se borre y la secuencia de s2 se promueva a s3. El registro 9 y su m_id (1) se agregan al estado y a la salida.
• s2: no se pasa la comprobación 1 porque el estado de s1 está vacío y check 2 no se pasa porque s2 carece de una secuencia activa.
• s1: compruebe que no se pasa 1 porque no hay ningún paso anterior. pasa check 2 porque cumple la condición de Event == "Start". Esta coincidencia inicia una nueva secuencia en s1 con un nuevo m_id.

Estado:

step	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	"Inicio"	00:11:00	"E"	00:12:00	"Detener"

Salida final

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