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

Использование конструктора запросов в плагине Grafana для ClickHouse

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

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

Доступны следующие типы запросов:

• Таблица: самый простой тип запроса для отображения данных в табличном виде. Подходит как универсальный вариант и для простых, и для сложных запросов с агрегатными функциями.
• Журналы: оптимизирован для построения запросов к журналам. Лучше всего работает в представлении Explore с настроенными параметрами по умолчанию.
• Временные ряды: лучше всего подходит для построения запросов временных рядов. Позволяет выбрать отдельный временной столбец и добавлять агрегатные функции.
• Трассировки: оптимизирован для поиска и просмотра трассировок. Лучше всего работает в представлении Explore с настроенными параметрами по умолчанию.
• редактор SQL: редактор SQL можно использовать, если вам нужен полный контроль над запросом. В этом режиме можно выполнять любые SQL-запросы.

​

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

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

​

Таблица

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

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

Данные для этого типа запроса отображаются в виде таблицы.

​

Журнал

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

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

Тип запроса журнал поддерживает ссылки на данные.

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

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

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

​

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

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

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

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

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

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

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

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

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

​

Трассировки

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

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

Тип запроса Trace поддерживает ссылки на данные.

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

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

​

Редактор SQL

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

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

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

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

​

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

В 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. Если нажать ссылку на панели мониторинга, а не в разделе Explore, она откроется в новой вкладке раздела Explore.

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

Пример просмотра трассировки (справа) из запроса к журналам (слева)

​

Макросы

Макросы — это простой способ добавить в запрос динамический 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)	Заменяется на фильтр диапазона времени для указанного столбца с использованием временного диапазона панели Grafана в формате 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 or 1=1