scan operator

Artículo
08/24/2023

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.

Syntax

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

Sintaxis de ColumnDeclarations

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

Sintaxis stepDefinition

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

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

Parámetros

Nombre	Tipo	Requerido	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.
Condition	`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 es `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. De manera predeterminada, 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.

State

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 examinado coincide con un paso. Cuando el estado del paso actual no es vacío, el paso se conoce como tener una secuencia activa.

Lógica coincidente

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

Comprobación 1: Si el estado del paso anterior (s_k-1) no es vacío 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 ignora Check 2 y r pasa a 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 estado de s_k se reemplazan por los valores de la r extendida.
3. Si s_k se define como output=all, el r extendido se agrega a la salida.
4. Si s_k es el primer paso, comienza una nueva secuencia y el identificador de coincidencia aumenta por 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 a usar 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

Relleno hacia delante de una columna

Rellene una columna de cadena. A cada valor vacío se le asigna el último valor no vacío 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 la with_match_id 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 30 m del sessionStart valor de la 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), comenzando desde 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 producen 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	Inicio	0
00:02:00	B	0
00:03:00	D	0
00:04:00	Stop	0
00:08:00	Inicio	1
00:11:00	E	1
00:12:00	Stop	1

Cálculo de un embudo personalizado de eventos

Calcular una finalización de embudo de la secuencia Hail :Thunderstorm Wind>Tornado> mediante State umbrales personalizados en los tiempos 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:

paso	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1	X	X	X	X
s2			X	X
s3

"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 coincidente 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 la comprobación 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 la comprobación 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:

paso	s2. Ts	s2. Evento	s3. Ts	s3. Evento
s1	X	X	X	X
s2			X	X
s3

Registro 2

Ts	Evento
1 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 la comprobación 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 la comprobación 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 se asigna .m_id El registro 2 y su m_id (0) se agregan al estado y a la salida.

Estado:

paso	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 la comprobación 2 no se pasa porque s3 carece de una secuencia activa.
s2: se pasa la comprobación 1 porque el estado de s1 no es 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: la comprobación 1 es irrelevante porque no hay ningún paso anterior y la comprobación 2 no se pasa porque el registro no cumple la condición de Event == "Start".

Estado:

paso	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: la comprobación 1 es irrelevante porque no hay ningún paso anterior y la comprobación 2 no se pasa porque el registro no cumple la condición de Event == "Start".

Estado:

paso	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 vacía 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 la comprobación 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:

paso	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 m	"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 la comprobación 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 la comprobación 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 la comprobación 2 no se pasa porque no cumple la condición de Event == "Start". El registro 6 se descarta sin afectar al estado o la salida.

Estado:

paso	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 la comprobación 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 la comprobación 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:

paso	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 la comprobación 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 no es 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: la comprobación 1 es irrelevante porque no hay ningún paso anterior y la comprobación 2 no se pasa porque el registro no cumple la condición de Event == "Start".

Estado:

paso	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 vacía 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 la comprobación 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:

paso	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	Inicio	0
00:02:00	B	0
00:03:00	D	0
00:04:00	Stop	0
00:08:00	Inicio	1
00:11:00	E	1
00:12:00	Stop	1

scan operator

Syntax

Sintaxis de ColumnDeclarations

Sintaxis stepDefinition

Parámetros

Devoluciones

Lógica de examen

State

Lógica coincidente

Ejemplos

Suma acumulativa

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

Relleno hacia delante de una columna

Etiquetado de sesiones

Eventos entre Start y Stop

Cálculo de un embudo personalizado de eventos

Tutorial de lógica de examen

El estado

La lógica coincidente

Registro 1

Registro 2

Registro 3

Registro 4

Registro 5

Registro 6

Registro 7

Registro 8

Registro 9

Salida final

Comentarios

Comentarios

Recursos adicionales