Конструктор запросов

ClickHouse Supported

Любой запрос можно выполнить с помощью плагина ClickHouse. Конструктор запросов — удобный вариант для простых запросов, но для сложных запросов потребуется использовать SQL Editor.

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

Доступные типы запросов:

• Table: самый простой тип запроса для отображения данных в табличном формате. Хорошо подходит как универсальный вариант для простых и сложных запросов, содержащих агрегатные функции.
• Logs: оптимизирован для построения запросов к логам. Лучше всего работает в режиме обзора при настроенных значениях по умолчанию.
• Time Series: лучше всего подходит для построения запросов по временным рядам. Позволяет выбрать отдельный временной столбец и добавлять агрегатные функции.
• Traces: оптимизирован для поиска и просмотра трейсов. Лучше всего работает в режиме обзора при настроенных значениях по умолчанию.
• SQL Editor: SQL Editor можно использовать, когда вам нужен полный контроль над запросом. В этом режиме можно выполнять любые SQL-запросы.

Типы запросов

Настройка Query Type изменяет компоновку конструктора запросов в соответствии с типом создаваемого запроса. Тип запроса также определяет, какая панель используется при визуализации данных.

Table

Наиболее гибкий тип запроса — табличный запрос. Это универсальный вариант для других конструкторов запросов, предназначенный для обработки простых и агрегирующих запросов.

Field	Description
Builder Mode	Простые запросы исключают Aggregates и Group By, тогда как агрегирующие запросы включают эти опции.
Columns	Выбранные столбцы. В это поле можно вводить «сырой» SQL, чтобы использовать функции и алиасы столбцов.
Aggregates	Список aggregate functions. Позволяет указывать произвольные значения для функции и столбца. Отображается только в режиме Aggregate.
Group By	Список выражений GROUP BY. Отображается только в режиме Aggregate.
Order By	Список выражений ORDER BY.
Limit	Добавляет оператор LIMIT в конец запроса. Если установлено значение 0, он будет исключён. Для некоторых визуализаций может потребоваться установка 0, чтобы показать все данные.
Filters	Список фильтров, применяемых в предложении WHERE.

Этот тип запроса отобразит данные в виде таблицы.

Logs

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

Фильтры Time и Level добавляются по умолчанию, вместе с Order By для столбца Time. Эти фильтры привязаны к соответствующим полям и будут обновляться при изменении столбцов. Фильтр Level по умолчанию исключён из SQL; изменение его с опции IS ANYTHING включает его.

Тип запроса для логов поддерживает data links.

Field	Description
Use OTel	Включает столбцы OpenTelemetry. Перезаписывает выбранные столбцы, чтобы использовать столбцы, определённые выбранной версией схемы OTel (отключает выбор столбцов).
Columns	Дополнительные столбцы, добавляемые к строкам логов. В это поле можно вводить «сырой» SQL, чтобы использовать функции и алиасы столбцов.
Time	Основной столбец временной метки для лога. Отображает типы, похожие на время, но также допускает пользовательские значения/функции.
Log Level	Необязательно. Уровень или severity лога. Значения обычно выглядят как INFO, error, Debug и т. п.
Message	Содержимое сообщения лога.
Order By	Список выражений ORDER BY.
Limit	Добавляет оператор LIMIT в конец запроса. Если установлено значение 0, он будет исключён, но это не рекомендуется для больших наборов логов.
Filters	Список фильтров, применяемых в предложении WHERE.
Message Filter	Текстовое поле для удобной фильтрации логов с помощью LIKE %value%. Исключается, когда поле ввода пустое.

Этот тип запроса отобразит данные на панели логов вместе с панелью гистограммы логов в верхней части.

Дополнительные столбцы, выбранные в запросе, можно просмотреть в развёрнутой строке лога:

Time series

Тип запроса временного ряда аналогичен table, но с фокусом на данных временных рядов.

Два представления в основном одинаковы, с такими примечательными отличиями:

• Отдельное поле Time.
• В режиме Aggregate автоматически применяется макрос временного интервала вместе с Group By по полю Time.
• В режиме Aggregate поле «Columns» скрыто.
• Для поля Time автоматически добавляются фильтр временного диапазона и Order By.

В вашей визуализации отсутствуют данные?

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

Попробуйте убрать предложение LIMIT, установив его в 0 (если это допустимо для вашего набора данных).

Field	Description
Builder Mode	В режиме Simple из запросов исключаются агрегаты и GROUP BY, тогда как в режиме Aggregate эти опции доступны.
Time	Основная временная колонка для запроса. Отображает типы, представляющие время, но допускает пользовательские значения и функции.
Columns	Выбранные колонки. В это поле можно вводить произвольный SQL, чтобы использовать функции и алиасы колонок. Видно только в режиме Simple.
Aggregates	Список aggregate functions. Позволяет задавать пользовательские значения для функции и колонки. Видно только в режиме Aggregate.
Group By	Список выражений GROUP BY. Видно только в режиме Aggregate.
Order By	Список выражений ORDER BY.
Limit	Добавляет оператор LIMIT в конец запроса. Если установлено значение 0, то оператор будет исключён; это рекомендуется для некоторых наборов данных временных рядов, чтобы показать полную визуализацию.
Filters	Список фильтров, которые будут применены в предложении WHERE.

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

Traces

Тип запроса trace предоставляет конструктор запросов для удобного поиска и просмотра трассировок. Он предназначен для данных OpenTelemetry, но могут быть выбраны и другие колонки, чтобы отображать трассировки из иной схемы. Значения по умолчанию можно настроить в конфигурации трассировок источника данных, чтобы конструктор запросов предварительно загружался базой данных/таблицей и колонками по умолчанию. Если значения по умолчанию настроены, выбор колонок будет свернут по умолчанию. OpenTelemetry также может быть включён для автоматического выбора колонок в соответствии с версией схемы.

Фильтры по умолчанию добавляются с целью показывать только верхнеуровневые спаны. Также включён ORDER BY по колонкам Time и Duration Time. Эти фильтры привязаны к своим соответствующим полям и будут обновляться при изменении колонок. Фильтр Service Name по умолчанию исключён из SQL; изменение его значения с опции IS ANYTHING включит его.

Тип запроса trace поддерживает data links.

Field	Description
Trace Mode	Переключает запрос между режимами Trace Search и поиска по Trace ID.
Use OTel	Включает колонки OpenTelemetry. Перезапишет выбранные колонки, используя колонки, определённые выбранной версией схемы OTel (отключает выбор колонок).
Trace ID Column	Идентификатор трассировки (Trace ID).
Span ID Column	Идентификатор спана (Span ID).
Parent Span ID Column	Идентификатор родительского спана (Parent Span ID). Обычно пустой для верхнеуровневых трассировок.
Service Name Column	Имя сервиса.
Operation Name Column	Имя операции.
Start Time Column	Основная временная колонка для спана трассировки — время начала спана.
Duration Time Column	Длительность спана. По умолчанию Grafana ожидает, что это будет число с плавающей запятой в миллисекундах. Преобразование автоматически применяется через выпадающий список Duration Unit.
Duration Unit	Единица времени, используемая для длительности. По умолчанию — наносекунды. Выбранная единица будет преобразована в число с плавающей запятой в миллисекундах, как того требует Grafana.
Tags Column	Теги спана (Span Tags). Исключите это поле, если не используется схема на основе OTel, поскольку ожидается конкретный тип колонки Map.
Service Tags Column	Теги сервиса (Service Tags). Исключите это поле, если не используется схема на основе OTel, поскольку ожидается конкретный тип колонки Map.
Order By	Список выражений ORDER BY.
Limit	Добавляет оператор LIMIT в конец запроса. Если установлено значение 0, то оператор будет исключён, но это не рекомендуется для больших наборов данных трассировок.
Filters	Список фильтров, которые будут применены в предложении WHERE.
Trace ID	Trace ID для фильтрации. Используется только в режиме Trace ID и при открытии data link по Trace ID.

Этот тип запроса визуализирует данные в виде табличного представления в режиме Trace Search и в виде панели трассировок в режиме Trace ID.

SQL-редактор

Если запрос слишком сложен для конструктора запросов, вы можете использовать SQL-редактор. Он дает вам полный контроль над запросом, позволяя писать и выполнять чистый SQL ClickHouse.

SQL-редактор можно открыть, выбрав «SQL Editor» в верхней части редактора запросов.

Макрофункции по-прежнему можно использовать в этом режиме.

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

Ссылки на данные

Ссылки на данные в Grafana можно использовать для перехода к новым запросам. Эта функция реализована в плагине ClickHouse для связывания трассировки с логами и наоборот. Лучше всего она работает, когда OpenTelemetry настроен как для логов, так и для трассировок в конфигурации источника данных

Пример ссылок на трассировки в таблице

Пример ссылок на трассировки в логах

Как создать ссылку на данные

Вы можете создать ссылку на данные, выбрав в запросе столбец с именем traceID. Имя не чувствительно к регистру и поддерживает добавление символа подчёркивания перед ID. Например: traceId, TraceId, TRACE_ID и tracE_iD будут считаться допустимыми.

Если OpenTelemetry включён в запросе логов или трассировок, столбец с идентификатором трассировки будет добавлен автоматически.

При наличии столбца с идентификатором трассировки к данным будут прикреплены ссылки "View Trace" и "View Logs".

Возможности связывания

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

"View Trace" откроет разделённую панель с трассировкой, а "View Logs" откроет запрос логов, отфильтрованный по идентификатору трассировки. Если перейти по ссылке с дашборда, а не из режима Explore, она будет открыта в новой вкладке в режиме Explore.

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

Пример просмотра трассировки (правая панель) из запроса логов (левая панель)

Макросы

Макросы — это простой способ добавить динамический SQL в запрос. Перед тем как запрос будет отправлен на сервер ClickHouse, плагин развернёт макрос и заменит его на полное выражение.

Макросы могут использоваться в запросах и из SQL Editor, и из Query Builder.

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

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

Ниже приведён пример использования макроса $__timeFilter:

Вход:

SELECT log_time, log_message
FROM logs
WHERE $__timeFilter(log_time)

Итоговый результат запроса:

SELECT log_time, log_message
FROM logs
WHERE log_time >= toDateTime(1415792726) AND log_time <= toDateTime(1447328726)

В этом примере диапазон времени дашборда Grafana применяется к столбцу log_time.

Плагин также поддерживает запись с использованием фигурных скобок {}. Используйте её, когда необходимо использовать запросы внутри параметров.

Список макросов

Ниже приведён список всех макросов, доступных в плагине:

Macro	Description	Output example
$__dateFilter(columnName)	Заменяется фильтром по диапазону времени для указанного столбца с использованием диапазона времени панели Grafana в виде Date.	columnName >= toDate('2022-10-21') AND columnName <= toDate('2022-10-23')
$__timeFilter(columnName)	Заменяется фильтром по диапазону времени для указанного столбца с использованием диапазона времени панели Grafana в виде DateTime.	columnName >= toDateTime(1415792726) AND time <= toDateTime(1447328726)
$__timeFilter_ms(columnName)	Заменяется фильтром по диапазону времени для указанного столбца с использованием диапазона времени панели Grafana в виде DateTime64.	columnName >= fromUnixTimestamp64Milli(1415792726123) AND columnName <= fromUnixTimestamp64Milli(1447328726456)
$__dateTimeFilter(dateColumn, timeColumn)	Сокращение, объединяющее $__dateFilter() и $__timeFilter() при использовании раздельных столбцов Date и DateTime. Псевдоним — $__dt()	$__dateFilter(dateColumn) AND $__timeFilter(timeColumn)
$__fromTime	Заменяется начальным временем диапазона панели Grafana, приведённым к типу DateTime.	toDateTime(1415792726)
$__fromTime_ms	Заменяется начальным временем диапазона панели, приведённым к типу DateTime64.	fromUnixTimestamp64Milli(1415792726123)
$__toTime	Заменяется конечным временем диапазона панели Grafana, приведённым к типу DateTime.	toDateTime(1447328726)
$__toTime_ms	Заменяется конечным временем диапазона панели, приведённым к типу DateTime64.	fromUnixTimestamp64Milli(1447328726456)
$__timeInterval(columnName)	Заменяется функцией, вычисляющей интервал на основе размера окна в секундах.	toStartOfInterval(toDateTime(columnName), INTERVAL 20 second)
$__timeInterval_ms(columnName)	Заменяется функцией, вычисляющей интервал на основе размера окна в миллисекундах.	toStartOfInterval(toDateTime64(columnName, 3), INTERVAL 20 millisecond)
$__interval_s	Заменяется интервалом дашборда в секундах.	20
$__conditionalAll(condition, $templateVar)	Заменяется первым параметром, если переменная шаблона во втором параметре не выбирает все значения. Заменяется на 1=1, если переменная шаблона выбирает все значения.	condition или 1=1