Конструктор запросов
Любой запрос можно выполнить с помощью плагина ClickHouse. Конструктор запросов является удобным вариантом для простых запросов, но для сложных запросов вам понадобится использовать SQL Editor.
Все запросы в конструкторе запросов имеют тип запроса и требуют выбора хотя бы одной колонки.
Доступные типы запросов:
- Table: самый простой тип запроса для отображения данных в табличном формате. Хорошо работает как универсальный вариант как для простых, так и для сложных запросов, содержащих агрегатные функции.
- Logs: оптимизирован для построения запросов к логам. Лучше всего работает в режиме исследования с предустановленными настройками.
- Time Series: лучше всего подходит для построения запросов временных рядов. Позволяет выбрать специальную временную колонку и добавлять агрегатные функции.
- Traces: оптимизирован для поиска/просмотра трасс. Лучше всего работает в режиме исследования с предустановленными настройками.
- SQL Editor: SQL редактор можно использовать, когда вам нужен полный контроль над запросом. В этом режиме можно выполнять любой SQL запрос.
Типы запросов
Настройка Тип запроса изменит макет конструктора запросов, чтобы соответствовать типу создаваемого запроса. Тип запроса также определяет, какая панель используется при визуализации данных.
Table
Самый гибкий тип запроса — это табличный запрос. Это универсальный вариант для других конструкторов запросов, предназначенный для обработки простых и агрегатных запросов.
| Поле | Описание |
|---|---|
| Builder Mode | Простые запросы исключают агрегаты и Group By, в то время как агрегатные запросы включают эти опции. |
| Columns | Выбранные колонки. В это поле можно ввести сырой SQL, чтобы позволить использовать функции и псевдонимы колонок. |
| Aggregates | Список агрегатных функций. Позволяет использовать пользовательские значения для функций и колонок. Видно только в режиме 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.
| Поле | Описание |
|---|---|
| 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 Series
Тип запроса временных рядов похож на таблицу, но с акцентом на данные временных рядов.
Обе формы в основном одинаковы, с этими примечательными отличиями:
- Специальное поле Time.
- В режиме Aggregate автоматически применяются макроинтервалы времени вместе с Group By для поля Time.
- В режиме Aggregate поле "Columns" скрыто.
- Автоматически добавляется фильтр диапазона времени и Order By для поля Time.
В некоторых случаях панель временных рядов может казаться обрезанной, потому что лимит по умолчанию равен 1000.
Попробуйте удалить предложение LIMIT, установив его на 0 (если ваш набор данных это позволяет).
| Поле | Описание |
|---|---|
| Builder Mode | Простые запросы исключают агрегаты и Group By, в то время как агрегатные запросы включают эти опции. |
| Time | Основная временная колонка для запроса. Отображает типы времени, но позволяет использовать произвольные значения/функции. |
| Columns | Выбранные колонки. В это поле можно ввести сырой SQL, чтобы позволить использовать функции и псевдонимы колонок. Видно только в простом режиме. |
| Aggregates | Список агрегатных функций. Позволяет использовать пользовательские значения для функций и колонок. Видно только в режиме Aggregate. |
| Group By | Список выражений GROUP BY. Видно только в режиме Aggregate. |
| Order By | Список выражений ORDER BY. |
| Limit | Добавляет оператор LIMIT в конец запроса. Если установлено значение 0, то он будет исключен, это рекомендуется для некоторых наборов данных временных рядов с целью получить полную визуализацию. |
| Filters | Список фильтров, которые будут применены в условии WHERE. |
Этот тип запроса отобразит данные с панелью временных рядов.
Traces
Тип запроса трасс предлагает конструктор запросов для простого поиска и просмотра трасс. Он предназначен для данных 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 ожидает, что это будет дробное число в миллисекундах. Автоматически применяется преобразование через выпадающее меню Duration Unit. |
| Duration Unit | Единица времени, используемая для продолжительности. Наносекунды по умолчанию. Выбранная единица будет преобразована в дробное число в миллисекундах, как того требует Grafana. |
| Tags Column | Теги спана. Исключите это, если не используете схему на основе OTel, так как ожидается определенный тип Map. |
| Service Tags Column | Теги службы. Исключите это, если не используете схему на основе OTel, так как ожидается определенный тип Map. |
| Order By | Список выражений ORDER BY. |
| Limit | Добавляет оператор LIMIT в конец запроса. Если установлено значение 0, то он будет исключен, но это не рекомендуется для больших наборов данных трасс. |
| Filters | Список фильтров, которые будут применены в условии WHERE. |
| Trace ID | ID трассы для фильтрации. Используется только в режиме Trace ID и при открытии data link для трассы. |
Этот тип запроса отобразит данные в представлении таблицы для режима Trace Search и в панели трасс для режима Trace ID.
SQL Editor
Для запросов, которые слишком сложны для конструктора запросов, вы можете использовать SQL Editor. Это предоставляет вам полный контроль над запросом, позволяя вам писать и выполнять обычный SQL ClickHouse.
SQL редактор можно открыть, выбрав "SQL Editor" в верхней части редактора запросов.
Макро функции всё ещё могут использоваться в этом режиме.
Вы можете переключаться между типами запросов, чтобы получить визуализацию, которая лучше всего соответствует вашему запросу. Это переключение также влияет даже в режиме панели инструментов, особенно с данными временных рядов.
Data Links
Grafana ссылки данных могут быть использованы для ссылки на новые запросы. Эта функция была включена в плагин ClickHouse для связывания трассы с логами и наоборот. Он лучше всего работает с настроенным OpenTelemetry как для логов, так и для трасс в конфигурации источника данных
Пример ссылок трасс в таблице
Пример ссылок трасс в логах
Как создать ссылку данных
Вы можете создать ссылку данных, выбрав колонку с именем traceID в своем запросе. Это имя нечувствительно к регистру и поддерживает добавление подчеркивания перед "ID". Например: traceId, TraceId, TRACE_ID и tracE_iD будут действительными.
Если OpenTelemetry включен в запросе логов или трасс, колонка с ID трассы будет добавлена автоматически.
Включив колонку с ID трассы, ссылки "View Trace" и "View Logs" будут прикреплены к данным.
Возможности связывания
С имеющимися ссылками данных вы можете открыть трассы и логи, используя предоставленный ID трассы.
"View Trace" откроет разделённую панель с трассой, а "View Logs" откроет запрос логов, отфильтрованный по ID трассы. Если ссылка нажата из панели инструментов, а не из режима исследования, ссылка будет открыта в новой вкладке в режиме исследования.
Для перехода между типами запросов (логи к трассам и трассы к логам) необходимо иметь предустановленные настройки как для логов, так и для трасс. Предустановленные настройки не требуются при открытии ссылки того же типа запроса, так как запрос может быть просто скопирован.
Пример просмотра трассы (правая панель) из запроса логов (левая панель)
Макросы
Макросы — это простой способ добавить динамический SQL к вашему запросу. Перед отправкой запроса на сервер ClickHouse плагин развернет макрос и заменит его полным выражением.
Запросы из как SQL редактора, так и конструктора запросов могут использовать макросы.
Использование макросов
Макросы могут быть включены в любой части запроса, многократно, если это необходимо.
Вот пример использования макроса $__timeFilter:
Вход:
Итоговый результат запроса:
В этом примере диапазон времени панели инструментов 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 |