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

ClickHouse Supported

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

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

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

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

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

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

Table

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

Поле	Описание
Режим конструктора	Простые запросы исключают агрегаты и Group By, в то время как агрегатные запросы включают эти параметры.
Колонки	Выбранные колонки. В это поле можно ввести чистый SQL для возможности работы с функциями и псевдонимами колонок.
Агрегаты	Список агрегатных функций. Позволяет устанавливать пользовательские значения для функции и колонки. Видимо только в агрегатном режиме.
Group By	Список выражений GROUP BY. Видимо только в агрегатном режиме.
Order By	Список выражений ORDER BY.
Limit	Добавляет оператор LIMIT в конец запроса. Если установлено значение 0, оно будет исключено. Некоторые визуализации могут требовать, чтобы это значение было установлено на 0, чтобы отобразить все данные.
Фильтры	Список фильтров, применяемых в условии WHERE.

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

Logs

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

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

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

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

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

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

Time series

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

Оба представления в основном одинаковы, но с этими заметными отличиями:

• Специальное поле Time.
• В агрегатном режиме автоматически применяется макрос временного интервала вместе с Group By для поля Time.
• В агрегатном режиме поле "Columns" скрыто.
• Автоматически добавляется фильтр временного диапазона и Order By для поля Time.

Пропущены данные в вашей визуализации?

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

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

Поле	Описание
Режим конструктора	Простые запросы исключают агрегаты и Group By, в то время как агрегатные запросы включают эти параметры.
Время	Основная временная колонка для запроса. Будет отображать типы, похожие на время, но допускает пользовательские значения/функции.
Колонки	Выбранные колонки. В это поле можно ввести чистый SQL для возможности работы с функциями и псевдонимами колонок. Видимо только в простом режиме.
Агрегаты	Список агрегатных функций. Позволяет устанавливать пользовательские значения для функции и колонки. Видимо только в агрегатном режиме.
Group By	Список выражений GROUP BY. Видимо только в агрегатном режиме.
Order By	Список выражений ORDER BY.
Limit	Добавляет оператор LIMIT в конец запроса. Если установлено значение 0, оно будет исключено, это рекомендуется для некоторых наборов данных временных рядов, чтобы показать всю визуализацию.
Фильтры	Список фильтров, применяемых в условии WHERE.

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

Traces

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

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

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

Поле	Описание
Режим трасс	Изменяет запрос с поиска трасс на поиск по Trace ID.
Использовать 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 ожидает, что это будет число с плавающей запятой в миллисекундах. Автоматически применяется преобразование через выпадающий список Duration Unit.
Duration Unit	Единица времени, используемая для продолжительности. Наносекунды по умолчанию. Выбранная единица будет преобразована в формат с плавающей запятой в миллисекундах, как требует Grafana.
Tags Column	Теги спана. Исключите это, если не используете схему на основе OTel, так как она ожидает конкретный тип колонок Map.
Service Tags Column	Теги сервиса. Исключите это, если не используете схему на основе OTel, так как она ожидает конкретный тип колонок Map.
Order By	Список выражений ORDER BY.
Limit	Добавляет оператор LIMIT в конец запроса. Если установлено значение 0, оно будет исключено, но это не рекомендуется для больших наборов данных трасс.
Фильтры	Список фильтров, применяемых в условии WHERE.
Trace ID	Trace ID для фильтрации. Используется только в режиме Trace ID, а также при открытии data link по Trace ID.

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

SQL редактор

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

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

Macro functions все еще могут быть использованы в этом режиме.

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

Data links

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

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

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

Как сделать data link

Вы можете создать data link, выбрав колонку с именем traceID в вашем запросе. Это название не чувствительно к регистру и поддерживает добавление подчеркивания перед "ID". Например: traceId, TraceId, TRACE_ID и tracE_iD будут действительными.

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

При включении колонки Trace ID ссылки "Посмотреть трассу" и "Посмотреть логи" будут привязаны к данным.

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

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

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

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

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

Макросы

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

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

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

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

Вот пример использования макроса $__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.

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

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

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

Макрос	Описание	Пример выхода
$__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