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

ClickHouse Supported

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

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

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

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

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

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

Таблица

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

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

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

Логи

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

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

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

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

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

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

Временные ряды

Тип запроса «Временные ряды» похож на табличный, но с акцентом на данные временных рядов.

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

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

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

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

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

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

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

Трейсы

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

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

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

Поле	Описание
Trace Mode	Меняет тип запроса с Trace Search на поиск по Trace ID.
Use OTel	Включает столбцы OpenTelemetry. Перезаписывает выбранные столбцы, чтобы использовать столбцы, определённые выбранной версией схемы OTel (отключает выбор столбцов).
Trace ID Column	ID трейса.
Span ID Column	ID спана.
Parent Span ID Column	ID родительского спана. Обычно пустой для верхнеуровневых трейсов.
Service Name Column	Имя сервиса.
Operation Name Column	Имя операции.
Start Time Column	Основной временной столбец для спана трейса. Время начала спана.
Duration Time Column	Длительность спана. По умолчанию Grafana ожидает значение типа float в миллисекундах. Преобразование автоматически применяется через выпадающий список Duration Unit.
Duration Unit	Единица времени, используемая для длительности. По умолчанию наносекунды. Выбранная единица будет конвертирована во float в миллисекундах, как того требует Grafana.
Tags Column	Теги спана. Исключите это поле, если вы не используете схему, основанную на OTel, так как ожидается конкретный тип столбца Map.
Service Tags Column	Теги сервиса. Исключите это поле, если вы не используете схему, основанную на 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, столбец с идентификатором трассы (trace ID) будет добавлен автоматически.

При наличии столбца trace ID к данным будут добавлены ссылки «View Trace» и «View Logs».

Возможности переходов

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

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

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

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

Макросы

Макросы — это простой способ добавить динамический 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