Команды OTL

OTL – Open Technology Language – высокоуровневый язык для работы с данными, не требующий от пользователя навыков программирования.

Язык OTL применяется в интерактивной среде разработки EVA для создания поисковых запросов к различным источникам данных для последующей визуализации и анализа данных.

Структура поиска на языке OTL выглядит следующим образом:

данные из индекса <аргументы> | команда1 <аргументы> | команда2 <аргументы> | ...

Запрос состоит из серии команд, разделенных конвейером (|), который принимает выходные данные одной команды и передает их в следующую.

Команды в запросе используются для получения индексированных данных, фильтрации нежелательной и извлечения дополнительной информации, вычисления значений и проведения статистического анализа.

Результаты поиска, извлеченные из индекса, можно рассматривать как динамически создаваемую таблицу.

В документе представлены команды языка OTL.

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

Команда	Действие	Пример
addcoltotals	Добавляет сумму каждого числового поля в конец набора результатов запроса.	... | addcoltotals labelfield=Total label=Flights
addinfo	Добавляет к каждому событию информацию о времени и идентификаторе запроса, в результате выполнения которого получена запись.	... | addinfo
addtotals	Вычисляет арифметическую сумму числовых полей для каждого результата запроса.	... | addtotals Germany Russia USA fieldname=SUM
append	Добавляет результаты подзапроса, как новые записи текущего запроса.	... | append [search index=access_web_server | top 1 clientip by method]
appendcols	Добавляет результаты подзапроса, как новые поля текущего запроса.	... | appendcols [serach index=LA_Air]
appendpipe	Добавляет дополнительные преобразования (subpipeline) к результатам основного запроса.	... | appendpipe [| eval SUM=TerminalA+TerminalB+TerminalC]
bin	Отображает значения поля в дискретный набор значений.	... | bin bins=3 testField
chart	Группирует записи по указанному полю.	... | chart count(Population) by Country
collect	Сохраняет результаты запроса в указанном индексе.	... | collect index=transactions_russia source=transactions sourcetype=transactions
command	Использует функции Spark.	... | command empty_check=isnotnull(phrase)
convert	Конвертирует значения поля в числовые значения.	... | convert ctime(<testField>)
dedup	Удаляет события с повторяющимися значениями полей.	... | table Terminal, Arrival_Departure| dedup Terminal
delta	Вычисляет разницу между текущим значением поля и его значением несколькими записями ранее.	... | where currency="EUR" | sort _time | delta sum as delta_sum_eur
eval	Создаёт новое поле и заполняет его вычисленными значениями.	... | eval currency_low=lower(currency)
eventstats	Считает статистику из значений полей без трансформации исходных данных.	... | eventstats max(temperature) as temperature
fields	Отображает только указанные поля. Синоним команды table.	... | fields testField1 testField2
fieldsummary	Отображает количество значений, максимальное, среднее, минимальное значения и стандартное отклонение для каждого поля.	... | fieldsummary
filldown	Заполняет пропуски значениями из предыдущей записи.	... | filldown
fillnull	Заполняет пропуски указанным значением.	... | fillnull value="noValue"
filter	Фильтрует записи в зависимости от заданного условия. Синоним команды search.	... | filter {"query": "!(Terminal=\"Terminal 6\")"}
foreach	Для каждого из полей выполняет шаблонный подзапрос.	... | foreach test* [eval sum=test1+test2]
head	Отображает заданное количество первых записей запроса.	... | head 3
inputlookup	Загружает данные из csv-файла.	| inputlookup testTable.csv |...
join	Объединяет результаты поискового подзапроса с результатами основного запроса.	search index=... | join [ index=... ]
lookup	Добавляет данные из внешней таблицы.	... | lookup students.csv Name, age
makemv	Конвертирует поле, состоящее из одного значения, в поле, состоящее из нескольких значений.	... | makemv testFied delim=";"
makeresults	Создает (генерирует) требуемое количество результатов поиска.	| makeresults count=3 | ...
mvcombine	Группирует записи, отличающиеся только значениями в отдельных полях.	... | mvcombine testField
mvexpand	Преобразует событие с полем из нескольких значений в несколько отдельных событий.	... | mvexpand fields
nomv	Конвертирует поле, состоящее из нескольких значений, в поле, состоящее из одного значения (в строку).	... | nomv testField
otloadjob	Извлекает из кеша результаты ранее выполненного запроса.	otloadjob spl="index=\"apache\" | ...
otstats	Получает проиндексированные данные из индекса.	otstats index="linux-log" severity="ERR*" | ...
outputlookup	Сохраняет результаты запроса в статическую таблицу (lookup).	... | outputlookup transactions_eur.csv
rangemap	Преобразует числовое поле в текстовое по заданному правилу.	... | rangemap field=sum min=1-5 med=6-15 max=16-30
rare	Находит наименее распространённые значения в выбранных полях.	... | rare 2 Name
rename	Переименовывает одно или несколько полей.	... | rename dest as "destination country"
replace	Заменяет значение поля указанным значением.	... | replace oldValue1 newValue in testField
return	Используется в подзапросах для подстановки в исходный запрос значения из определенной колонки полученного набора данных.	... | return avgTemp] - 1) > 0.05
reverse	Получает записи в обратном порядке.	... | reverse
rex	Применяет регулярное выражение к указанному полю.	... | rex field=testField ".*(?<new_host>Q)(?<new_host2>.*)"
search	Получает необработанные данные из индекса. Синоним команды filter.	search index="linux-log"
sort	Сортирует результаты по заданному полю.	... | sort testField
spath	Извлекает информацию из структурированных данных в формате JSON.	... | spath input=github_response output=commit_author path=commits{}.author.name
stats	Применяет агрегирующую функцию к полю.	... | stats max(testField)
streamstats	Вычисляет статистику по значениям полей в "потоковом" режиме и добавляет поле результата к каждому событию.	... | streamstats sum(testField) window=5
superjoin	Объединяет результаты из таблицы на диске с результатами основного запроса.	… | superjoin id, day type=left format=parquet path=folder/table1
table	Отображает только указанные поля. Синоним команды fields.	... | table testField1 testField2
tail	Отображает заданное количество последних записей запроса.	... | tail 3
timechart	Агрегирует результаты по времени.	... | timechart span=2d sum(Air_traffic) by Terminal
top	Получает наиболее часто встречающиеся значения указанных полей, количество таких значений и их процент среди общего количества значений.	… | top 3 testField
transaction	Находит среди множества записей, сгруппированных по указанному набору полей, первую по времени запись (в своей группе).	... | transaction deposit, well, metric_name, value
transpose	Превращает строки таблицы в столбцы и наоборот.	... | transpose
untable	Преобразует данные из широкой таблицы в длинную таблицу.	... | untable _time, metric_name, value
where	Отфильтровывает записи согласно заданным условиям.	... | where Population > 1000000
xyseries	Конвертирует результаты в пригодный для визуализации табличный формат.	... | xyseries testField1

ADDCOLTOTALS

Команда добавляет сумму каждого числового поля в конец набора результатов запроса. Если указан аргумент labelfield, в таблицу результатов добавляется столбец с указанным именем.

Синтаксис команды

addcoltotals [labelfield=<fieldname>] [label=<string>]

Опциональные параметры:

• labelfield=<fieldname> – определяет имя поля для добавления в набор результатов.

• label=<string> – используется с аргументом labelfield для добавления метки в итоговое событие. Если аргумент labelfield отсутствует, аргумент label не имеет никакого эффекта.

Примеры использования

Пример 1.

Добавляет общую сумму всех транзакций в конец набора результатов поля sum:

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... | addcoltotals labelfield=All_Transactions

Результат:

datetime	currency	dest	sum	All_Transactions
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7
			67	Total

Пример 2.

Выводит количество рейсов (вылетов и прилетов) по всем терминалам аэропорта:

Исходные данные:

Terminal	Arrivals	Departures
Terminal1	80000	40000
Terminal2	30000	50000
Terminal3	60000	90000

Запрос:

... | addcoltotals labelfield=Total label=Flights

Результат:

Terminal	Arrivals	Departures	Total
Terminal1	80000	40000
Terminal2	30000	50000
Terminal3	60000	90000
	170000	180000	Flights

ADDINFO

Команда добавляет поля, общую информацию об идентификаторе запроса и временных интервалах.

Синтаксис команды

addinfo

Следующие поля добавляются к каждому событию при использовании команды addinfo:

Поле	Описание
info_min_time	Самая ранняя временная граница для поиска.
info_max_time	Самая поздняя временная граница для поиска.
info_sid	Идентификатор поиска, который сгенерировал событие.

Примеры использования

Пример 1

Добавляет служебную информацию о поиске к каждому событию.

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... | addinfo

Результат:

datetime	currency	dest	sum	info_min_time	info_max_time	info_sid
1587045110	RUB	Russia	10	1587045000	1587048000	13102
1587045120	USD	Russia	7	1587045000	1587048000	13102
1587045130	EUR	Germany	21	1587045000	1587048000	13102
1587045140	EUR	USA	3	1587045000	1587048000	13102
1587045150	RUB	Germany	19	1587045000	1587048000	13102
1587045160	EUR	Russia	7	1587045000	1587048000	13102

ADDTOTALS

Команда вычисляет арифметическую сумму числовых полей для каждого результата запроса. Сумма помещается в новое поле. Если установлен параметр col = true, команда addtotals добавляет сумму каждого числового поля в конец набора результатов запроса. Кроме того, вместо использования команды addtotals с параметром col = true, можно использовать команду addcoltotals для вычисления итогового события.

Синтаксис команды

addtotals [row=<bool>] [fieldname=<field>] [col=<bool>] [labelfield=<field>] [label=<string>] <field-list>

Обязательный параметр:

• field-list – одно или несколько числовых полей для вычисления суммирующего значения.

Опциональные параметры:

• row=<bool> – указывает, следует ли рассчитывать сумму field-list для каждого события. Это похоже на вычисление итога для каждой строки в таблице. Сумма помещается в новое поле. Имя поля по умолчанию – Total. Если необходимо указать другое имя для поля, используется параметр fieldname. Значение по умолчанию: true.

• fieldname=<field> – используется для указания имени поля, которое содержит рассчитанную сумму списка полей для каждого события. Параметр fieldname действителен только тогда, когда row = true.

• col=<bool> – указывает на необходимость добавления нового события, называемого сводным событием, вниз списка событий. Сводное событие отображает сумму каждого поля в событиях, аналогично вычислению итоговых значений столбцов в таблице.

  Значение по умолчанию: false.

• labelfield=<field> – используется для указания поля метки сводного события. Аргумент labelfield действителен только тогда, когда col = true.

• label=<string> – используется для указания метки строки для сводного события.

Примеры использования

Пример 1

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

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... 
| chart sum(sum) over currency by dest 
| fillnull 
| addtotals  Germany Russia USA fieldname=SUM 

Результат:

currency	Germany	Russia	USA	SUM
EUR	21	7	3	31
RUB	19	10	0	29
USD	0	7	0	7

Пример 2

Считает общее количество прилётов в аэропорту за каждые сутки и для каждого терминала за все дни.

Исходные данные:

Terminal	Date	Arrivals	Departures
TerminalA	27.03.2019	235	321
TerminalB	27.03.2019	178	167
TerminalC	27.03.2019	79	68
TerminalA	28.03.2019	216	278
TerminalB	28.03.2019	165	145
TerminalC	28.03.2019	64	60
TerminalA	29.03.2019	223	216
TerminalB	29.03.2019	143	120
TerminalC	29.03.2019	87	98

Запрос:

... 
| chart sum(Arrivals) by Terminal over Date 
| addtotals fieldname=Arrivals/day col=true labelfield=Arrivals/Terminal TerminalA TerminalB TerminalC

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

Результат:

Date	Terminal A	Terminal B	Terminal C	Arrivals/day	Arrivals/Terminal
27.03.2019	235	178	79	492
28.03.2019	216	165	64	445
29.03.2019	223	143	87	453
	674	486	230	1390	Total

APPEND (UNION)

Команда добавляет результаты подзапроса к текущим результатам. Синоним команды – union.

Синтаксис команды

append <subsearch>

Обязательный параметр:

• subsearch – дополнительный запрос, результаты выполнения которого необходимо добавить. Подзапрос должен быть заключен в квадратные скобки.

Примеры использования

Пример 1

Подсчитывает количество различных IP-адресов, с которых обращались к веб-серверу. Затем находит пользователя, который обращался к веб-серверу в разрезе типа запроса (method).

Исходные данные:

_time	clientip	method
2020-04-20 18:22:16	91.205.189.15	GET
2020-04-20 18:20:56	182.236.164.11	GET
2020-04-20 18:18:59	198.35.1.75	GET
2020-04-20 18:16:29	221.204.246.72	POST
...	...	...

Запрос:

index=access_web_server 
| stats dc(clientip), count by method 
| append [search index=access_web_server | top 1 clientip by method]

Результат:

method	dc(clientip)	count	clientip	percent
GET	182	24866
POST	182	14666
GET		651	87.194.216.51	2.618033
POST		385	87.194.216.51	2.625119

Пример 2.

Выводит статистику по транзакциям (самые частые и редкие валюты, самые маленькие и большие суммы транзакций, топ мест назначения) в разрезе стран.

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... 
| stats max(currency), min(currency), max(sum), min(sum) by dest 
| rename  max(currency) as "most frequent currency", min(currency) as "rarest currency", max(sum) as "maximum amount", min(sum) as "minimum amount" 
| append [| ... | top dest | rename count as "top dest"]

Результат:

dest	most frequent currency	rarest currency	maximum amount	minimum amount	top dest	percent
USA	USD	USD	3	3
Germany	EUR	EUR	21	19
Russia	RUB	EUR	10	7
Russia					3	50
Germany					2	33.333333333333336
USA					1	16.666666666666668

APPENDCOLS

Команда добавляет результаты подзапроса, как новые поля текущего запроса.

Синтаксис команды

appendcols <subsearch>

Обязательный параметр:

• subsearch — подзапрос, результаты выполнения которого будут добавлены в основной запрос.

Примеры использования

Пример 1

Дополняет информацию о работе аэропорта метеорологическими сводками.

Запрос:

| serach index=LA_Air 
| appendcols subsearch=[search index=weather]

Пример 2

Дополняет данные о транзакциях информацией о курсе валют:

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

datetime	USD exchange	EUR exchange
1587045110	77,28	83,63

Запрос:

| otstats index=transactions 
| appendcols [otstats index=currencies]

Результат:

datetime	currency	dest	sum	USD exchange	EUR exchange
1587045110	RUB	Russia	10	77,28	83,63
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Пример 3

Подсчитывает сколько раз встречается определённое поле в логах сервера и использует это значение для вычисления других полей.

... 
| stats dc(userID) as totalUsers
| appendcols [ ... AND "text" | addinfo | where _time >= info_min_time AND _time <=info_max_time | stats count(field) as variableA ]
| eval variableB = (variableA/totalUsers)

Сначала в запросе используется команда stats для подсчета количества отдельных пользователей на сервере, это значение присваивается полю totalUsers.

Затем используется команда appendcols для добавления информации о том, сколько раз за определённое время встречается интересующее нас поле – variableA.

В конце подсчитываем новое поле variableB на основе полученных данных.

APPENDPIPE

Команда добавляет дополнительные преобразования (subpipeline) к результатам основного запроса. В отличие от подзапроса (subsearch), subpipeline не запускается первым. Subpipeline запускается тогда, когда запрос достигает команды appendpipe.

Синтаксис команды

appendpipe <subpipeline>

Обязательный параметр:

• subpipeline – список преобразований, которые применяются к результатам выполнения основного запроса.

Примеры использования

Пример 1

Считает сумму прилётов за день во все терминалы аэропорта.

Исходные данные:

Terminal	Date	Arrivals	Departures
TerminalA	27.03.2019	235	321
TerminalB	27.03.2019	178	167
TerminalC	27.03.2019	79	68
TerminalA	28.03.2019	216	278
TerminalB	28.03.2019	165	145
TerminalC	28.03.2019	64	60
TerminalA	29.03.2019	223	216
TerminalB	29.03.2019	143	120
TerminalC	29.03.2019	87	98

Запрос:

... 
| chart sum(Arrivals) by Terminal over Date 
| appendpipe [| eval SUM=TerminalA+TerminalB+TerminalC]

Результат:

Date	TerminalA	TerminalB	TerminalC	SUM
27.03.2019	235	178	79	492
28.03.2019	216	165	64	453
29.03.2019	223	143	87	445

BIN

Команда отображает числовые значения поля в дискретный набор значений таким образом, что все значения из заданного диапазона значений этого же поля принимают одно из значений дискретного ряда.

Синтаксис команды

bin [<bin-options>...] <field> [AS <newfield>]

Обязательный параметр:

• field – поле, к которому будет применяться дискретизация.

Опциональные параметры:

• bin-options — опции команды bin:

  • bins – устанавливает максимальное число фрагментов отображения (дискретизации).

  • span – устанавливает размер каждого фрагмента отображения (дискретизации) в единицах времени. Параметр применим только к полю _time.

• AS <newfield> – имя нового поля, в которое будет записано значение после операции отображения (дискретизации).

Примеры использования

Пример 1

Делит весь диапазон значений поля location_id на 10 частей. Записывает результат в поле location_id_range. Считает количество уникальных пользователей в каждом из диапазонов значений поля id.

Исходные данные:

location_id	user
5	John
18	Mary
...	...
54	Sam
...	...
99	Bob
16	Phil

Запрос:

...
| bin bins=10 location_id as location_id_range 
| stats dc(user)  by location_id_range

Результат:

location_id_range	dc(user)
0-10	6
11-20	11
...	...
...	...
90-99	3

Пример 2

Исходные данные:

Для каждого хоста возвращает значение пропускной способности (throughput), усредненное по минутным интервалам времени.

_time	host	throughput
2019-10-02 12:20:00	host1	13
2019-10-02 12:20:33	host2	14
2019-10-02 12:20:55	host2	2
2019-10-02 12:21:03	host1	25
2019-10-02 12:21:34	host2	2
2019-10-02 12:21:45	host1	23
2019-10-02 12:21:55	host2	18
2019-10-02 12:22:07	host2	9
2019-10-02 12:22:08	host1	11

Запрос:

... 
| bin _time span=1m 
| stats avg(throughput) by _time host

Результат:

_time	host	avg(throughput)
2019-10-02 12:20:00	host1	13
2019-10-02 12:20:00	host2	8
2019-10-02 12:21:00	host1	24
2019-10-02 12:21:00	host2	10
2019-10-02 12:22:00	host1	11
2019-10-02 12:22:00	host2	9

CHART

Команда chart группирует записи по указанному полю и является трансформирующей командой, которая возвращает результаты в табличном формате.

Результат, затем, может быть визуализирован в разных форматах – линейный график, столбчатая диаграмма, круговая диаграмма.

В команде chart должна быть определена статистическая функция для агрегации данных.

Синтаксис команды

chart <stats-agg-term> [OVER <row-split>] [BY <column-split>]

Обязательный параметр:

• stats-agg-term – статистические функции, применяемые к полям и eval-выражениям. Результат выполнения функции может быть помещён в отдельное поле с именем, указанным после операнда AS.

  Синтаксис: <stats-func>( <evaled-field> | <wc-field> ) [AS <new-field>].

  Перечень функций представлен в разделе ниже.

Опциональные параметры:

• OVER <row-split> – поле, определенное после OVER, появится в первой колонке результирующей таблицы. Значения полей в исходных данных станут значениями рядов в результирующей таблице. Если далее строить график по этой таблице, то эти поля будут отмечены на оси Х.

• BY <column-split> – одно или несколько полей, значения которых будут названиями столбцов в результирующей таблице.

Статистические функции

Функции позволяют получить различные статистики по полю или eval-выражению, к которому они применяются.

В таблице представлен перечень функций, сгруппированных по типам:

Имя функции	Описание функции
Агрегирующие функции:
approxdc()	Приблизительное количество уникальных значений.
avg()	Среднее арифметическое.
count()	Количество значений.
distinct_count()	Количество уникальных значений.
max()	Наибольшее значение.
min()	Наименьшее значение.
perc()	Процентиль.
percentile_approx()
stdev()	Стандартное отклонение.
sum()	Сумма значений.
var()	Дисперсия.
Порядковые функции:
first()	Первое значение в таблице.
last()	Последнее значение в таблице.
Функции для работы с multivalue-полями:
list()	Список значений.
values()
Временные функции:
earliest()	Первое значение в таблице.
latest()	Последнее значение в таблице.

Примеры использования

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Пример 1

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

Запрос:

...| chart sum(sum) as total max(sum) as max_sent by dest_country

Результат выполнения:

dest_country	tolal	max_sent
Germany	40	21
Russia	34	17
USA	3	3

Пример 2

Считает сумму переводов в разрезе по стране и в разрезе валюты перевода. Over отвечает за row-split, by отвечает за column-split.

Запрос:

... | chart sum(sum) over dest_country by currency

Результат:

dest_country	EUR	RUB	USD
Germany	21	19
Russia	17	10	7
USA	3

COLLECT

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

Синтаксис команды

collect index=<string> [host=<host> source=<source> sourcetype=<sourcetype>]

Обязательные параметры:

• index=<string> – имя индекса, в который добавляются события.

Опциональные параметры:

• host=<host> – имя хоста, указываемое для событий.

• source=<source> – имя источника, указываемое для событий.

• sourcetype=<sourcetype> – имя типа источника, указываемое для событий.

Примеры использования

Пример 1

Сохраняет отформатированные данные о транзакциях в новый индекс с указанием имени и типа источника.

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

| otstats index=transactions 
| where dest="Russia" 
| collect index=transactions_russia source=transactions sourcetype=transactions

COMMAND

Команда позволяет использовать функции Spark для обработки полей.

Синтаксис команды

command <field>=[<spark_function>(<field>, <options>)]

Обязательный параметр:

• field – имя поля, которому присваивается полученное значение.

Опциональный параметр:

• spark_function – функция Spark.

  Полный список доступных функций см. в документации на Spark.

Примеры использования

Исходные данные:

id	phrase
1	world is never be the same
2	be quick or be dad
3

Пример 1

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

Запрос:

... | command up_phrase=ucase(phrase)

Результат:

id	phrase	up_phrase
1	world is never be the same	WORLD IS NEVER BE THE SAME
2	be quick or be dad	BE QUICK OR BE DAD
3

Пример 2

Проверяем поля на пустые значения. Если поле пустое (значение = NULL), то новому полю будет присвоен 0, если поле не пустое – 1.

... | command empty_check=isnotnull(phrase)

Результат:

id	phrase	empty_check
1	world is never be the same	1
2	be quick or be dad	1
3		0

Пример 3

Присваивает полю position номер позиции слова "be" во фразе поля phrase (при этом просит начать поиск от 4-го символа).

Запрос:

... | command position=locate("be", phrase, 4)

Результат:

id	phrase	position
1	world is never be the same	16
2	be quick or be dad	13
3

CONVERT

Команда конвертирует значения поля в поисковом результате в числовые значения там, где это возможно.

Синтаксис команды

convert [timeformat=<string>] (<convert-function> [AS <field>])

Обязательный параметр:

• convert-function – функция конвертирования:

  ctime() – функция конвертирует время, представленное в Epoch-формате, в понятный для человека формат. При этом используются опции параметра timeformat, который описывает параметры конвертирования.

Опциональные параметры:

• timeformat=<string> – описывает формат конвертирования поля. Формат времени по умолчанию: %Y-%m-%d %H:%M:%S.

• AS <field> – имя нового поля, в которое будет записан результат конвертирования. Если AS не использовать, оригинальные значения полей будут заменены новыми сконвертированными.

Примеры использования

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7

Пример 1

Конвертирует время из Epoch-формата в формат %Y-%m-%d и создает поле Т, куда записывается результат.

Запрос:

...|  convert timeformat="%Y-%m-%d"  ctime(datetime) as T

Результат:

datetime	currency	dest	sum	T
1587045110	RUB	Russia	10	2019-10-02
1587045120	USD	Russia	7	2019-10-02

DEDUP

Команда удаляет события, которые содержат повторяющееся значение поля или повторяющуюся идентичную комбинацию значений полей, заданных как параметры команды. Такая процедура называется дедупликацией.

Важно!
Порядок, в котором события будут поступать на обработку в команду dedup*, определяется результатом выполнения предыдущих команд. При этом один и тот же порядок событий не может быть гарантирован для разных запусков запроса.

В случае необходимости сохранения одного и того же порядка событий для разных запусков запроса, необходимо предусмотреть сортировку событий до их поступления на вход команды dedup. Для этого, например, можно использовать команду sort.*

Синтаксис команды

dedup <field-list> [sortby <sort-by-clause>]

Обязательный параметр:

• field-list – поле или перечень полей, по которым выполняется дедупликация.

Опциональный параметр:

• sortby <sort-by-clause> – порядок сортировки результата дедупликации по заданному полю:

  • в порядке возрастания – при указании префикса '+' перед полем сортировки;

  • в порядке убывания – при указании префикса '-' перед полем сортировки.

Примеры использования

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Пример 1

Удаляет события, которые содержат идентичное значение поля dest и результат сортирует по полю sum в порядке возрастания.

Запрос:

... | dedup dest sortby +sum

Результат:

datetime	currency	dest	sum
1587045140	EUR	USA	3
1587045110	RUB	Russia	10
1587045130	EUR	Germany	21

DELTA

Вычисляет разницу между соседними результатами, используя значение определенного числового поля. Для каждого события, где поле field является числом, команда delta вычисляет разницу в порядке поиска между значением поля для текущего события и значением поля для предыдущего события. Команда delta записывает эту разницу в newfield.

Важно!
Порядок, в котором события будут поступать на обработку в команду delta, определяется результатами выполнения предыдущих команд. В случае необходимости сохранения одного и того же порядка событий, необходимо предусмотреть сортировку событий внутри запроса (использование команды sort).

Синтаксис команды

delta (<field> [AS <newfield>]) [p=<int>]

Обязательный параметр:

• field – имя поля для анализа.

Опциональные параметры:

• AS <newfield> – псевдоним для нового поля, в которое будет записана вычисляемая разница (дельта).

• p=<int> – определяет значение какого результата перед текущим использовать для сравнения:

  • p = 1 (по умолчанию), текущее значение результата сравнивается со значением в первом результате до текущего результата;

  • p = 2, текущее значение результата сравнивается со значением во втором результате до текущего результата;

    и так далее.

Примеры использования

Пример 1

Считает изменение объёма авиатрафика.

Исходные данные:

Date	Departures
21.03.2019	150
22.03.2019	160
23.03.2019	145
...	...

Запрос:

... | sort Date |delta Departures as Diff

Результат выполнения:

Date	Departures	Diff
21.03.2019	150	0
22.03.2019	160	10
23.03.2019	145	-15
...	...	...

Пример 2

Вычисляет дельту транзакций для определённой валюты.

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... 
| where currency="EUR" 
| sort _time 
| delta sum as delta_sum_eur

Результат:

datetime	currency	dest	sum	delta_sum_eur
1587045130	EUR	Germany	21	0
1587045140	EUR	USA	3	-18
1587045160	EUR	Russia	7	4

EVAL

Команда eval вычисляет выражение и помещает полученное значение в поле результатов поиска:

• По результатам работы команды eval вычисляется новое поле, которое добавляется в результаты поиска.

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

• Результатом выражения eval не может быть логическое значение.

• Если во время поиска выражение не может быть успешно вычислено для данного события, команда eval стирает результирующее поле и значением поля становится 'NULL'.

• Если выражение ссылается на поле, имя которого содержит специальные символы, за исключением символа подчеркивания (_), то имя поля должно быть заключено в одинарные кавычки. Например, имя поля server-1 в выражении указывается так – new = count + 'server-1'.

• Если имя вычисляемого поля содержит специальные символы, то могут использоваться как двойные, так и одинарные кавычки. Например, если имя поля – var-1, то обе записи – 'var-1' = m + n и "var-1" = m + n – будут обработаны корректно.

• Если выражение ссылается на строку (string), то эта строка должна быть заключена в двойные кавычки. Например, если значение строки – server, то строка указывается как new = "server".

Команда eval оценивает математические, строковые и логические выражения.

Можно объединить несколько выражений в одном запросе, используя запятую для разделения последующих выражений.

Запрос обрабатывает несколько выражений eval слева направо и позволяет ссылаться в последующих выражениях на ранее преобразованные поля.

Синтаксис команды

eval <field>=<expression>["," <field>=<expression>]

Обязательный параметр:

• <field>=<expression>:

  • field – имя поля назначения для результирующего вычисленного значения. Если имя поля уже существует в событиях, eval перезаписывает значение.

  • expression – комбинация значений, переменных, операторов и функций, которые будут выполнены, чтобы определить значение для размещения в поле назначения.

Операторы

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

Тип операции	Операторы
Арифметический	+ - * / %
Логический	AND OR NOT XOR < > <= >= != = == LIKE

Операторы операций над числами:

• Оператор плюс (+) принимает два числа для сложения или две строки для объединения.

• Операторы вычитания (-), умножения (*), деления (/) и вычисления остатка от деления (%) принимают два числа.

Операторы логических выражений:

• Операторы AND и OR принимают два логических значения.

• Операторы <, >, <=, >=,!=, =, == принимают два числа или две строки.

• В выражениях одинарный знак равенства (=) является синонимом двойного знака равенства (==).

• Оператор LIKE принимает две строки. Это сопоставление с образцом, аналогичное тому, что используется в SQL. Например, строка как шаблон. Оператор шаблона поддерживает литеральный текст, символ процента (%) для подстановочного знака и символ подчеркивания () для совпадения одного символа. Например, поле LIKE "a% b" соответствует любой строке, начинающейся с a, за которой следует что угодно, затем b, за которым следует один символ.

Имена полей

Чтобы указать имя поля из нескольких слов, можно объединить слова или использовать кавычки при указании имени. Например, чтобы указать имя поля Account ID, можно указать AccountID или "Account ID".

Чтобы указать имя поля со специальными символами, такими как точка, можно использовать кавычки. Например, чтобы указать имя поля www.domain, используйте "www.domain&quot;.

Поддерживаемые функции

Вместе с командой eval можно использовать широкий спектр функций. В таблице перечислены поддерживаемые функции, разделённые по типу:

Тип функции	Поддерживаемые функции
Сравнительные и условные функции	case(X,"Y",...), coalesce(X,...), if(X,Y,Z), like(TEXT,PATTERN), match(SUBJECT,"REGEX"), nullif(X,Y), true()
Функции конвертации	printf, tonumber(NUMSTR,BASE), tostring(X,Y)
Криптографические функции	md5(X), sha1(X)
Функции даты и времени	now(), relative_time(X,Y), strptime(X,Y)
Информационные функции	isnotnull(X), isnull(X)
Математические функции	abs(X), ceiling(X)или ceil(X), exp(X), floor(X), ln(X), log(X,Y), pi(), pow(X,Y), round(X,Y), sqrt(X)
Функции преобразования для мультизначений	mvappend(X,...), mvcount(MVFIELD), mvdedup(X), mvfind(MVFIELD,"REGEX"), mvindex(MVFIELD,STARTINDEX,ENDINDEX), mvjoin(MVFIELD,STR), mvrange(X,Y,Z), mvsort(X), mvzip(X,Y,"Z"), split(X,"Y")
Статистические функции	max(X,...), min(X,...)
Текстовые функции	len(X), lower(X), replace(X,Y,Z), substr(X,Y,Z), upper(X)
Тригонометрические и гиперболические функции	acos(X), asin(X), atan(X), atan2(Y,X), cos(X), hypot(X,Y), sin(X), tan(X)

Примеры использования

Пример 1

Создаёт новое поле transaction, объединяя значения из трёх существующих полей.

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... | eval transaction=sum+" "+currency+" "+dest

Результат:

datetime	currency	dest	sum	transaction
1587045110	RUB	Russia	10	10 RUB Russia
1587045120	USD	Russia	7	7 USD Russia
1587045130	EUR	Germany	21	21 EUR Germany
1587045140	EUR	USA	3	3 EUR USA
1587045150	RUB	Germany	19	19 RUB Germany
1587045160	EUR	Russia	7	7 EUR Russia

Пример 2

Преобразует значения поля currency в нижний регистр.

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... | eval currency_low=lower(currency)

Результат:

datetime	currency	dest	sum	currency_low
1587045110	RUB	Russia	10	rub
1587045120	USD	Russia	7	usd
1587045130	EUR	Germany	21	eur
1587045140	EUR	USA	3	eur
1587045150	RUB	Germany	19	rub
1587045160	EUR	Russia	7	eur

Пример 3

Использует функцию if для оценки размера транзакций.

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... | eval "Transaction size"=if(sum>15, "Large", "Small")

Результат:

datetime	currency	dest	sum	Transaction size
1587045110	RUB	Russia	10	Small
1587045120	USD	Russia	7	Small
1587045130	EUR	Germany	21	Large
1587045140	EUR	USA	3	Small
1587045150	RUB	Germany	19	Large
1587045160	EUR	Russia	7	Small

Пример 4

Присваивает категорию размеру авиатрафика в терминалах аэропорта в разрезе календарных суток.

Исходные данные:

Terminal	Date	Arrivals	Departures
TerminalA	27.03.2019	235	321
TerminalB	27.03.2019	178	167
TerminalC	27.03.2019	79	68
TerminalA	28.03.2019	116	178
TerminalB	28.03.2019	265	245
TerminalC	28.03.2019	64	60
TerminalA	29.03.2019	223	216
TerminalB	29.03.2019	98	101
TerminalC	29.03.2019	187	198

Запрос:

... 
| eval Air_traffic_size=case((Arrivals+Departures)<=200, "Small", (Arrivals+Departures)>100 AND (Arrivals+Departures)<=400, "Medium", (Arrivals+Departures)>400, "Large") 
| chart values(Terminal) by Air_traffic_size over Date

В этом примере используется команда chart для представления категории размера трафика в разрезе дней.

Результат:

Date	Large	Medium	Small
27.03.2019	TerminalA	TerminalB	TerminalC
28.03.2019	TerminalB	TerminalA	TerminalC
29.03.2019	TerminalA	TerminalC	TerminalB

EVENTSTATS

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

Синтаксис команды

eventstats <stats-agg-term> ... [<by-clause>]

Обязательный параметр:

• stats-agg-term – статистические функции, применяемые к полям и eval-выражениям. Результат выполнения функции может быть помещён в отдельное поле с именем, указанным после операнда AS.

  Синтаксис:

<stats-func>( <evaled-field> | <wc-field> ) [AS <new-field>]

Перечень функций представлен в разделе ниже.

Опциональный параметр:

• by-clause – поле или несколько полей, по которым надо рассчитать агрегацию (группировку).

  Синтаксис:

by <field1> <field2> ....

Статистические функции

Функции позволяют получить различные статистики по полю или eval-выражению, к которому они применяются.

В таблице представлен перечень функций, сгруппированных по типам:

Имя функции	Описание функции
Агрегирующие функции:
approxdc()	Приблизительное количество уникальных значений.
avg()	Среднее арифметическое.
count()	Количество значений.
distinct_count()	Количество уникальных значений.
max()	Наибольшее значение.
min()	Наименьшее значение.
perc()	Процентиль.
percentile_approx()
stdev()	Стандартное отклонение.
sum()	Сумма значений.
var()	Дисперсия.
Порядковые функции:
first()	Первое значение в таблице.
last()	Последнее значение в таблице.
Функции для работы с multivalue-полями:
list()	Список значений.
values()
Временные функции:
earliest()	Первое значение в таблице.
latest()	Последнее значение в таблице.

Примеры использования

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Пример 1

Вычисляется максимальное и минимальное значение поля sum. В каждом событии создается два новых поля (maxsum и minsum), в которые записываются результаты вычислений.

Запрос:

... | eventstats  max(sum) AS maxsum min(sum) AS minsum

Результат:

datetime	currency	dest	sum	maxsum	minsum
1587045110	RUB	Russia	10	21	3
1587045120	USD	Russia	7	21	3
1587045130	EUR	Germany	21	21	3
1587045140	EUR	USA	3	21	3
1587045150	RUB	Germany	19	21	3
1587045160	EUR	Russia	7	21	3

Пример 2

Вычисляется сумма поля sum в разбивке по странам. В каждое событие добавляется новое поле, содержащее сумму значений sum для каждой страны. Имя нового поля – sumTotal.

Запрос:

... | eventstats sum(sum) AS sumTotal by dest

Результат:

datetime	currency	dest	sum	sumTotal
1587045110	RUB	Russia	10	34
1587045120	USD	Russia	7	34
1587045130	EUR	Germany	21	40
1587045140	EUR	USA	3	3
1587045150	RUB	Germany	19	40
1587045160	EUR	Russia	7	34

FIELDS (TABLE)

Команда оставляет или удаляет выбранные поля из результатов запроса.

Если команда помещена в конец запроса, то на экран будут выведены указанные поля.

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

Если в запросе указаны поля, отсутствующие в наборе данных, то при использовании символа минус "-" они будут проигнорированы. А если символ минус не используется, то такие поля будут добавлены как пустые колонки.

Синоним команды – table.

Синтаксис команды

fields [-|*] <field-list> 

Обязательный параметр:

• field-list – список полей (через запятую), к которым должна быть применена команда fields. Также для указания полей с похожими именами можно использовать * (wildcard).

  Синтаксис: <field1>, <field2>, ...

Опциональный параметр:

• -|* – символ минус "-" или звездочка:

  • "-" – поля, указанные после этого символа, будут удалены из результатов запроса.

  • "*" – будут получены все поля.

Примеры использования

Исходные данные:

Name	Surname	age
John	Snow	10
Alex	Smith	7
Anna	Show	21

Пример 1

Удалить из итоговой таблицы поле age.

Запрос:

... | fields – age

Результат:

Name	Surname
John	Snow
Alex	Smith
Anna	Show

Пример 2

Вывести только поля Name и age.

... | fields Name, age

Результат:

Name	age
John	10
Alex	7
Anna	21

FIELDSUMMARY

Команда вычисляет сводную статистику для всех полей в событиях. Сводная информация отображается в виде таблицы результатов.

Синтаксис команды

fieldsummary

Использование команды

Команда fieldsummary отображает сводную информацию в таблице результатов:

Сводное имя поля	Описание поля
column	Имя поля в событии.
count	Количество событий с этим полем.
max	Максимальное значение поля.
mean	Среднее значение поля.
min	Минимальное значение поля.
stdev	Стандартное отклонение значений поля.

Примеры использования

Пример 1

Вывести суммарную информацию из транзакций по определённой валюте.

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... 
| where currency="EUR" 
| table sum 
| fieldsummary

Результат:

column	count	max	mean	min	stddev
sum	3	21	10.333333333333334	3	9.451631252505216

FILLDOWN

Если значение поля NULL, то команда filldown заполняет поле ближайшим сверху значением этого же поля, не равным NULL. Если у поля не было предыдущих не-NULL значений, то после применения filldown поле остаётся пустым (NULL).

Если список полей не объявлен, то команда filldown пытается отработать на всех полях или автоматически определить поля, содержащие значения NULL, и отработать на них.

Синтаксис команды

filldown [<wc-field-list> [defineTargetColumns=<bool>][BY <field-group>]]

Опциональные параметры:

• wc-field-list – разделённые запятой имена полей, к которым будет применена команда filldown. Синтаксис: <field1>, <field2>, ...

• defineTargetColumns – логический параметр, используемый при отсутствии параметра wc-field-list:

  • если defineTargetColumns=true, целевые поля (содержащие значения NULL) определятся во время выполнения команды;

  • если defineTargetColumns=false, команда filldown попытается отработать на всех полях.

    Значение по умолчанию: false.

    Важно!

    Если параметр wc-field-list определён, параметр defineTargetColumns игнорируется.

• BY <field-group> – поле, по которому в таблице будет выполнена группировка для дальнейшего заполнения NULL-значений полей, указанных в параметре wc-field-list, отдельно по каждой группе.

  Важно!

  При использовании параметра BY <field-group> должен быть определён параметр wc-field-list.

Примеры использования

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045111	RUB
1587045120	USD	USA	20
1587045121	USD
1587045121	EUR
1587045111	RUB	Russia
1587045121	EUR	Italy	40
1587045111	RUB	Russia	30
1587045122	RUB
1587045122	EUR

Пример 1

Если значение любого поля есть NULL, то оно заполняется ближайшим сверху не-NULL значением этого же поля.

Запрос:

... | filldown

Результат:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045111	RUB	Russia	10
1587045120	USD	USA	20
1587045121	USD	USA	20
1587045121	EUR	USA	20
1587045111	RUB	Russia	20
1587045121	EUR	Italy	40
1587045111	RUB	Russia	30
1587045122	RUB	Russia	30
1587045122	EUR	Russia	30

Пример 2

Если значение поля dest есть NULL, то оно заполняется ближайшим сверху не-NULL значением поля dest.

Запрос:

... | filldown dest

Результат:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045111	RUB	Russia
1587045120	USD	USA	20
1587045121	USD	USA
1587045121	EUR	USA
1587045111	RUB	Russia
1587045121	EUR	Italy	40
1587045111	RUB	Russia	30
1587045122	RUB	Russia
1587045122	EUR	Russia

Пример 3

Если значение определённого в параметре <wc-field-list> поля есть NULL, и в команде присутствует параметр BY <field-group>, то оно заполняется ближайшим сверху не-NULL значением этого же поля в пределах категории, определённой значением параметра BY <field-group>.

Запрос:

... | filldown dest by currency

Результат:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045111	RUB	Russia
1587045120	USD	USA	20
1587045121	USD	USA
1587045121	EUR
1587045111	RUB	Russia
1587045121	EUR	Italy	40
1587045111	RUB	Russia	30
1587045122	RUB	Russia
1587045122	EUR	Italy

Пример 4

Если требуется заменить NULL-значения в тех полях таблицы, где значения могут быть NULL, и в команде присутствует параметр BY <field-group>, то следует явно указать эти поля.

Запрос:

... | filldown datetime, dest, sum by currency

Результат:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045111	RUB	Russia	10
1587045120	USD	USA	20
1587045121	USD	USA	20
1587045121	EUR
1587045111	RUB	Russia	10
1587045121	EUR	Italy	40
1587045111	RUB	Russia	30
1587045122	RUB	Russia	30
1587045122	EUR	Italy	40

FILLNULL

Если значение поля отсутствует, то есть равно NULL, то оно заполняется заданным в качестве аргумента значением. Если не определить конкретное значение для автозаполнения NULL-поля, то оно будет заполнено нулем (0). Если не определить список имен полей, NULL-значения которых должны быть автоматически заполнены, то будут заполнены все NULL-значения всех полей.

Синтаксис команды

fillnull [value=<string>] [<field-list>]

Опциональные параметры:

• field-list – одно или несколько полей, разделенных пробелами. Если параметр не задан, то команда fillnull применяется ко всем полям. Синтаксис: <string> <string> ...

• value=<string> – определяет, чем будут заполнены NULL-значения. Значение по умолчанию – 0.

Примеры использования

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD

Пример 1

Если значение любого поля есть NULL, то оно заполняется значением "no_value".

Запрос:

...  | fillnull value="no_value"

Результат:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	no_value	no_value

Пример 2

Если значение поля sum есть NULL, то оно заполняется значением по умолчанию то есть 0. Null-значения остальных полей остаются неизменными.

... | fillnull  sum

Результат:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD		0

FOREACH

Команда запускает шаблонный поисковый запрос для каждого поля, к которому есть обращение через wildcard-конструкции в синтаксисе команды.

Синтаксис команды

foreach <wc-field>... <subsearch>

Обязательные параметры:

• wc-field – список имен полей, к которым будет применяться шаблонный поисковый запрос. Можно использовать wildcard-конструкции при задании полей. Синтаксис: <field1> <field2>...

• subsearch – поисковый запрос-шаблон, который будет применяться к полям wc-field, заменяя wildcard поля конкретными значениями. Синтаксис: [ subsearch ].

В тексте шаблонного запроса допускается использование следующих wildcard-конструкций:

• <<FIELD>> – токен <<FIELD>> будет заменен именем поля целиком.

• <<MATCHSTR>> – токен <<MATCHSTR>> будет заменен частью имени поля, которая определяется wildcard-правилами.

Примеры использования

Исходные данные:

currency	dest	sum
RUB	Russia	10
USD	USA	20

Пример 1

Создает поле newfield в каждой строке результата. В каждой строке поле newfield определяется как сумма фиксированной части newfield, равной 5, и текущего значения полей sum (сложение работает как сложение чисел) и currency (сложение работает как строковая операция).

Запрос:

...  
| eval newfield=5, sum=tonumber(sum) 
| foreach sum, currency [eval newfield = newfield+'<<FIELD>>']

Результат:

currency	dest	sum	newfield
RUB	Russia	10	15.0RUB
USD	USA	20	25.0USA

Пример 2

Создает поле newfield в каждой строке результата.

Создает поле newfield в каждой строке результата. В каждой строке поле newfield определяется как сложение следующих полей: поля, совпадающего с полем currency (подходит по wildcard = cu*cy), и фиксированной части "currency". Сложение работает как строковая операция.

Запрос:

... 
|eval newfield="" 
| foreach cu*cy [eval newfield = newfield + '<<FIELD>>' +  "_currency"]

Результат:

currency	dest	sum	newfield
RUB	Russia	10	RUS_currency
USD	USA	20	USA_currency

HEAD

Команда возвращает первые N результатов поиска. Отсчет результатов будет вестись в порядке поиска, то есть, в том порядке, в котором события поступают на вход команды head после обработки предыдущими командами.

Важно!
Порядок, в котором события будут поступать на обработку в команду head, определяется результатом выполнения предыдущих команд. Иногда один и тот же порядок событий не может быть гарантирован для разных запусков запроса. В случае необходимости сохранения одинакового порядка событий для разных запусков запроса, необходимо предусмотреть сортировку событий до их поступления на вход команды head. Для этого можно использовать команду sort.

Синтаксис команды

head [<N>] | [limit=<int>]

Опциональные параметры:

• N – целое число, определяющее количество возвращаемых результатов.

• limit=<int> – другой вариант задания количества возвращаемых результатов. Если значение возвращаемых результатов не задано, то head возвращает 10 результатов.

Примеры использования

Исходные данные:

currency	dest	sum
RUB	Russia	10
USD	USA	20

Пример 1

Возвращает первый результат из полученных до выполнения команды head.

Запрос:

...  | head 1

Результат:

datetime	currency	dest	sum
1587045110	RUB	Russia	10

INPUTLOOKUP

Команда inputlookup используется для вывода содержимого lookup-таблицы и поиска по ней. Lookup-таблица это файл в CSV-формате.

Важно!

Эту команду не рекомендуется применять при поиске по датам и времени. Для получения корректного результата поиска по датам и времени используйте команды otstats и search.

Синтаксис команды

inputlookup [append=<bool>] <filename> [WHERE <search-query>]

Обязательный параметр:

• filename – имя lookup-файла. Lookup-файл может не иметь расширения .csv, но должен быть в формате CSV.

Опциональные параметры:

• append=<bool>:

  • если append=true, то данные lookup-файла будут присоединены к результатам, полученным до вызова команды inputlookup.

  • если append=false (значение по умолчанию), то содержимое lookup-файла заменит результаты, полученные до вызова команды inputlookup.

• WHERE <search-query> – опция для предварительной фильтрации данных lookup-файла. Результатом поискового запроса будут только те строки lookup-файла, которые попадут под условия фильтрации.
  Поддерживается следующий набор операторов: =, !=, <, >, <=, >=, AND, OR, NOT.

Примеры использования

Исходные данные:

lookup-файл money_senders.csv со следующим содержимым:

dest_country	sender	sum
RUS	John	20
USA	Mary	10

Пример 1

Выводит содержимое lookup-файла money_senders.csv.

Запрос:

...| inputlookup  money_senders.csv

Результат выполнения:

dest_country	sender	sum
RUS	John	20
USA	Mary	10

Пример 2

Присоединяет содержимое lookup-файла money_senders.csv к результатам поискового запроса до вызова команды inputlookup.

Запрос:

| makeresults 
| eval dest_country="France", sender="Tom",sum=99 
| inputlookup append=t  money_senders.csv

Результат:

dest_country	sender	sum
France	Tom	99
RUS	John	20
USA	Mary	10

Пример 3

Выводит только те строки lookup-файла, в которых поле sum строго больше 10.

Запрос:

... | inputlookup append=t  money_senders.csv where sum>10

Результат:

dest_country	sender	sum
RUS	John	20

JOIN

Команда join комбинирует результаты поискового подзапроса с результатами основного запроса. Основной запрос и подзапрос должны содержать в себе одно или несколько идентичных полей.

Альтернативные команды. Если для решения задачи не требуется в точности семантика join, то использование схожих по функционалу команд может быть более целесообразно: append, appendcols, lookup, search, stats.

Синтаксис команды

join [join-options...] [<field-list>] <subsearch>

Обязательный параметр:

• subsearch – возвращающий результаты поисковый подзапрос, к которому будут присоединены результаты основного запроса.

Опциональные параметры:

• join-options – опции команды join.

  Синтаксис: type=(inner | outer | left | right) | max=<int>.

  Описание:

  • type – тип команды join.

    Синтаксис: type=inner | outer | left | right.

    Значение по умолчанию: left.

    Разница между типами заключается в том, каким образом обрабатываются события основного запроса, которые не могут быть поставлены в соответствие событиям поискового подзапроса. Как в inner так и в left возвращаются только те события, которые могут быть поставлены в соответствие друг другу по заданному полю. Однако результаты inner join не включают события основного запроса, которые не имеют совпадений в подзапросе. Результат же left join (или outer join) включает все события основного запроса и те события из подзапроса, которые могут быть поставлены в соответствие событиям основного запроса по заданному полю.

    См. примеры 3, 4, 5.

  • max – максимальное возвращаемое количество результатов поискового подзапроса, с которым будет объединён каждый результат основного запроса. Параметр, равный нулю (0), означает, что ограничений на количество результатов нет.

    Значение по умолчанию: 0.

    Синтаксис: max=<int>.

• field-list – поля, по которым будет выполняться команда join. Совпадение значений полей основного запроса и подзапроса должно быть с точностью до регистра отдельных символов.

  Синтаксис: <field1>, <field2>, ...

Примеры использования

Исходные данные:

Результат Запроса_1. Для удобства результат представлен в виде таблицы (search1.csv):

currency	dest_country	sum
EUR	Italy	10
USD	Russia	13
RUB	Canada	14
EUR	Canada	1
USD	Russia	3
MXN	Mexico	7

Результат Запроса_2. Для удобства результат представлен в виде таблицы (search2.csv):

commission	dest_country
1,7%	Canada
3.3%	Italy
2%	Russia
2.1%	Georgia

Пример 1

Соединяет результаты Запроса_1 с результатами Запроса_2 по полю dest_country.

Запрос:

...
| inputlookup  search1.csv 
| join dest_country  [| inputlookup  search2.csv]

Результат:

commission	currency	dest_country	sum
3.3%	EUR	Italy	10
2%	USD	Russia	13
7%	RUB	Canada	14
7%	EUR	Canada	1
2%	USD	Russia	3

Пример 2

Соединяет результаты Запроса_2 с результатами Запроса_1 по полю dest_country. Видно, что каждому результату Запроса_2, который в примере является основным запросом, ставится в соответствие один результат Запроса_1 (используется опция max=1), который в примере является подзапросом. Если max=1 задан не будет, то ограничений по числу "соединений" полей не будет.

...
| inputlookup  search2.csv 
| join dest_country max=1 [| inputlookup search1.csv]

Результат:

commission	currency	dest_country	sum
2%	USD	Russia	3
3.3%	EUR	Italy	10
7%	EUR	Canada	1

Пример 3

Пример операции join type=outer.

Результат:

commission	currency	dest_country	sum
3.3%	EUR	Italy	10
3.4%	MXN	Mexico	7
1.7%	RUB	Canada	14
1.7%	EUR	Canada	1
2%	USD	Russia	13
2%	USD	Russia	3

Пример 4

Пример операции join type=left.

Результат:

commission	currency	dest_country	sum
3.3%	EUR	Italy	10
2%	USD	Russia	13
1.7%	RUB	Canada	14
1.7%	EUR	Canada	1
2%	USD	Russia	3
3.4%	MXN	Mexico	7

Пример 5

Пример операции join type=inner.

Результат:

commission	currency	dest_country	sum
1.7%	EUR	Canada	1
1.7%	RUB	Canada	14
3.3%	EUR	Italy	10
2%	USD	Russia	3
2%	USD	Russia	13

LOOKUP

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

Синтаксис команды

lookup <lookup-file> <field-list> [AS <new_field_name>] 

Команда позволяет присоединять релевантные поля из существующей таблицы в результаты запроса при совпадении значений целевого поля или полей field-list со значением в результатах запроса.

Обязательные параметры:

• lookup-file – имя файла таблицы, сохраненное в файловой системе, в директории ../lookups.

• field-list – поле или список полей (через запятую), по которым осуществляется связка таблицы с результатами запроса.

Опциональный параметр:

• AS <new_field_name> – имя, используемое для переименования поля в существующей таблице, если целевое поле с ним не совпадает.

Примеры использования

Исходные данные:

Имеем существующую таблицу students.csv:

Name	Familyname	age
John	Snow	10
John	Smith	7
Anna	Show	21

И результаты запроса, в которых поле с фамилиями указано как Surname:

Name	Surname	Town
John	Snow	Moscow
John	Smith	Volgograd
John	Bond	Perm

Пример 1

Результаты запроса нам выдают имя и фамилию без возраста. Требуется добавить в результаты запроса возраст из сохраненной таблицы. Для этого обязательно указываем связующие столбцы таблицы Name и Familyname, причем Familyname нужно переименовать в Surname.

Запрос:

| lookup students.csv Name, Familyname as Surname

Результат:

Name	Familyname	Town	age
John	Snow	Moscow	10
John	Smith	Volgograd	7
John	Bond	Perm

MAKEMV

Команда конвертирует поле, состоящее из одного значения (singlevalue-поле), в поле, состоящее из нескольких значений (multivalue-поле), разделяя singlevalue-поле на отдельные части указанным строковым разделителем.

Синтаксис команды

makemv [delim=<string>] <field>

Обязательный параметр:

• field – имя singlevalue-поля, которое будет преобразовано в multivalue-поле.

Опциональный параметр:

• delim=<string> – строка, которая будет использована в качестве разделителя при преобразовании в multivalue-поле.

  Значение по умолчанию: пробел (" ").

Примеры использования

Исходные данные:

dest_country	sender	sum
RUS	John OR Mary	20
USA	John OR Mary	10

Пример 1

Преобразует singlevalue-поле sender, в multivalue-поле c таким же именем. В качестве строки-разделителя используется "OR".

Запрос:

...| makemv  sender delim="OR"

Результат выполнения:

dest_country	sender	sum
RUS	John Mary	20
USA	John Mary	10

MAKERESULTS

Команда создает (генерирует) требуемое количество результатов поиска. Если не указывать опциональные параметры, то команда генерирует только один результат с единственным полем _time.

Важно!

Эту команду не рекомендуется применять при поиске по датам и времени. Для получения корректного результата поиска по датам и времени пользуйтесь командами otstats и search.

Синтаксис команды

makeresults [count=<num>] [annotate=<bool>]

Обязательные параметры: отсутствуют.

Опциональные параметры:

• count=<num> – количество результатов, которые должны быть сгенерированы. Значение по умолчанию: 1.

  Если count не указан, то команда генерирует только один результат с единственным полем _time.

• annotate=<bool>:

  • если annotate=true, то дополнительно будут сгенерированы результаты с полями, указанными в таблице ниже;

  • если annotate=false, то сгенерированные результаты будут содержать только поле _time. Значение по умолчанию: false.

Поля, генерируемые при указании annotate=true:

Поле	Значение
_raw	Нет значения (NULL)
_time	Дата и время выполнения команды makeresults
host	Нет значения (NULL)
source	Нет значения (NULL)
sourcetype	Нет значения (NULL)

Примеры использования

Пример 1

Генерирует 3 результата. Дополняет результат полем dest_country со значением "Russia".

Запрос:

| makeresults count=3 
| eval dest_country="Russia"

Результат:

_time	dest_country
1588755573	Russia
1588755573	Russia
1588755573	Russia

MVCOMBINE

Команда берет группу событий, которые отличаются только одним полем, содержащим определенное значение, и комбинирует их в одно событие. Значение в этом поле становится массивом значений из скомбинированных по этому полю значений.

Синтаксис команды

mvcombine <field>

Команда mvcombine принимает на вход события и находит группы событий, где все поля одинаковы в отличие от указанного после команды поля. Полученные значения этого поля объединяются в массив и становятся новым значением этого поля. Так как события могут содержать много разных полей (особенно часто различающиеся поля _time и _raw), то имеет смысл предварительно отобрать нужные поля с помощью команды fields.

Обязательный параметр:

• field – имя поля, значения которого будут комбинироваться.

Примеры использования

Исходные данные:

host	ping	latency
www1	10	1
www2	10	1
finance_dep	11	1
it_dep	11	2
www3	10	1

Пример 1

Комбинирует значения поля host там, где поля latency и ping содержат одинаковые значения (то есть 1 и 10).

Запрос:

... | mvcombine host

Результат:

host	ping	latency
www1 www2 www3	10	1
finance_dep	11	1
it_dep	11	2

MVEXPAND

Команда разворачивает значения многозначного поля в отдельные события. Для каждого результата команда создаёт новое событие.

Синтаксис команды

mvexpand <field> [limit=<int>]

Обязательный параметр:

• field – имя многозначного поля.

Опциональный параметр:

• limit=<int> – количество значений в многозначном поле field, которое будет использоваться для каждого входного события.

Примеры использования

Пример 1

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

Исходные данные:

Date	fields
27.04.2020	33,55 17,18 34,54
28.04.2020	3,5 34,34 67,9

Запрос:

... 
| mvexpand fields 
| rex field=fields "(?<alpha>\d+),(?<beta>\d+)" 
| table _time alpha beta 

Результат:

Date	alpha	beta
27.04.2020	33	55
27.04.2020	17	18
27.04.2020	34	54
28.04.2020	3	5
28.04.2020	34	34
28.04.2020	67	9

NOMV

Команда конвертирует значения multivalue-поля в singlevalue-поле.

Синтаксис команды

nomv <field>

Обязательный параметр:

• field – имя multivalue-поля, которое необходимо конвертировать в singlevalue-поле

Примеры использования

Исходные данные:

Поле dest является multivalue-полем.

datetime	currency	dest	sum
1587045110	RUB	Russia France	10
1587045120	USD	Italy USA	7

Пример 1

Создает singlevalue-поле dest из multivalue-поля dest. Поле dest становится обычной строкой.

Запрос:

... | nomv dest

Результат:

datetime	currency	dest	sum
1587045110	RUB	Russia France	10
1587045120	USD	Italy USA	7

Теперь с полем dest можно проводить строковые операции, как с обычной строкой:

... | nomv dest | eval dest=dest+"Spain"

Результат:

datetime	currency	dest	sum
1587045110	RUB	Russia France Spain	10
1587045120	USD	Italy USA Spain	7

OTLOADJOB

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

Синтаксис команды

otloadjob <spl-query>

Обязательный параметр:

• spl-query – поисковый запрос, результаты которого требуется извлечь из кэша. Успешное выполнение команды otloadjob возможно только при наличии двух условий:

  • Запрос, результат которого требуется получить, должен быть выполнен.

  • Время хранения результата выполненного запроса не истекло.

    Если хотя бы одно из условий отсутствует, запрос, указанный в параметре spl-query, будет выполнен повторно.

    Spl-запрос задается как строка. При этом, если внутри запроса встречаются кавычки, то они должны быть заэкранированы символом обратный слеш ("\").

    Синтаксис: spl="spl-запрос".

Примеры использования

Исходные данные:

Выполнен запрос:

index="apache" 
| stats count as num

Получен результат:

num
46

Пример 1

После выполнения запроса, указанного в исходных данных, выполнен следующий запрос:

| otloadjob spl="index=\"apache\" 
| stats count as num"

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

Следовательно, в качестве результата будет возвращён результат запроса, указанного в исходных данных:

num
46

OTSTATS

Команда используется для получения из индекса данных с извлеченными во время индексации полями. Вы можете получить события из индексов, указывая необходимые поля и используя логические выражения. Также для получения более широкого поля результатов можно использовать wildcard (*).

Команда otstats также может быть использована в подзапросе. После того как данные получены из индекса, к ним можно применять различные команды трансформации, фильтрации и т.д. Отличие от команды search (которая читает и выводит только поля _time и _raw) заключается в том, что otstats читает из файловой системы уже проиндексированные поля, что ускоряет работу поиска, так как нет необходимости проводить дополнительный парсинг во время поискового запроса.

Синтаксис команды

otstats index=<index-name> [<logical-expression>] [<time>] 

Для поиска по нескольким индексам и значениям полей можно использовать логические выражения (OR, AND). При чередовании через пробел нескольких индексов или полей к ним применяется логический оператор OR. Стоит отметить, что необходимо учитывать тип данных того поля, по которому производится поиск, так как к строковым значениям нельзя применить операции сравнения (<, >, >=, <=, !=). Знак вертикальной черты "|" перед командой не обязателен, так как она идет первой в запросе или подзапросе.

Обязательный параметр:

• index=<index-name> – имя индекса, из которого будут читаться данные. Имя индекса необходимо заключать в двойные кавычки.

Опциональные параметры:

• logical-expression – логическое выражение. Выражение может содержать два и более вариантов поиска, соединенных логическими операторами, такими как OR или AND. Поиск по определенным значениям осуществляется с помощью знака равно "=" или "!=". Может быть использован также оператор регулярных выражений wildcard (в конце строки) и знаки сравнения (<, >, >=, <=, !=) для числовых значений.

• time – в подзапросах (или основном запросе) могут использоваться дополнительные опции времени (latest= и earliest=) для поиска по другому временному интервалу. Временные рамки указываются в формате Epoch time (Linux time).

Примеры использования

Исходные данные:

Имеются два индекса с логами данных linux-log и nginx-log с полями _time, _raw, severity, message.

Пример 1

Выводим данные из индекса linux-log, где поле severity указывает на возникновение ошибки:

| otstats index="linux-log" severity="ERR*"

Пример 2

Выводим данные из индекса linux-log и nginx-log, где поле severity указывает на возникновение ошибки и на критическое событие:

| otstats index="linux-log" index="nginx-log" severity="ERR*" OR severity="CRITICAL"

Пример 3

Выводим данные из индекса linux-log и прибавляем к ним данные из подзапроса, указывая другой временной интервал:

| otstats index="linux-log" severity="ERR*" 
| append [otstats index="nginx-log" earliest=1577836799 latest=1577858400]

OUTPUTLOOKUP

Команда сохраняет результаты запроса в статическую таблицу (lookup).

Синтаксис команды

outputlookup <filename> [append=<bool>]

Обязательный параметр:

• filename – имя lookup-файла.

Опциональный параметр:

• append=<bool>:

  • если append=false (по умолчанию), то команда outputlookup перезаписывает данные в существующем lookup-файле;

  • если append=true, то outputlookup пытается добавить результаты запроса в существующий файл.

Примеры использования

Пример 1

Фильтрует список транзакций и сохраняет результаты запроса в lookup-файл.

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... 
| where currency="EUR" 
| outputlookup transactions_eur.csv

Результат, записанный в lookup-файл:

datetime	currency	dest	sum
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045160	EUR	Russia	7

RANGEMAP

Команда разбивает значения числового поля на категории. Команда добавляет новое поле с именем range к каждому событию и отображает категорию в этом поле.

Значения в поле range основаны на указанных числовых диапазонах. Если значение в числовом поле не соответствует какому-либо из указанных диапазонов, поле range устанавливается в значение по умолчанию.

Синтаксис команды

rangemap field=<string> (<attribute_name>=<numeric_range>)... [default=<string>]

Обязательные параметры:

• field=<string> – имя категоризируемого поля, содержащего числовые значения.

• <attribute_name>=<numeric_range>:

  • attribute_name – строка, выводимая в поле range, когда значение в field попадает в диапазон значений из numeric_range.

  • numeric_range – начальное и конечное значения диапазона, заданные через слеш (-).

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

Опциональный параметр:

• default=<string> – значение по умолчанию, которое выводится в случае, если категоризируемое поле не соответствует какому-либо из указанных диапазонов. По умолчанию значение – "None".

Примеры использования

Пример 1

Разбивает на категории события на основании значения поля суммы транзакции (sum).

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... | rangemap field=sum min=1-5 med=6-15 max=16-30

Результат:

datetime	currency	dest	sum	range
1587045110	RUB	Russia	10	med
1587045120	USD	Russia	7	med
1587045130	EUR	Germany	21	max
1587045140	EUR	USA	3	min
1587045150	RUB	Germany	19	max
1587045160	EUR	Russia	7	med

Пример 2

Установите значение поля range в "зеленый", если date_second находится между 1-30, "жёлтый", если между 31-39, "красный", если между 40-59 и "серый", если диапазон не совпадает (например, если date_second = 0).

Запрос:

... | rangemap field=date_second green=1-30 yellow=31-39 red=40-59 default=gray

RARE

Команда находит наименее распространённые значения в выбранных полях.

Синтаксис команды

| rare [<limit>] <field-list> [<by-clause>]

Команда вычисляет количество и процентное соотношение того, насколько редко выбранные значения встречаются в событиях. Если добавлена опция by-clause, то результат будет сгруппирован по полю, указанному после by.

Обязательный параметр:

• field-list – поле или список полей (через запятую или пробел), по которым проводится подсчёт.

Опциональный параметр:

• limit – количество нижних строк, которые должны быть выведены в результате. По умолчанию: 10.

• by-clause – одно или несколько полей, значения которых будут названиями столбцов в результирующей таблице.

Пример использования

Выводит 3 наименее часто встречающихся имени.

Исходные данные:

Name	Surname	age
John	Snow	10
Alex	Smith	7
Anna	Show	21
John	Bond	3
John	Smith	19
Tony	Stark	5
John	Dow	19
Tony	Pitt	5

Запрос:

... | rare 2 Name

Результат:

Name	count	percent
Anna	1	12,5
Tony	2	25

RENAME

Команда переименовывает одно или несколько полей. Для переименования полей с похожими именами можно использовать подстановочный знак (*).

Синтаксис команды

rename <wc-field> AS <wc-field>...

Обязательный параметр:

• <wc-field> AS <wc-field> – название поля и через оператор AS имя для его замены. В именах полей можно использовать подстановочные знаки. Имена с пробелами должны быть заключены в кавычки.

Примеры использования

Пример 1

Переименовывает поле dest в поле destination country.

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... | rename dest as "destination country"

Результат:

datetime	currency	destination country	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Пример 2

Переименовывает несколько полей с похожими именами, используя подстановочный знак (*).

Исходные данные:

Date	TerminalA	TerminalB	TerminalC
27.03.2019	235	178	79
28.03.2019	116	265	64
29.03.2019	223	98	187

Запрос:

... | rename Terminal* as "Terminal *"

Результат:

Date	Terminal A	Terminal B	Terminal C
27.03.2019	235	178	79
28.03.2019	116	265	64
29.03.2019	223	98	187

REPLACE

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

Синтаксис команды

replace (<wc-string> WITH <wc-string>)[IN <field>]

Обязательные параметры:

• <wc-string> WITH <wc-string> – значение поля и значение для его замены, разделённые оператором WITH. Можно использовать символы подстановки для соответствия одному или нескольким значениям.

• IN <field> – имя поля, в котором происходит замена значения. Чтобы заменить значения в поле field, необходимо указать имя поля с оператором IN.

Примеры использования

Пример 1

Заменяет сокращённое название валют на полное.

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... 
| replace EUR with Euro in currency 
| replace RUB with Ruble in currency 
| replace USD with Dollar in currency 

Результат:

datetime	currency	dest	sum
1587045110	Ruble	Russia	10
1587045120	Dollar	Russia	7
1587045130	Euro	Germany	21
1587045140	Euro	USA	3
1587045150	Ruble	Germany	19
1587045160	Euro	Russia	7

RETURN

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

Команда возвращает значение из подзапроса в виде строки (не датафрейма). Это позволяет использовать команду в подзапросах для генерации сложных выражений, которые далее в основном запросе могут быть вычислены командой eval (команда eval принимает строковое выражение для вычисления поля).

Синтаксис команды

return $<column_name>

Обязательный параметр:

• $<column_name> – колонка, значения которой вернутся из подзапроса.

Опциональные параметры отсутствуют.

Пример использования

Исходные данные:

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

_time	deposit	well	metric_name	value
16744164	deposit_1	well_1	temperature	27
16744164	deposit_1	well_2	temperature	24
16744164	deposit_2	well_1	temperature	27
16744164	deposit_2	well_2	temperature	25
16744164	deposit_3	well_1	temperature	27
16744164	deposit_3	well_1	temperature	26
16744364	deposit_1	well_1	temperature	26
16744364	deposit_2	well_2	temperature	25
16744364	deposit_3	well_2	temperature	27
16744364	deposit_3	well_2	temperature	22

Используем команду для возврата значения из подзапроса. Добавим к исходному набору данных новое поле логического типа, которое будет принимать значение true, если температура отклонилась от средней величины (по всем скважинам всех месторождений) более чем на 5%. При этом для вычисления средней температуры воспользуемся подзапросом.

В подзапросе для перечитывания исходного набора используется команда inputlookup (исходный набор представлен в виде csv-файла).

... | eval alarm=abs(value / [| inputlookup test.csv | eventstats avg(value) as avgTemp | return avgTemp] - 1) > 0.05

Результат:

_time	deposit	well	metric_name	value	alarm
1641744164	deposit_1	well_1	temperature	27	true
1641744164	deposit_1	well_2	temperature	24	true
1641744164	deposit_2	well_1	temperature	27	true
1641744164	deposit_2	well_2	temperature	25	false
1641744164	deposit_3	well_1	temperature	27	true
1641744164	deposit_3	well_1	temperature	26	false
1641744364	deposit_1	well_1	temperature	26	false
1641744364	deposit_2	well_2	temperature	25	false
1641744364	deposit_3	well_2	temperature	27	true
1641744364	deposit_3	well_2	temperature	22	true

REVERSE

Команда инвертирует порядок результатов.

Важно!
Порядок, в котором события будут поступать на обработку в команду reverse, определяется результатом выполнения предыдущих команд. В случае необходимости сохранения одинакового порядка событий для разных запусков запроса, необходимо предусмотреть сортировку событий до их передачи на вход команды reverse. Для этого можно использовать, например, команду sort.

Синтаксис команды

reverse

Примеры использования

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	USA	20

Пример 1

Инвертирует порядок строк в таблице.

Запрос:

... | reverse

Результат:

datetime	currency	dest	sum
1587045120	USD	USA	20
1587045110	RUB	Russia	10

REX

Команда позволяет находить совпадения в значениях полей согласно регулярным выражениям.

Синтаксис команды

rex (field=<field> <regex-expression> [max_match=<int>])

Команда позволяет выделять поля, используя именованные группы регулярных выражений.

Команда rex находит совпадения в строках указанного поля, согласно регулярному выражению, и выделяет его в отдельное поле с соответствующим именем (указанным в качестве группы именования регулярного выражения – ?<groupname>).

Запуск команды rex по отношению к полю _raw может сильно влиять на производительность.

Обязательные параметры:

• field=<field> – поле, по которому осуществляется поиск.

• regex-expression -– регулярное выражение, согласно которому производится поиск совпадений.

Опциональный параметр:

• max_match=<int> – определяет максимальное количество совпадений, которые должны быть найдены в поле. По умолчанию: 1 (первое совпадение).

  Если поле содержит multivalue-список, то совпадения будут определяться по каждому элементу списка в отдельности.

Примеры использования

Исходные данные:

time	phrase	mvword
2020	world is never be the same	step stone moon
2021	be quick or be dad	rapid quick fast

Пример 1

Создает новое multivalue поле first_word, которое содержит первое слово в фразе.

Запрос:

... | rex field=phrase "(?<first_word>^\w+)."

Результат:

time	phrase	mvword	first_word
2020	world is never be the same	step stone moon	world
2021	be quick or be dad	rapid quick fast	be

Пример 2

Создает новое поле, которое содержит последнюю букву каждого слова из multivalue-значений поля mvword.

Запрос:

... | rex field=mvword "(^\w+)(?<last_letter>\w$)"

Результат:

time	phrase	mvword	last_letter
2020	world is never be the same	step stone moon	p e n
2021	be quick or be dad	rapid quick fast	d k t

Пример 3

Создает новое поле, которое объединяет до трех совпадений буквы "e" в поле phrase.

Запрос:

... | rex field=phrase max_match=3 "(?<e_letter>e)"

Результат:

time	phrase	mvword	e_letter
2020	world is never be the same	step stone moon	e e e
2021	be quick or be dad	rapid quick fast	e e

SEARCH (FILTER)

Команда используется для получения из индекса необработанных данных.

Также команду можно применить для осуществления поиска по результатам запроса. В этом случае можно фильтровать события, указывая необходимые поля и используя ключевые слова или логические выражения. В том числе допустимо использование wildcard (*) для получения более широкого поля результатов.

Команда search также может быть использована в подзапросе. После получения данных из индекса, к ним можно применять различные команды трансформации, фильтрации и т.д. Отличие от команды otstats (которая читает проиндексированные данные) заключается в том, что search читает из файловой системы только поля _time и _raw, что может привести к необходимости проводить дополнительный парсинг во время поискового запроса.

Синтаксис команды

search <logical-expression> [<time>]

Для поиска по нескольким индексам и значениям полей можно использовать логические выражения (OR, AND). При чередовании через пробел нескольких индексов или полей, к ним применяется логический оператор OR. Стоит отметить, что необходимо учитывать тип данных поля, по которому производится поиск, так как к строковым значениям нельзя применить операции сравнения (<, >, >=, <=).

Обязательный параметр:

• logical-expression – логическое выражение.

  Выражение может содержать два и более варианта поиска, соединяемых логическими операторами, такими как OR или AND. Поиск по определенным значениям осуществляется с помощью знака равно "=" или не равно "!=". Может быть использован также оператор регулярных выражений wildcard (в конце строки) и знаки сравнения (<, >, >=, <=, !=) для числовых значений.

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

Опциональный параметр:

• time – в подзапросах (или основном запросе) могут использоваться дополнительные опции времени (latest= и earliest=) для поиска по другому временному интервалу. Временные рамки указываются в формате Epoch time (Linux time).

Примеры использования

Исходные данные:

Имеются два индекса с логами данных linux-log и nginx-log с полями _time, _raw.

Пример 1

Выводим данные из индекса linux-log:

... | search index="linux-log" | ...

Пример 2

Выводим данные из индекса linux-log и nginx-log:

... | search index="linux-log" index="nginx-log" | ...

Пример 3

Фильтруем данные, полученные в результате запроса. Ищем значение поля ID, равное 298, и значение результата, равное "DONE":

... | search ID=298 AND RESULT="DONE"

SORT

Команда sort сортирует результаты по указанному полю. События, в которых поле сортировки отсутствует, рассматриваются как имеющие наибольшее значение (в случае сортировки по возрастанию) и как имеющие наименьшее значение (в случае сортировки по убыванию).

Синтаксис команды

sort [count=<int>] [- | +]<sort-by-clause>...

Обязательный параметр:

• [-|+]<sort-by-clause> – список полей, по которым будет выполнена сортировка:

  • При указании опционального знака минус (-) используется убывающий порядок сортировки.

  • При указании опционального знака плюс (+) используется возрастающий порядок сортировки.

    По умолчанию используется возрастающий порядок сортировки.

    При указании нескольких полей для сортировки, поля должны быть разделены запятыми или пробелами.

    Синтаксис : [ - | + ] <sort-field1>, [ - | + ] <sort-field2> …

Опциональный параметр:

• count=<int> – если первым аргументом команды sort является count=<целое число>, то результатом сортировки будет только заданное число событий, а не отсортированные исходные данные в полном объеме.

Примеры использования

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Пример 1

Сортирует по убыванию по полю sum и выводит три первых результата.

... | sort count=3 -sum

Результат:

datetime	currency	dest	sum
1587045130	EUR	Germany	21
1587045150	RUB	Germany	19
1587045110	RUB	Russia	10

Пример 2

Сортирует сначала по полю dest_country, а затем, в пределах набора событий с одинаковым значением поля dest_country, выполняет сортировку по полю sum.

... | sort dest_country sum

Результат:

datetime	currency	dest	sum
1587045150	RUB	Germany	19
1587045130	EUR	Germany	21
1587045120	USD	Russia	7
1587045110	RUB	Russia	10
1587045160	EUR	Russia	7
1587045140	EUR	USA	3

SPATH

Команда spath позволяет извлекать информацию из структурированных данных в формате JSON. Команда сохраняет эту информацию в одном или нескольких полях.

Синтаксис команды

spath [input=<field>] [output=<field>] path=<datapath>

Обязательный параметр:

• path=<datapath> – путь к значению, которое необходимо извлечь. Путь состоит из одного или нескольких шагов местоположения, разделенных точками. Шаг местоположения состоит из имени поля и необязательного индекса, заключенного в фигурные скобки. Индекс должен быть целым числом, чтобы ссылаться на положение данных в массиве (индексация начинается с нуля). Например, 'foo.bar.baz' или 'foo.bar.baz{2}'.

Опциональные параметры:

• input=<field> – поле для чтения и извлечения значений.

  Значение по умолчанию: _raw.

• output=<field> – поле, в которое будет записано извлечённое значение. Если параметр не определён, именем поля для извлечённого значения становится значение параметра path.

Примеры использования

Пример 1

Извлекает из поля в JSON-формате сумму необходимой нам транзакции.

Исходные данные:

{
  "transaction" : {
    "1587045110" : {
      "Russia": {
        "RUB": 10
      }
    },
    "1587045120" : {
      "Russia" : {
        "USD": 7
      }
    },
    "1587045130" : {
      "Germany": {
        "EUR": 21
      }
    },
    "1587045140" : {
      "USA": {
        "EUR": 3
      }
    } 
  }
}

Запрос:

... | spath input=_raw output=result path=transaction.1587045130.Germany.EUR

Результат:

result
21

Пример 2

Извлекает из поля в JSON-формате размер необходимой нам транзакции, ссылаясь на её положение в массиве (индекс).

Исходные данные:

{
  "transaction" : {
    "1587045110" : {
      "Russia" : {
        "RUB" : [144332, 345446, 2342456, 242456, 78856],
        "EUR" : [353, 6556, 7676],
        "USD" : [3535, 7676, 7668]
      },
      "Germany" : {
        "RUB" : [13455],
        "EUR" : [1445, 45656, 1000, 2543, 345336]
      },
      "USA" : {
        "EUR" : [324343, 54664, 66565],
        "USD" : [1000, 4545, 333, 500]
      }
    }
  }
}

Запрос:

... | spath input=_raw output=result path=transaction.1587045110.Russia.RUB{2}

Результат:

result
2342456

STATS

Команда считает агрегирующую статистику, такую как среднее, количество, сумма и т.п., по имеющемуся набору данных. Процесс аналогичен SQL-агрегации. Если команда stats используется без BY группировки, то возвращается только один ряд, как совокупность всех данных входящего набора. Если применяется группировка BY, то возвращается один ряд для каждого уникального значения, входящего в набор, указанный после BY.

Синтаксис команды

stats <stats-функция>(field) [AS <field>] ... [BY <field-list>]

Синтаксис команды stats зависит от используемой функции (см. таблицу поддерживаемых функций). При выполнении команды можно использовать одну или более функций, но может быть использована только одна группировка BY.

Обязательные параметры:

• stats-функция – статистическая функция, которая будет применена к полю. Перечень функций представлен в разделе ниже.

• field – имя поля, к которому будет применена статистическая функция.

Опциональные параметры:

• AS <field> – имя поля, в которое будет записан результат статистической функции. По умолчанию, если не указывается AS <field>, то именем поля будет сама применяемая функция.

• BY <field-list> – группировка по определенному полю или списку полей.

Статистические функции

Функции позволяют получить различные статистики по полю или eval-выражению, к которому они применяются.

В таблице представлен перечень функций, сгруппированных по типам:

Имя функции	Описание функции
Агрегирующие функции:
approxdc()	Приблизительное количество уникальных значений.
avg()	Среднее арифметическое.
count()	Количество значений.
distinct_count()	Количество уникальных значений.
max()	Наибольшее значение.
min()	Наименьшее значение.
perc()	Процентиль.
percentile_approx()
stdev()	Стандартное отклонение.
sum()	Сумма значений.
var()	Дисперсия.
Порядковые функции:
first()	Первое значение в таблице.
last()	Последнее значение в таблице.
Функции для работы с multivalue-полями:
list()	Список значений.
values()
Временные функции:
earliest()	Первое значение в таблице.
latest()	Последнее значение в таблице.

Примеры использования

Исходные данные:

Имеются таблица студентов разных возрастов.

Name	Surname	age
John	Snow	10
Alex	Smith	7
Anna	Show	21
James	Bond	3
John	Dow	14

Пример 1

Считаем средний возраст студента.

Запрос:

... | stats avg(age) as AvgAge

Результат:

AvgAge
11

Пример 2

Выводим количество с группировкой по имени.

Запрос:

... | stats count(Surname) by Name

Результат:

Name	count
John	2
James	1
Alex	1
Anna	1

Пример 3

Выводим и средний возраст и количество с агрегацией по имени.

Запрос:

... | stats avg(age) as AvgAge, count(Surname) by Name

Результат:

Name	AvgAge	count
Anna	21	1
Alex	7	1
John	12	2
James	3	1

STREAMSTATS

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

Команда streamstats считает статистику от события к событию, формируя каждый раз новый результат в момент поступления очередного события на обработку. Такая обработка событий для подсчета статистики называется потоковой или стриминговой. Другими словами, команда streamstats рассчитывает статистику "по мере просмотра" событий, обновляя результат статистики для каждого просматриваемого события в момент его поступления на обработку.

Важно!
Порядок, в котором события будут поступать на обработку в команду streamstats, определяется результатом выполнения предыдущих команд. Иногда, при этом, одинаковый порядок событий не может быть гарантирован для разных запусков запроса. В случае необходимости сохранения одного и того же порядка событий для разных запусков запроса, необходимо предусмотреть сортировку событий до их поступления на вход команды streamstats. Для этого можно использовать команду sort.

Синтаксис команды

streamstats [window=<int>] [time_window=<span-length>] <stats-agg-term>... [BY <field-list>]

Обязательный параметр:

• stats-agg-term – статистические функции, применяемые к полям и eval-выражениям. Результат выполнения функции может быть помещён в отдельное поле с именем, указанным после операнда AS.

  Синтаксис:
  <stats-func> ( <evaled-field> | <field> ) [AS <newfield>]

  Перечень функций представлен в разделе ниже.

Опциональные параметры:

• BY <field-list> – одно или несколько полей, по которым будет производиться группировка вычисляемой статистики.

• time_window=<span-length> – временное окно для выполнения "потоковых вычислений". Статистика, определенная аргументом stats-agg-term, считается для событий, которые попадают во временное окно, заданное аргументом time_window. Аргумент time_window ограничен диапазоном значения поля _time для обрабатываемых событий. Для использования аргумента time_window события должны быть отсортированы в убывающем или возрастающем порядке по полю _time. Аргумент time_window может использоваться вместе с аргументом window.

  Синтаксис: time_window=<span-length>, где <span-length> – диапазон времени в секундах.

• window=<int> – количество событий, в пределах которого происходит подсчет статистики. Если window равно нулю, то расчет статистики будет выполнен только для одного события – того, которое обрабатывается в данный момент.

Статистические функции

Функции позволяют получить различные статистики по полю или eval-выражению, к которому они применяются.

В таблице представлен перечень функций, сгруппированных по типам:

Имя функции	Описание функции
Агрегирующие функции:
approxdc()	Приблизительное количество уникальных значений.
avg()	Среднее арифметическое.
count()	Количество значений.
distinct_count()	Количество уникальных значений.
max()	Наибольшее значение.
min()	Наименьшее значение.
perc()	Процентиль.
percentile_approx()
stdev()	Стандартное отклонение.
sum()	Сумма значений.
var()	Дисперсия.
Порядковые функции:
first()	Первое значение в таблице.
last()	Последнее значение в таблице.
Функции для работы с multivalue-полями:
list()	Список значений.
values()
Временные функции:
earliest()	Первое значение в таблице.
latest()	Последнее значение в таблице.

Примеры использования

Исходные данные:

_time	dest_country	currency	sum
2019-10-02 12:20:00	Italy	EUR	10
2019-10-02 12:20:01	Russia	USD	13
2019-10-02 12:20:02	Canada	RUB	14
2019-10-02 12:20:03	Canada	EUR	1
2019-10-02 12:20:04	Russia	USD	3
2019-10-02 12:20:05	Italy	RUB	4
2019-10-02 12:20:06	Italy	RUB	5

Пример 1

Просматривает подряд события в таблице и, по мере просмотра, вычисляет три новых поля. Вычисление происходит таким образом, что на момент просмотра очередного события в трех новых полях находятся, соответственно, максимальное, минимальное и сумма значений этого поля sum среди тех событий, которые уже просмотрены.

Запрос:

... | streamstats count as count max(sum) as "max num" min(sum) as "min num" sum(sum) as "sum num"

Результат:

_time	count	currency	dest_country	max num	min num	sum	sum num
2019-10-02 12:20:00	1	EUR	Italy	10	10	10	10
2019-10-02 12:20:01	2	USD	Russia	13	10	13	23
2019-10-02 12:20:02	3	RUB	Canada	14	10	14	37
2019-10-02 12:20:03	4	EUR	Canada	14	1	1	38
2019-10-02 12:20:04	5	USD	Russia	14	1	3	41
2019-10-02 12:20:05	6	RUB	Italy	14	1	4	45
2019-10-02 12:20:06	7	RUB	Italy	14	1	5	50

Пример 2

Просматривает подряд события в таблице и, по мере просмотра, вычисляет новое поле count – количество переводов в разрезе валюты (currency). Вычисление происходит таким образом, что на момент просмотра очередного события поле count содержит статистику только в отношении тех событий, которые уже просмотрены.

Запрос:

... | streamstats count by currency

Результат:

_time	count	currency	dest_country	sum
2019-10-02 12:20:00.000+0300	1	EUR	Italy	10
2019-10-02 12:20:01.000+0300	1	USD	Russia	13
2019-10-02 12:20:02.000+0300	1	RUB	Canada	14
2019-10-02 12:20:03.000+0300	2	EUR	Canada	1
2019-10-02 12:20:04.000+0300	2	USD	Russia	3
2019-10-02 12:20:05.000+0300	2	RUB	Italy	4
2019-10-02 12:20:06.000+0300	3	RUB	Italy	5

Пример 3

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

Запрос:

... | streamstats window=3 sum(sum) as "total"

Результат:

_time	currency	dest_country	sum	total
2019-10-02 12:20:00	EUR	Italy	10	10
2019-10-02 12:20:01	USD	Russia	13	23
2019-10-02 12:20:02	RUB	Canada	14	37
2019-10-02 12:20:03	EUR	Canada	1	28
2019-10-02 12:20:04	USD	Russia	3	18
2019-10-02 12:20:05	RUB	Italy	4	8
2019-10-02 12:20:06	RUB	Italy	5	12

SUPERJOIN

Команда superjoin комбинирует данные из таблицы, указанной в параметрах команды superjoin, с результатами основного запроса без каких-либо ограничений на размер таблицы.

Важно!
Команда superjoin не является частью стандартного набора команд. Находится в плагине OTLExtend.

Синтаксис команды

superjoin <field-list> <superjoin-params>

Обязательные параметры:

• field-list – поля, по которым будет выполнена команда superjoin. Совпадение значений полей основного запроса и подзапроса должно быть с точностью до регистра отдельных символов.

  Синтаксис: <field1>, <field2>, ...

• superjoin-params – опции команды superjoin.

  Синтаксис:

type=(inner|outer|left) format=(parquet|csv|orc|)  path=(parquet|csv|orc|)

Описание:

• type – тип команды superjoin.

  Синтаксис: type=inner | outer | left.

  Значение по умолчанию отсутствует.

  Разница между типами заключается в том, каким образом обрабатываются события основного запроса, которые не могут быть поставлены в соответствие событиям из таблицы. Как в inner так и в left возвращаются только те события, которые могут быть поставлены в соответствие друг другу по заданному полю. Однако результаты inner join не включают события основного запроса, которые не имеют совпадений в присоединяемой таблице. Результат же left join (или outer join) включает все события основного запроса и те события из присоединяемой таблицы, которые могут быть поставлены в соответствие событиям основного запроса по заданному полю.

  • format – формат таблицы, с которой соединяются результаты основного запроса.

    Синтаксис: format=(parquet|csv|orc|).

    Значение по умолчанию отсутствует.

  • path – путь к таблице с которой соединяются результаты основного запроса в external_data.

    Синтаксис: path=(path/to/table).

    Значение по умолчанию отсутствует.

Пример использования

...| superjoin id, day type=left format=parquet path=folder/table1 

TAIL

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

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

Синтаксис команды

tail [<N>] | [limit=<int>]

Опциональные параметры:

• N – количество возвращаемых результатов.

  Значение по умолчанию = 10.

• limit=<int> – другой вариант задания количества возвращаемых результатов.

Примеры использования

Пример 1

Возвращает последние четыре транзакции из списка.

Исходные данные:

datetime	currency	dest	sum
1587045110	RUB	Russia	10
1587045120	USD	Russia	7
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

Запрос:

... | tail 4

Результат:

datetime	currency	dest	sum
1587045130	EUR	Germany	21
1587045140	EUR	USA	3
1587045150	RUB	Germany	19
1587045160	EUR	Russia	7

TIMECHART

Команда создает диаграмму временного ряда с соответствующей ей статистической таблицей.

Диаграмма временного ряда – это диаграмма с отображением времени на оси X. По оси Y отображаются значения, вычисленные применением к какому-либо полю статистической агрегации.

Синтаксис команды

timechart [span=<timescale>] (<stats-agg-term> 
BY <split-by-clause>)

Обязательные параметры:

• stats-agg-term – статистические функции (перечень см. в разделе ниже), применяемые к полям и eval-выражениям. Результат выполнения функции может быть помещён в отдельное поле с именем, указанным после операнда AS.

  Синтаксис: <stats-func>( <evaled-field> | <wc-field> ) [AS <new-field>].

• BY <split-by-clause> – поле для разделения результатов.

Каждый раз, когда вызывается команда timechart, можно использовать одну или несколько функций. Однако оператор BY можно использовать только один раз.

Опциональный параметр:

• span=<timescale> – временной интервал для группировки. Возможные варианты указаны в таблице ниже.

Временные рамки	Доступный синтаксис	Описание
<sec>	"s" | "sec"	Шкала времени в секундах
<min>	"m" | "min"	Шкала времени в минутах
<hr>	"h"	Шкала времени в часах
<day>	"d"	Шкала времени в днях
<week>	"w"	Шкала времени в неделях
<month>	"mon"	Шкала времени в месяцах

Статистические функции

Функции позволяют получить различные статистики по полю или eval-выражению, к которому они применяются.

В таблице представлен перечень функций, сгруппированных по типам:

Имя функции	Описание функции
Агрегирующие функции:
approxdc()	Приблизительное количество уникальных значений.
avg()	Среднее арифметическое.
count()	Количество значений.
distinct_count()	Количество уникальных значений.
max()	Наибольшее значение.
min()	Наименьшее значение.
perc()	Процентиль.
percentile_approx()
stdev()	Стандартное отклонение.
sum()	Сумма значений.
var()	Дисперсия.
Порядковые функции:
first()	Первое значение в таблице.
last()	Последнее значение в таблице.
Функции для работы с multivalue-полями:
list()	Список значений.
values()
Временные функции:
earliest()	Первое значение в таблице.
latest()	Последнее значение в таблице.

Примеры использования

Пример 1

Агрегирует в интервалы по двое суток статистику размеров авиатрафика.

Исходные данные:

Terminal	_time	Arrivals	Departures
TerminalA	1556704800	235	321
TerminalB	1556704800	178	167
TerminalC	1556704800	79	68
TerminalA	1556791200	216	278
TerminalB	1556791200	165	145
TerminalC	1556791200	64	60
TerminalA	1556877600	223	216
TerminalB	1556877600	143	120
TerminalC	1556877600	87	98
TerminalA	1556964000	145	256
TerminalB	1556964000	124	167
TerminalC	1556964000	89	51
TerminalA	1557050400	256	170
TerminalB	1557050400	146	198
TerminalC	1557050400	95	101

Запрос:

... 
| eval Air_traffic=Arrivals+Departures 
| timechart span=2d sum(Air_traffic) by Terminal 
| rename _time as Time 
| eval Time=strftime(Time, "%Y-%m-%dT%H:%M:%S")

В запросе время конвертируется из Unix-time формата в понятный для человека формат.

Результат:

Time	TerminalA	TerminalB	TerminalC
2019-04-30T03:00:00	556	345	147
2019-05-02T03:00:00	933	573	309
2019-05-04T03:00:00	827	635	336

Пример 2

Агрегирует в интервалы по двое суток минимальное и максимальное значения авиатрафика.

Исходные данные:

Terminal	_time	Arrivals	Departures
TerminalA	1556704800	235	321
TerminalB	1556704800	178	167
TerminalC	1556704800	79	68
TerminalA	1556791200	216	278
TerminalB	1556791200	165	145
TerminalC	1556791200	64	60
TerminalA	1556877600	223	216
TerminalB	1556877600	143	120
TerminalC	1556877600	87	98
TerminalA	1556964000	145	256
TerminalB	1556964000	124	167
TerminalC	1556964000	89	51
TerminalA	1557050400	256	170
TerminalB	1557050400	146	198
TerminalC	1557050400	95	101

Запрос:

... 
| eval Air_traffic=Arrivals+Departures 
| timechart span=2d max(Air_traffic) as "max" min(Air_traffic) as "min" by Terminal 
| rename _time as Time 
| eval Time=strftime(Time, "%Y-%m-%dT%H:%M:%S")

В запросе время конвертируется из Unix-time формата в понятный для человека формат.

Результат:

Time	max: TerminalA	min: TerminalA	max: TerminalB	min: TerminalB	max: TerminalC	min: TerminalC
2019-05-02T03:00:00	494	439	310	263	185	124
2019-05-04T03:00:00	426	401	344	291	196	140

TOP

Команда находит наиболее часто встречающиеся значения в выбранных полях.

Синтаксис команды

top [<number>] <field-list> [<by-clause>]

Команда вычисляет количество и процентное соотношение того, как часто выбранные значения встречаются в событиях. Если добавлена опция by-clause, то результат будет сгруппирован по полю, указанному после by.

Обязательный параметр:

• field-list – поле или список полей (через запятую или пробел), по которым проводится подсчёт.

Опциональный параметр:

• number – указывается количество верхних строк, которые должны быть выведены в результате. По умолчанию: 10.

• by-clause – одно или несколько полей, значения которых будут названиями столбцов в результирующей таблице.

Пример использования

Выводит 3 наиболее часто встречающихся Имени.

Исходные данные:

Name	Surname	age
John	Snow	10
Alex	Smith	7
Anna	Show	21
John	Bond	3
John	Smith	19
Tony	Stark	5
John	Dow	19
Tony	Pitt	5

Запрос:

... | top 3 Name

Результат:

Name	count	percent
John	4	50
Tony	2	25
Alex	1	12.5

TRANSACTION

Команда позволяет найти среди множества записей, сгруппированных по указанному набору полей, первую по времени запись (в своей группе).

Например, исходные данные содержат название месторождения, название метрики и значение метрики. Для такого набора данных команда transaction позволяет найти первую по времени запись для каждого уникального значения каждой уникальной метрики для каждого уникального месторождения. Транзакцией в данном случае называется совокупность следующих данных: название месторождения, название метрики, значение метрики.

Исходя из описания, следует отметить, что исходный набор данных должен содержать временную отметку в виде поля _time (время измерения). Если поле _time отсутствует, то команда вернет набор данных, сгруппированный по полям, указанным в параметрах. При этом поля, не указанные в параметрах команды, но присутствующие в наборе данных, будут представлены массивами своих значений.

Например, если в описанном выше наборе данных есть поле с номером скважины (при этом на одном месторождении может располагаться несколько скважин), но его нет среди параметров команды transaction (то есть группировка по нему не производится), то в результирующем наборе это поле будет представлено массивом значений, соответствующих транзакции с полями название месторождения, название метрики, значение метрики.

Использование команды transaction c набором данных без поля _time, а также включение данного поля в список параметров команды нежелательно. Если поле _time будет указано среди параметров, то группировка будет производиться в том числе и по нему, что лишает смысла использование команды.

Более детально рассмотрим правила работы команды на примерах ниже.

Синтаксис команды

transaction [field-list]

Обязательные параметры: отсутствуют.

Опциональный параметр:

• field-list – непустой список полей, по которым будет формироваться транзакция.

  Синтаксис: <field1>, <field2>, ...

Примеры использования

Исходные данные:

Набор представляет результаты измерений двух метрик – температуры и влажности – на скважинах нескольких месторождений. На одно месторождение может приходиться несколько скважин.

_time	deposit	well	metric_name	value
1641744164	"deposit_1"	"well_1"	temperature	27
1641744164	"deposit_1"	"well_2"	temperature	27
1641744164	"deposit_2"	"well_1"	temperature	27
1641744164	"deposit_2"	"well_2"	temperature	27
1641744164	"deposit_3"	"well_1"	temperature	27
1641744364	"deposit_1"	"well_1"	temperature	26
1641744364	"deposit_2"	"well_2"	temperature	25
1641744364	"deposit_3"	"well_1"	temperature	27
1641744164	"deposit_1"	"well_2"	humidity	47
1641744164	"deposit_2"	"well_1"	humidity	67
1641744164	"deposit_3"	"well_2"	humidity	57
1641744364	"deposit_1"	"well_1"	humidity	36
1641744364	"deposit_1"	"well_2"	humidity	36
1641744364	"deposit_2"	"well_2"	humidity	55
1641744364	"deposit_3"	"well_1"	humidity	57

Пример 1

Исходные данные содержат поле _time, однако среди параметров команды поле _time отсутствует. При этом все поля исходных данных указаны в списке параметров команды. В этом случае команда вернёт набор уникальных транзакций с полями deposit, well, metric_name и value. Каждая уникальная транзакция при этом будет иметь в качестве поля _time минимальное значение времени среди всех записей исходных данных, подходящих под ограничения данной транзакции.

Запрос:

... | transaction deposit, well, metric_name, value

Результат:

deposit	well	metric_name	value	_time
"deposit_2"	"well_2"	humidity	55	1641744364
"deposit_1"	"well_1"	humidity	36	1641744364
"deposit_1"	"well_1"	temperature	27	1641744164
"deposit_2"	"well_1"	temperature	27	1641744164
"deposit_2"	"well_1"	humidity	67	1641744164
"deposit_3"	"well_1"	temperature	27	1641744164
"deposit_1"	"well_1"	temperature	26	1641744364
"deposit_1"	"well_2"	humidity	36	1641744364
"deposit_1"	"well_2"	humidity	47	1641744164
"deposit_3"	"well_2"	humidity	57	1641744164
"deposit_3"	"well_1"	humidity	57	1641744364
"deposit_2"	"well_2"	temperature	27	1641744164
"deposit_2"	"well_2"	temperature	25	1641744364
"deposit_1"	"well_2"	temperature	27	1641744164

Пример 2

Исходные данные содержат поле _time, однако среди параметров команды поле _time отсутствует. При этом не все поля исходных данных указаны в списке параметров команды (отсутствует well). В этом случае команда вернёт набор уникальных транзакций с полями deposit, metric_name и value. Поле с названием скважины well будет представлено массивом. Если одно и то же значение конкретной метрики на конкретном месторождении встречается одновременно на нескольких скважинах, то в этом поле будут указаны все такие скважины (одному уникальному сочетанию значений полей deposit, metric_name, value соответствует несколько скважин, которые и представлены массивом названий). Каждая уникальная транзакция при этом будет иметь в качестве поля _time минимальное значение времени среди всех записей исходных данных, подходящих под ограничения данной транзакции.

Запрос:

... | transaction deposit, metric_name, value

Результат:

deposit	metric_name	value	_time	well
"deposit_2"	humidity	55	1641744364	[ "well_2" ]
"deposit_3"	humidity	57	1641744164	[ "well_2", "well_1" ]
"deposit_3"	temperature	27	1641744164	[ "well_1" ]
"deposit_1"	humidity	47	1641744164	[ "well_2" ]
"deposit_1"	temperature	26	1641744364	[ "well_1" ]
"deposit_2"	temperature	27	1641744164	[ "well_2" , "well_1" ]
"deposit_2"	temperature	25	1641744364	[ "well_2" ]
"deposit_1"	humidity	36	1641744364	[ "well_2" , "well_1" ]
"deposit_1"	temperature	27	1641744164	[ "well_2" , "well_1" ]
"deposit_2"	humidity	67	1641744164	[ "well_1" ]

Пример 3

Исходные данные содержат поле _time, поле _time присутствует среди параметров команды. При этом все поля исходных данных указаны в списке параметров команды. В этом случае команда вернет набор записей, сгруппированных по параметрам, которые присутствуют в наборе данных, но отсутствуют среди параметров команды. А поскольку в параметрах команды указаны все поля исходного набора, группировка будет производиться по всем полям в наборе данных. Таким образом, команда вернёт набор данных, аналогичный исходному (порядок записей при этом может отличаться от исходного).

Запрос:

... | transaction deposit, well, metric_name, value, _time

Пример 4

Исходные данные содержат поле _time, поле _time присутствует среди параметров команды. При этом не все поля исходных данных указаны в списке параметров (отсутствует – well). В этом случае команда вернет набор записей, сгруппированных по параметрам, которые присутствуют в наборе данных, но отсутствуют среди параметров команды. В данном случае среди параметров отсутствует только поле well, поэтому данное поле будет представлено массивом, содержащим все названия скважин, соответствующие уникальному сочетанию значений полей _time, deposit, metric_name, value.

Запрос:

... | transaction deposit, metric_name, value, _time

Результат:

deposit	metric_name	value	_time	well
"deposit_1"	temperature	26	1641744364	[ "well_1" ]
"deposit_3"	temperature	27	1641744364	[ "well_1" ]
"deposit_3"	temperature	27	1641744164	[ "well_1" ]
"deposit_2"	humidity	55	1641744364	[ "well_2" ]
"deposit_3"	humidity	57	1641744364	[ "well_1" ]
"deposit_1"	humidity	47	1641744164	[ "well_2" ]
"deposit_1"	humidity	36	1641744364	[ "well_2" , "well_1" ]
"deposit_1"	temperature	27	1641744164	[ "well_2" , "well_1" ]
"deposit_2"	temperature	27	1641744164	[ "well_2" , "well_1" ]
"deposit_3"	humidity	57	1641744164	[ "well_2" ]
"deposit_2"	humidity	67	1641744164	[ "well_1" ]
"deposit_2"	temperature	25	1641744364	[ "well_2" ]

TRANSPOSE

Команда возвращает заданное число рядов поисковых результатов в виде колонок – происходит операция транспонирования.

Синтаксис команды

transpose [int] [column_name=<string>] [header_field=<field>] [include_empty=<bool>]

Обязательные параметры: отсутствуют.

Опциональные параметры:

• column_name – имя, которое будет носить первая колонка. Значениями ячеек в этой колонке будут наименования столбцов до применения команды transpose.

  Значение по умолчанию: column.

• header_field – имя колонки до трансформации, значения из которой будут использованы как имена колонок (кроме первой колонки) в транспонированных данных.

  Значение по умолчанию: row 1, row 2, row 3, и т.д.

• include_empty – определяет включать (true) или нет (false) в операцию транспонирования те поля, которые содержат пустые и только пустые значения.

  Значение по умолчанию: true.

• int – определяет количество рядов для транспонирования. Чтобы транспонировать все ряды, значение параметра должно быть равно нулю.

  Значение по умолчанию: 5.

Примеры использования

Исходные данные:

currency	dest_country	sum
RUB	Russia	10
USD	Russia	7
EUR	Germany	21
EUR	USA	3
RUB	Germany	19
EUR	Russia	7

Пример 1

Транспонирует таблицу, выводит 5 результатов транспонирования (значение по умолчанию), переименовывает первую колонку из названия по умолчанию в col_values (из column в col_values).

Запрос:

... | transpose column_name=col_values

Результат:

col_values	row 1	row 2	row 3	row 4	row 5
currency	RUB	USD	EUR	EUR	RUB
dest_country	Russia	Russia	Germany	USA	Germany
sum	10	7	21	3	19

Пример 2

Транспонирует таблицу, в качестве имен столбцов берутся значения столбца dest_country до транспонирования.

... | transpose  header_field=dest_country

Результат:

column	Russia	Germany	USA
currency	USD	USD	RUB
sum	7	7	19

UNTABLE

Команда преобразует данные, изначально представленные в виде широкой таблицы, в длинную таблицу.

Примечание.
В широкой таблице каждая метрика представлена в отдельной колонке. В длинной таблице есть колонка, содержащая имена метрик, колонка, содержащая значения метрик (пара "ключ-значение").

Команда позволяет, зафиксировав значение одной из колонок (например, поле _time), разбить каждую из строк исходной таблицы на несколько строк в результирующей таблице.

Синтаксис команды

untable <fixed_column=<string>>, <field_column=<string>>, <value_column=<string>>

Обязательные параметры:

• fixed_column – имя колонки, по которой будут группироваться данные (чаще всего используется колонка с полем _time).

• field_column – имя колонки, которая будет содержать имена метрик.

• value_column – имя колонки, в которую нужно поместить значения метрик.

Опциональные параметры отсутствуют.

Пример использования

Нужно преобразовать широкую таблицу в длинную. Данные группируются по полю _time. Каждая исходная строка разбивается на 4 строки.

Исходные данные:

_time	temperature	humidity	carbon_dioxide_level	air_pressure
1641744664	27	42	452	756
1641744774	18	37	537	759
1641744884	23	47	425	763

Запрос:

... | untable _time, metric_name, value

Результат:

_time	metric_name	value
1641744664	temperature	27
1641744664	humidity	42
1641744664	carbon_dioxide_level	452
1641744664	air_pressure	756
1641744774	temperature	18
1641744774	humidity	37
1641744774	carbon_dioxide_level	537
1641744774	air_pressure	759
1641744884	temperature	23
1641744884	humidity	47
1641744884	carbon_dioxide_level	425
1641744884	air_pressure	763

WHERE

Команда where использует eval-выражения для фильтрации результатов запроса. Эти eval-выражения должны быть булевыми выражениями, то есть возвращать true или false значения. Команда where пропускает только те результаты, для которых eval-выражения возвращают true.

Синтаксис команды

where <eval-expression>

Команда where использует синтаксис, схожий с командой eval.

Команда интерпретирует строки, заключенные в кавычки, как строковые значения. Если строка не имеет кавычек, то она обрабатывается как поле. Эта особенность позволяет, в отличие от команды search, сравнивать два отдельных поля.

Для поиска по нескольким значениям полей можно использовать логические выражения: or, and. Также необходимо учитывать тип данных того поля, по которому производится поиск, так как к строковым значениям нельзя применить операции сравнения (<, >, >=, <=).

Обязательный параметр:

• eval-expression – операции сравнения, логические выражения, в том числе содержащие функции (перечень функций представлен ниже).

Таблица указывает на особенности синтаксиса, которые нужно учитывать при построении запроса:

Символы в выражениях	Описание	Пример
Имена полей начинаются с числа	Если выражение обращается к полю, имя которого начинается с цифры, рекомендуется такое поле заключать в одинарные кавычки (апострофы).	'10km'="far" Это выражение представляет собой поле, которое сравнивается со строкой. Так как поле начинается с цифры, оно заключено в одинарные кавычки, а строка заключена в двойные кавычки.
Имена полей, содержащие не цифро-буквенные символы.	Если выражение обращается к полю, имя которого содержит не цифро-буквенные символы, то это поле должно быть заключено в одинарные кавычки (апострофы).	coord=xy+'point-1' Это выражение могло быть интерпретировано как математическое сравнение, где дефис считался бы минусом. Для того, чтобы избежать этого, нужно заключить поле point-1 в одинарные кавычки.
Строки	Если выражение указывает определенную строку, то эту строку следует заключать в двойные кавычки.	coord="position-"+count Здесь position- могло бы быть интерпретировано как поле или как часть математического сравнения, которое использует знаки плюс и минус. Чтобы убедиться, что строка интерпретируется правильно, position- заключается в двойные кавычки.

Булевые выражения проходят обработку командой where в следующей последовательности:

NOT условие

AND условие

OR условие

Символ регулярного выражения звездочка (wildcard) может быть использован только в функции like().

Сравнительная функция like() возвращает TRUE если значение поля (или просто строка) согласуется с заданным выражением.

Синтаксис: like(TEXT, PATTERN)

Аргументы функции:

• TEXT – строка или поле, которое проверяется.

• PATTERN – строка-выражение, с которым сравнивается TEXT.

  Можно использовать символ процент (%) для нескольких (одного и более) строковых символов или символ подчёркивания (_) для одного символа.

Символ процента ( % ) является заменой символа wildcard (*).

Вы можете использовать довольно широкий набор функций в команде where. Все они представлены в таблице:

Тип функции	Функции и синтаксис
Сравнительные и условные функции	case(X,"Y",...), coalesce(X,...), if(X,Y,Z), like(TEXT, PATTERN), match(SUBJECT, "REGEX"), nullif(X,Y), true()
Функции конвертации	printf, tonumber(NUMSTR,BASE), tostring(X,Y)
Криптографические функции	md5(X), sha1(X)
Функции даты и времени	now(), relative_time(X,Y), strptime(X,Y)
Информационные функции	isnotnull(X), isnull(X)
Математические функции	abs(X), ceiling(X) или ceil(X), exp(X), floor(X), ln(X), log(X,Y), pi(), pow(X,Y), round(X,Y), sqrt(X)
Функции преобразования для мультизначений	mvappend(X,...), mvcount(MVFIELD), mvdedup(X), mvfind(MVFIELD,"REGEX"), mvindex(MVFIELD,STARTINDEX, ENDINDEX), mvjoin(MVFIELD,STR), mvrange(X,Y,Z), mvsort(X), mvzip(X,Y,"Z"), split(X,"Y")
Статистические функции	max(X,...), min(X,...)
Текстовые функции	len(X), lower(X), replace(X,Y,Z), substr(X,Y,Z), upper(X)
Тригонометрические и гиперболические функции	acos(X), asin(X), atan(X), atan2(Y, X), cos(X), hypot(X,Y), sin(X), tan(X)

Примеры использования

Исходные данные:

Имеются таблица студентов разных возрастов.

Name	Surname	age
John	Snow	10
Alex	Smith	7
Anna	Show	21
James	Bond	3
John	SMITH	19
Tony	Stark	5
John	Dow	14
Tony	Pitt	5

Пример 1

Выводим всех студентов по фамилии "Smith", учитывая, что фамилии написаны в разных регистрах.

Запрос:

... | where lower(Surname)="smith"

Результат:

Name	Surname	age
Alex	Smith	7
John	SMITH	19

Пример 2

Выводим всех студентов старше 10 лет и с именем, начинающимся на букву "J".

Запрос:

... | where age>10 and like(Name,"J%")

Результат:

Name	Surname	age
John	Snow	10
James	Bond	3
John	SMITH	19
John	Dow	14

XYSERIES

Команда конвертирует результаты в табличный формат, пригодный для визуализации результата в формате диаграммы или графика.

Синтаксис команды

xyseries <x-field> <y-name-field> <y-data-field>

Обязательные параметры:

• x-field – значения поля, которые будут отложены на оси Х при рисовании графика. Синтаксис: <field>.

• y-name-field – значения поля, которые будут отложены на оси Y при рисовании графика. Синтаксис: <field>.

• y-data-field – значения поля, которые будут точками графика.
  Синтаксис: <field>.

Опциональные параметры: отсутствуют.

Примеры использования

Исходные данные:

currency	dest_country	sum
EUR	Italy	10
USD	Russia	13
RUB	Canada	14
EUR	Canada	1
USD	Russia	3
MXN	Mexico	7

Пример 1

Форматирует данные к пригодному для визуализации виду. По оси Х будут отложены значения поля dest_country, по оси Y значения поля currency, точками графика (или диаграммы) будут значения поля sum. Результат может быть визуализирован, например, в формате столбчатой диаграммы.

Запрос:

| xyseries dest_country currency sum 

Результат:

EUR	MXN	RUB	USD	dest_country
10				Italy
	7			Mexico
			13	Russia
1		14		Canada

Приложение

Использование макросов в запросах

Реализация данной функциональности связана с оптимизацией использования в OTL-запросах повторяющихся наборов команд. Для этих целей повторяющиеся последовательности можно оформить в виде макросов.

Синтаксис использования макроса

|__<имя макроса>__ <аргументы макроса>

_<имя макроса>_ – имя макроса с двух сторон обрамляется двойным подчёркиванием (__);

<аргументы макроса> – аргументы макроса, разделённые пробелами; аргументы могут быть следующих типов:

• Аргументы значений:

  • <имя поля/токена>=<значения через запятую>;

  • отсутствие аргумента/аргументов при наличии токена макрос интерпретирует как: absent_arg=*.

• Аргументы времени.

  В качестве аргументов времени используются ключевые слова:

  • latest – начальная граница временного интервала;

  • earliest – конечная граница временного интервала.

    Формат даты в аргументе: YYYY-MM-DD. В процессе обработки макроса дата преобразуется в формат Epoch time (Linux time).

    Возможные комбинации значений аргументов:

  • earliest=2019-11-01 latest=2019-12-31 – задаёт период с 2019/11/01 по 2019/12/31;

  • earliest=2019-11-01 – задаёт период с 2019/11/01 по настоящее время;

  • latest=2019-12-31 – задаёт период с 1970/01/01 по 2019/12/31;

  • аргументы не заданы – временное окно определяется в границах с 1970/01/01 по настоящее время.

• Аргументы фильтрации полей.

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

  По заданным шаблонам происходит поиск имен полей в файле алиасов (см. в разделе ниже) без учета регистра.

  В случае отсутствия полей, удовлетворяющих условиям фильтрации, макрос отработает по всем полям.

Пример.

      | __getwell__ wellNum=4,12,1898 padNum=4 earliest=2019-11-01 
        latest=2019-12-31 debit freq

Имя макроса: _ _ getwell _ _

Аргументы значений: wellNum, padNum

аргумент wellNum=4,12,1898

интерпретируется как wellNum=4 OR wellNum=12 OR wellNum=1898

Аргументы времени: earliest, latest

earliest=2019-11-01 latest=2019-12-31 – аргументы задают период с 2019/11/01 по 2019/12/31

Аргументы фильтрации полей: debit, freq

По заданным шаблонам debit и freq будут отобраны следующие поля (см. пример в файле алиасов ниже):

debit:

adkuLiquidDebit

wellopLiquidDebitTM

freq:

ksADKUEngineFreq

wellopPumpFreqTm

На выходе получим следующий текст сгенерированного запроса:

            | table _time, wellNum, padNum, adkuLiquidDebit,
              wellopLiquidDebitTM, ksADKUEngineFreq, wellopPumpFreqTm

Конфигурационный файл макроса

Конфигурационный файл макроса должен быть размещён в распределенном файловом хранилище, путь к которому настраивается в конфигурационном файле OT.REST.

Файл должен содержать только один макрос.

В случае отсутствия аргумента в команде – строка, содержащая одноименный токен, не будет изменена. В случае наличия лишнего аргумента - он будет проигнорирован.

Пример.

../macros/getwell.macros

| readFile format=parquet path=omds_well_adku_v2
| search $wellNum$
| search _time>=$earliest$ AND _time<$latest$
| ``` Джойним номер куста и ID станции управления по ID скважины ```
| join type=inner ID [ 
  | readFile format=parquet path=oms_v5
  | fields IDObj, geoNum, Description, IDPad, IDWell
  | eval geoPad = if(Description="Pad", geoNum, null)
  | eval idKS = if(Description="controlStation", IDObj, null)
  | eventstats min(geoPad) as padNum by IDPad
  | eventstats min(idKS) as IDKs by IDWell
  | search Description="Well" AND ($padNum$)
  | rename IDObj as ID
  | fields ID, padNum, IDKs ]
| ``` Джойним данные из ШТР по ID скважины ```
| join _time, ID type=outer [ 
  | readFile format=parquet path=omds_well_wellop_v15 
  | search _time>=$earliest$ AND _time<$latest$ 
  | table _time, ID, wellop* ]
| fields _time, ID, adku*, wellop*
| ``` Джойним данные со станции управления по ID скважины ```
| join  _time, IDKs type=outer [ 
  | readFile format=parquet path=omds_ks_v3 
  | search _time>=$earliest$ AND _time<$latest$ 
  | rename ID as IDKs 
  | table _time, IDKs, ks* ] 
| sort _time

Конфигурационный файл алиасов

Конфигурационный файл алиасов – csv-файл – предназначен для установки соответствия между именами полей в базе данных и названиями столбцов, выводимых в пользовательские таблицы.

Файл размещается в распределенном файловом хранилище.

Макрос использует из csv-файла только имена полей.

Пример:

../macros/names.csv

adkuLiquidDebit,Дебит жидкости,3

adkuWellStatus,ТС Скважины,3

adkuTorLiquidDebit,ТОР. Дебит жидкости,3

adkuGazConsumption,Расход газа,3

Механизм работы

1. Оригинальный запрос попадает на OT.REST.

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

3. Сформированный запрос обрабатывается аналогично обычным поисковым запросам.