Оператор scan

Статья
11/23/2024

Область применения: ✅Microsoft Fabric ✅Azure Data Explorer✅Azure Monitor ✅Microsoft Sentinel

Сканирует данные, сопоставляет их и создает последовательности на основе предикатов.

Соответствующие записи определяются в соответствии с предикатами, определенными в шагах оператора. Предикат может зависеть от состояния, созданного предыдущими шагами. Выходные данные для соответствующей записи определяются входной записью и назначениями, определенными в шагах оператора.

Синтаксис

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

Синтаксис columnDeclarations

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

Синтаксис StepDefinition

stepStepName [ outputall | | none = last: ] Условие [ => Назначение столбцов = [, ... ];

Дополнительные сведения о соглашениях синтаксиса.

Параметры

Имя (название)	Type	Обязательно	Описание
T	`string`	✔️	Входной табличный источник.
MatchIdColumnName	`string`		Имя столбца типа `long` , добавляемого к выходным данным в рамках выполнения сканирования. Указывает 0-й индекс соответствия для записи.
СтолбцыDeclarations	`string`		Объявляет расширение для схемы T. Эти столбцы назначаются значениями в шагах. Если значение не назначено, возвращается значение DefaultValue . Если иное не указано, значение DefaultValue не задано `null`.
StepName	`string`	✔️	Используется для ссылки на значения в состоянии сканирования условий и назначений. Имя шага должно быть уникальным.
Условие	`string`	✔️	Выражение, которое оценивается `true` или `false` определяет, какие записи из входных данных соответствуют шагу. Запись соответствует шагу, когда условие находится `true` в состоянии шага или с состоянием предыдущего шага.
Передача прав и обязанностей	`string`		Скалярное выражение, назначенное соответствующему столбцу, когда запись соответствует шагу.
`output`	`string`		Управляет логикой вывода шага на повторяющихся совпадениях. `all` Выводит все записи, соответствующие шагу, `last` выводит только последнюю запись в серии повторяющихся совпадений для шага и `none` не выводит записи, соответствующие шагу. Значение по умолчанию — `all`.

Возвраты

Запись для каждого совпадения записи из входных данных на шаг. Схема выходных данных — это схема источника, расширенная с столбцом в предложении declare .

Логика сканирования

scan передает сериализованные входные данные, запись по записи, сравнивая каждую запись с условием каждого шага при учете текущего состояния каждого шага.

Штат

Базовое состояние scan оператора можно рассматривать как таблицу с строкой для каждого.step Каждый шаг сохраняет собственное состояние с последними значениями столбцов и объявленными переменными из всех предыдущих шагов и текущего шага. При необходимости он также содержит идентификатор соответствия для текущей последовательности.

Если оператор сканирования имеет n шагов с именем s_1, s_2, ..., s_n затем s_k будет иметь записи k в своем состоянии, соответствующее s_1, s_2, ..., s_k. Имя шага.Формат ColumnName используется для ссылки на значение в состоянии. Например, s_2.col1 будет ссылаться на столбец col1 , принадлежащий шагу s_2 в состоянии s_k. Подробный пример см. в пошаговом руководстве по логике сканирования.

Состояние запускается пустым и обновляется всякий раз, когда сканированная входная запись соответствует шагу. Если состояние текущего шага не является непустым, шаг называется активным последовательность.

Логика сопоставления

Каждая входная запись вычисляется по всем шагам в обратном порядке от последнего шага до первого. При оценке записи на некоторых шагах s_k применяется следующая логика:

Проверьте 1. Если состояние предыдущего шага (s_k-1) непустимо, а r соответствует условию s_k, то происходит совпадение. Совпадение приводит к следующим действиям:
1. Состояние s_k очищается.
2. Состояние s_k-1 способствует тому, чтобы стать состоянием s_k.
3. Назначения s_k вычисляются и расширяются.
4. Расширенный r добавляется в выходные данные и в состояние s_k.
Примечание.

Если проверка 1 приводит к совпадению, проверка 2 игнорируется, и r переходит к оценке по s_k-1.
Проверьте 2. Если состояние s_k имеет активную последовательность или s_k является первым шагом, и r соответствует условию s_k, то возникает совпадение. Совпадение приводит к следующим действиям:
1. Назначения s_k вычисляются и расширяются.
2. Значения, представляющие s_k в состоянии s_k , заменяются значениями расширенного r.
3. Если s_k определен как output=all, расширенный r добавляется в выходные данные.
4. Если s_k является первым шагом, начинается новая последовательность, а идентификатор соответствия увеличивается на 1. Это влияет только на выходные данные при with_match_id использовании.

После завершения проверок s_k r переходит к оценке по s_k-1.

Подробный пример этой логики см. в пошаговом руководстве по логике сканирования.

Примеры

Совокупная сумма

Вычислите совокупную сумму для входного столбца. Результат этого примера эквивалентен использованию 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;
)

Выходные данные

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

Совокупная сумма для нескольких столбцов с условием сброса

Вычислите совокупную сумму для двух входных столбцов, сбросьте значение суммы до текущего значения записи, когда суммарная сумма достигла 10 или более.

Выполнить запрос

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

Выходные данные

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

Заливка столбца вперед

Заполните строковый столбец. Каждое пустое значение присваивается последнему видное значение nonempty.

Выполнить запрос

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

Выходные данные

Ts	Мероприятие	Event_filled
00:00:00	а	а
00:01:00		а
00:02:00	Б	Б
00:03:00		Б
00:04:00		Б
00:06:00	C	C
00:08:00		C
00:11:00	D	D
00:12:00		D

Теги сеансов

Разделите входные данные на сеансы: сеанс заканчивается 30 минут после первого события сеанса, после которого начинается новый сеанс. Обратите внимание на использование флага with_match_id , которое назначает уникальное значение для каждого отдельного совпадения (сеанса) сканирования. Кроме того, обратите внимание на то, что в этом примере используется специальное использование двух шагов , inSession true поэтому оно записывает и выводит все записи из входных данных при endSession записи записей, которые происходят более 30 млн из sessionStart значения текущего совпадения. Шаг endSession имеет значение, output=none что он не создает выходные записи. Этот endSession шаг используется для продвижения состояния текущего совпадения до inSession endSession, что позволяет начать новый матч (сеанс), начиная с текущей записи.

Выполнить запрос

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

Выходные данные

Ts	Мероприятие	sessionStart	session_id
00:00:00	а	00:00:00	0
00:01:00	а	00:00:00	0
00:02:00	Б	00:00:00	0
00:03:00	D	00:00:00	0
00:32:00	Б	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	а	01:15:00	2

События между запуском и остановкой

Найдите все последовательности событий между событием Start и событием Stop , которое происходит в течение 5 минут. Назначьте идентификатор соответствия для каждой последовательности.

Выполнить запрос

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

Выходные данные

Ts	Мероприятие	m_id
00:01:00	Начать	0
00:02:00	Б	0
00:03:00	D	0
00:04:00	Остановить	0
00:08:00	Начать	1
00:11:00	E	1
00:12:00	Остановить	1

Вычисление настраиваемой воронки событий

Вычислите завершение воронки последовательности Hail —>>TornadoThunderstorm Wind с State пользовательскими порогами времени между событиями (Tornadoвнутри 1h и Thunderstorm Wind внутри).2h Этот пример похож на подключаемый модуль funnel_sequence_completion, но обеспечивает большую гибкость.

Выполнить запрос

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

Выходные данные

EventType	dcount_State
Град	50
Торнадо	34
Ураганный ветер	32

Пошаговое руководство по проверке логики

В этом разделе демонстрируется логика сканирования с помощью пошагового руководства по событиям между запуском и остановкой .

Выполнить запрос

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

Состояние

Подумайте о состоянии scan оператора в виде таблицы со строкой для каждого шага, в котором каждый шаг имеет собственное состояние. Это состояние содержит последние значения столбцов и объявленные переменные из всех предыдущих шагов и текущего шага. Дополнительные сведения см. в разделе "Состояние".

В этом примере состояние может быть представлено в следующей таблице:

step	s2. Ts	s2. Событие	s3. Ts	s3. Событие
s1	X	X	X	X
s2			X	X
s3

Значение "X" указывает, что определенное поле не имеет значения для этого шага.

Логика сопоставления

Этот раздел следует логике сопоставления по каждой записи Events таблицы, объясняя преобразование состояния и выходных данных на каждом шаге.

Примечание.

Входная запись вычисляется по шагам в обратном порядке с последнего шага (s3) до первого шага (s1).

Запись 1

Ts	Мероприятие
0 млн	"A"

Запись оценки на каждом шаге:

s3: проверка 1 не передается, так как состояние s2 пусто, и проверка 2 не передается, так как s3 отсутствует активная последовательность.
s2: проверка 1 не передается, так как состояние s1 пусто, и проверка 2 не передается, так как s2 отсутствует активная последовательность.
s1: проверка 1 не имеет значения, потому что нет предыдущего шага. Проверка 2 не передается, так как запись не соответствует условию Event == "Start". Запись 1 удаляется без влияния на состояние или выходные данные.

Штат:

step	s2. Ts	s2. Событие	s3. Ts	s3. Событие
s1	X	X	X	X
s2			X	X
s3

Запись 2

Ts	Мероприятие
1 мин	"Пуск"

Запись оценки на каждом шаге:

s3: проверка 1 не передается, так как состояние s2 пусто, и проверка 2 не передается, так как s3 отсутствует активная последовательность.
s2: проверка 1 не передается, так как состояние s1 пусто, и проверка 2 не передается, так как s2 отсутствует активная последовательность.
s1: проверка 1 не имеет значения, потому что нет предыдущего шага. Проверка 2 передается, так как запись соответствует условию Event == "Start". Это совпадение инициирует новую последовательность и m_id назначается. Запись 2 и ее m_id (0) добавляются в состояние и выходные данные.

Штат:

step	m_id	s1. Ts	s1. Событие	s2. Ts	s2. Событие	s3. Ts	s3. Событие
s1	0	00:01:00	"Пуск"	X	X	X	X
s2						X	X
s3

Запись 3

Ts	Мероприятие
2 мин	"B"

Запись оценки на каждом шаге:

s3: проверка 1 не передается, так как состояние s2 пусто, и проверка 2 не передается, так как s3 отсутствует активная последовательность.
s2: проверка 1 передается, так как состояние s1 неmpty и запись соответствует условию Ts - s1.Ts < 5m. Это совпадение приводит к очистке состоянияs1, а последовательность s1 должна быть повышена.s2 Запись 3 и ее m_id (0) добавляются в состояние и выходные данные.
s1: проверка 1 не имеет значения, так как предыдущий шаг отсутствует, и проверка 2 не передается, так как запись не соответствует условию Event == "Start".

Штат:

step	m_id	s1. Ts	s1. Событие	s2. Ts	s2. Событие	s3. Ts	s3. Событие
s1				X	X	X	X
s2	0	00:01:00	"Пуск"	00:02:00	"B"	X	X
s3

Запись 4

Ts	Мероприятие
3 мес	"D"

Запись оценки на каждом шаге:

s3: проверка 1 не передается, так как запись не соответствует условию Event == "Stop", и проверка 2 не передается, так как s3 отсутствует активная последовательность.
s2: проверка 1 не передается, так как состояние s1 пусто. он проходит проверку 2 , так как она соответствует условию Ts - s1.Ts < 5m. Запись 4 и ее m_id (0) добавляются в состояние и выходные данные. Значения из этой записи перезаписывают предыдущие значения состояния для s2.Ts и s2.Event.
s1: проверка 1 не имеет значения, так как предыдущий шаг отсутствует, и проверка 2 не передается, так как запись не соответствует условию Event == "Start".

Штат:

step	m_id	s1. Ts	s1. Событие	s2. Ts	s2. Событие	s3. Ts	s3. Событие
s1				X	X	X	X
s2	0	00:01:00	"Пуск"	00:03:00	"D"	X	X
s3

Запись 5

Ts	Мероприятие
4 млн	"Остановить"

Запись оценки на каждом шаге:

s3: проверка 1 передается, так как s2 не является немплетной, и она соответствует условию s3 Event == "Stop". Это совпадение приводит к очистке состоянияs2, а последовательность s2 должна быть повышена.s3 Запись 5 и ее m_id (0) добавляются в состояние и выходные данные.
s2: проверка 1 не передается, так как состояние s1 пусто, и проверка 2 не передается, так как s2 отсутствует активная последовательность.
s1: проверка 1 не имеет значения, потому что нет предыдущего шага. Проверка 2 не передается, так как запись не соответствует условию Event == "Start".

Штат:

step	m_id	s1. Ts	s1. Событие	s2. Ts	s2. Событие	s3. Ts	s3. Событие
s1				X	X	X	X
s2						X	X
s3	0	00:01:00	"Пуск"	00:03:00	"D"	00:04:00	"Остановить"

Запись 6

Ts	Мероприятие
6 млн	"C"

Запись оценки на каждом шаге:

s3: проверка 1 не передается, так как состояние s2 пусто, и проверка 2 не передается, так как s3 не соответствует условию s3 Event == "Stop".
s2: проверка 1 не передается, так как состояние s1 пусто, и проверка 2 не передается, так как s2 отсутствует активная последовательность.
s1: проверка 1 не передается, так как нет предыдущего шага, и проверка 2 не передается, так как она не соответствует условию Event == "Start". Запись 6 удаляется без влияния на состояние или выходные данные.

Штат:

step	m_id	s1. Ts	s1. Событие	s2. Ts	s2. Событие	s3. Ts	s3. Событие
s1				X	X	X	X
s2						X	X
s3	0	00:01:00	"Пуск"	00:03:00	"D"	00:04:00	"Остановить"

Запись 7

Ts	Мероприятие
8 млн	"Пуск"

Запись оценки на каждом шаге:

s3: проверка 1 не передается, так как состояние s2 пусто, и проверка 2 не передается, так как она не соответствует условию Event == "Stop".
s2: проверка 1 не передается, так как состояние s1 пусто, и проверка 2 не передается, так как s2 отсутствует активная последовательность.
s1: проверка 1 не пройдена, так как предыдущий шаг отсутствует. он проходит проверку 2 , так как она соответствует условию Event == "Start". Это совпадение инициирует новую последовательность с s1 новым m_id. Запись 7 и ее m_id (1) добавляются в состояние и выходные данные.

Штат:

step	m_id	s1. Ts	s1. Событие	s2. Ts	s2. Событие	s3. Ts	s3. Событие
s1	1	00:08:00	"Пуск"	X	X	X	X
s2						X	X
s3	0	00:01:00	"Пуск"	00:03:00	"D"	00:04:00	"Остановить"

Примечание.

Теперь в состоянии есть две активные последовательности.

Запись 8

Ts	Мероприятие
11 млн	"E"

Запись оценки на каждом шаге:

s3: проверка 1 не передается, так как состояние s2 пусто, и проверка 2 не передается, так как она не соответствует s3 условию Event == "Stop".
s2: проверка 1 передается, так как состояние s1 неmpty и запись соответствует условию Ts - s1.Ts < 5m. Это совпадение приводит к очистке состоянияs1, а последовательность s1 должна быть повышена.s2 Запись 8 и ее m_id (1) добавляются в состояние и выходные данные.
s1: проверка 1 не имеет значения, так как предыдущий шаг отсутствует, и проверка 2 не передается, так как запись не соответствует условию Event == "Start".

Штат:

step	m_id	s1. Ts	s1. Событие	s2. Ts	s2. Событие	s3. Ts	s3. Событие
s1				X	X	X	X
s2	1	00:08:00	"Пуск"	00:11:00	"E"	X	X
s3	0	00:01:00	"Пуск"	00:03:00	"D"	00:04:00	"Остановить"

Запись 9

Ts	Мероприятие
12 млн	"Остановить"

Запись оценки на каждом шаге:

s3: проверка 1 передается, так как s2 не является немплетной, и она соответствует условию s3 Event == "Stop". Это совпадение приводит к очистке состоянияs2, а последовательность s2 должна быть повышена.s3 Запись 9 и ее m_id (1) добавляются в состояние и выходные данные.
s2: проверка 1 не передается, так как состояние s1 пусто, и проверка 2 не передается, так как s2 отсутствует активная последовательность.
s1: проверка 1 не пройдена, так как предыдущий шаг отсутствует. он проходит проверку 2 , так как она соответствует условию Event == "Start". Это совпадение инициирует новую последовательность с s1 новым m_id.

Штат:

step	m_id	s1. Ts	s1. Событие	s2. Ts	s2. Событие	s3. Ts	s3. Событие
s1				X	X	X	X
s2						X	X
s3	1	00:08:00	"Пуск"	00:11:00	"E"	00:12:00	"Остановить"

Окончательные выходные данные

Ts	Мероприятие	m_id
00:01:00	Начать	0
00:02:00	Б	0
00:03:00	D	0
00:04:00	Остановить	0
00:08:00	Начать	1
00:11:00	E	1
00:12:00	Остановить	1

Поделиться через

Оператор scan

Синтаксис

Синтаксис columnDeclarations

Синтаксис StepDefinition

Параметры

Возвраты

Логика сканирования

Штат

Логика сопоставления

Примеры

Совокупная сумма

Совокупная сумма для нескольких столбцов с условием сброса

Заливка столбца вперед

Теги сеансов

События между запуском и остановкой

Вычисление настраиваемой воронки событий

Пошаговое руководство по проверке логики

Состояние

Логика сопоставления

Запись 1

Запись 2

Запись 3

Запись 4

Запись 5

Запись 6

Запись 7

Запись 8

Запись 9

Окончательные выходные данные

Обратная связь

Дополнительные ресурсы