Визуализации на основе SQL

ClickStack поддерживает визуализации на основе SQL-запросов в исходном виде. Это дает полный контроль над логикой запроса, сохраняя интеграцию с временными диапазонами на уровне панели мониторинга, фильтрами и отрисовкой диаграмм. Визуализации на основе SQL полезны, когда нужно выйти за рамки встроенного Chart Explorer — например, чтобы объединять таблицы с помощью JOIN или строить сложные агрегации, которые не поддерживаются chart builder.

Создание визуализации на основе SQL

Чтобы создать визуализацию на основе SQL, откройте редактор плитки панели мониторинга и выберите вкладку SQL. Далее:

Выберите подключение к ClickHouse, для которого будет выполняться запрос.
При необходимости выберите Source — это позволит применять к вашей визуализации фильтры уровня панели мониторинга через макрос $__filters.
Напишите SQL-запрос в редакторе, используя параметры запроса и макросы для интеграции с временным диапазоном и фильтрами панели мониторинга.
Нажмите кнопку play, чтобы просмотреть результат, затем нажмите Save.

Параметры запроса

Параметры запроса позволяют использовать в SQL текущий временной диапазон и уровень детализации панели мониторинга. Для этого применяется синтаксис параметризованных запросов ClickHouse: {paramName:Type}.

Доступные параметры

Доступные параметры зависят от типа диаграммы: Диаграммы Line и столбчатые диаграммы с накоплением:

Параметр	Тип	Описание
`{startDateMilliseconds:Int64}`	Int64	Начало диапазона дат панели мониторинга (миллисекунды с начала эпохи Unix)
`{endDateMilliseconds:Int64}`	Int64	Конец диапазона дат панели мониторинга (миллисекунды с начала эпохи Unix)
`{intervalSeconds:Int64}`	Int64	Размер временного интервала в секундах (в зависимости от гранулярности)
`{intervalMilliseconds:Int64}`	Int64	Размер временного интервала в миллисекундах (в зависимости от гранулярности)

Диаграммы Table, Pie и Number:

Параметр	Тип	Описание
`{startDateMilliseconds:Int64}`	Int64	Начало диапазона дат панели мониторинга (миллисекунды с начала эпохи Unix)
`{endDateMilliseconds:Int64}`	Int64	Конец диапазона дат панели мониторинга (миллисекунды с начала эпохи Unix)

Макросы

Макросы — это сокращённые конструкции, которые разворачиваются в типовые выражения ClickHouse SQL. Они начинаются с префикса $__ и заменяются до отправки запроса в ClickHouse.

Макросы временных границ

Эти макросы возвращают выражение ClickHouse, соответствующее времени начала или окончания панели мониторинга. Они не принимают аргументов.

Макрос	Раскрывается в	Тип столбца
`$__fromTime`	`toDateTime(fromUnixTimestamp64Milli({startDateMilliseconds:Int64}))`	DateTime
`$__toTime`	`toDateTime(fromUnixTimestamp64Milli({endDateMilliseconds:Int64}))`	DateTime
`$__fromTime_ms`	`fromUnixTimestamp64Milli({startDateMilliseconds:Int64})`	DateTime64
`$__toTime_ms`	`fromUnixTimestamp64Milli({endDateMilliseconds:Int64})`	DateTime64
`$__interval_s`	`{intervalSeconds:Int64}`	Int64

Макросы фильтрации по времени

Эти макросы создают фрагмент условия WHERE, который фильтрует столбец по временному диапазону панели мониторинга.

Макрос	Описание
`$__timeFilter(column)`	Фильтрует столбец `DateTime` по временному диапазону панели мониторинга
`$__timeFilter_ms(column)`	Фильтрует столбец `DateTime64` (миллисекунды) по временному диапазону панели мониторинга
`$__dateFilter(column)`	Фильтрует столбец `Date` по временному диапазону панели мониторинга
`$__dateTimeFilter(dateCol, timeCol)`	Фильтрует с использованием отдельных столбцов `Date` и `DateTime`
`$__dt(dateCol, timeCol)`	Псевдоним для `$__dateTimeFilter`

Пример развёртывания $__timeFilter(TimestampTime):

TimestampTime >= toDateTime(fromUnixTimestamp64Milli({startDateMilliseconds:Int64}))
AND TimestampTime <= toDateTime(fromUnixTimestamp64Milli({endDateMilliseconds:Int64}))

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

Эти макросы группируют столбец с временной меткой по интервалам, соответствующим детализации панели мониторинга. Обычно они используются в секциях SELECT и GROUP BY для графиков временных рядов. Они доступны только для визуализаций Line и столбчатых диаграмм с накоплением.

Macro	Description
`$__timeInterval(column)`	Группирует столбец `DateTime` по интервалам `intervalSeconds`
`$__timeInterval_ms(column)`	Группирует столбец `DateTime64` по интервалам `intervalMilliseconds`

Пример развёртывания $__timeInterval(TimestampTime):

toStartOfInterval(toDateTime(TimestampTime), INTERVAL {intervalSeconds:Int64} second)

Макрос фильтра панели мониторинга

Macro	Описание
`$__filters`	Подставляет условия фильтрации на уровне панели мониторинга (требуется выбрать Source)

Когда на графике выбран Source и включены фильтры панели мониторинга, $__filters разворачивается в соответствующие условия SQL WHERE. Если источник не выбран или фильтры не заданы, он разворачивается в (1=1), поэтому его всегда можно безопасно включать в условие WHERE.

Как результаты запроса отображаются на диаграмме

ClickStack автоматически сопоставляет столбцы результатов с элементами диаграммы в зависимости от типов столбцов. Правила сопоставления зависят от типа диаграммы.

Линейные диаграммы и столбчатые диаграммы с накоплением

Роль	Тип столбца	Описание
Временная метка	Первый столбец `Date` или `DateTime`	Используется как ось X.
Значение серии	Все числовые столбцы	Каждый числовой столбец отображается как отдельная серия. Обычно это агрегированные значения.
Названия групп	Столбцы String, Map или Array	Необязательно. Строки с разными значениями групп отображаются как отдельные серии.

Круговая диаграмма

Роль	Тип столбца	Описание
Значение сектора	Первый числовой столбец	Определяет размер каждого сектора.
Метка сектора	Столбцы типа String, Map или Array	Необязательно. Каждое уникальное значение становится меткой сектора.

Числовая диаграмма

Роль	Тип столбца	Описание
Число	Первый числовой столбец	Отображается значение из первой строки первого числового столбца.

Табличная диаграмма

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

Примеры

Требуется доступ к системной таблицеЕсли вы запускаете следующие примеры на play-clickstack.clickhouse.com, необходимо указать otel_v2.otel_logs или otel_v2.otel_traces.

Линейная диаграмма — количество логов по сервисам во времени

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

SELECT
  toStartOfInterval(TimestampTime, INTERVAL {intervalSeconds:Int64} second) AS ts,
  ServiceName,
  count() AS count
FROM otel_logs
WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
  AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
  AND $__filters
GROUP BY ServiceName, ts
ORDER BY ts ASC

ts (DateTime) используется как временная метка на оси X.
count (числовое значение) отображается как значение серии.
ServiceName (строка) создает отдельную линию для каждого сервиса.

Линейная диаграмма — с использованием макросов

Тот же запрос с использованием макросов для краткости:

SELECT
  $__timeInterval(TimestampTime) AS ts,
  ServiceName,
  count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND $__filters
GROUP BY ServiceName, ts
ORDER BY ts ASC

Столбчатая диаграмма с накоплением — количество ошибок по уровням серьёзности

SELECT
  $__timeInterval(TimestampTime) AS ts,
  lower(SeverityText),
  count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND lower(SeverityText) IN ('error', 'warn')
  AND $__filters
GROUP BY SeverityText, ts
ORDER BY ts ASC

Табличная диаграмма — 10 конечных точек с наибольшей задержкой

SELECT
  SpanName AS endpoint,
  avg(Duration) / 1000 AS avg_duration_ms,
  count() AS request_count
FROM otel_traces
WHERE $__timeFilter(Timestamp)
  AND $__filters
GROUP BY SpanName
ORDER BY avg_duration_ms DESC
LIMIT 10

Круговая диаграмма — распределение запросов по сервисам

SELECT
  ServiceName,
  count() AS request_count
FROM otel_traces
WHERE $__timeFilter(Timestamp)
  AND $__filters
GROUP BY ServiceName

request_count (числовое значение) определяет размер каждого сегмента.
ServiceName (строка) задает метку каждого сегмента.

Числовая диаграмма — общее число ошибок

SELECT
  count() AS total_errors
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND SeverityText = 'error'
  AND $__filters

Отображается числовое значение total_errors из первой строки.

Примечания

Визуализации на основе SQL выполняются во включенном режиме readonly — разрешены только запросы SELECT.
Визуализации на основе SQL должны содержать ровно один SQL-запрос — несколько запросов не поддерживаются.
Редактор SQL предлагает автодополнение как для параметров запроса, так и для макросов.
Чтобы фильтры панели мониторинга применялись к визуализациям на основе SQL, необходимо выбрать Source. Для корректной фильтрации Source должен соответствовать таблице, к которой обращается запрос.

Последнее изменение 2 июля 2026 г.

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

​Создание визуализации на основе SQL

​Параметры запроса

​Доступные параметры

​Макросы

​Макросы временных границ

​Макросы фильтрации по времени

​Макросы временных интервалов

​Макрос фильтра панели мониторинга

​Как результаты запроса отображаются на диаграмме

​Линейные диаграммы и столбчатые диаграммы с накоплением

​Круговая диаграмма

​Числовая диаграмма

​Табличная диаграмма

​Примеры

​Линейная диаграмма — количество логов по сервисам во времени

​Линейная диаграмма — с использованием макросов

​Столбчатая диаграмма с накоплением — количество ошибок по уровням серьёзности

​Табличная диаграмма — 10 конечных точек с наибольшей задержкой

​Круговая диаграмма — распределение запросов по сервисам

​Числовая диаграмма — общее число ошибок

​Примечания

Создание визуализации на основе SQL

Параметры запроса

Доступные параметры

Макросы

Макросы временных границ

Макросы фильтрации по времени

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

Макрос фильтра панели мониторинга

Как результаты запроса отображаются на диаграмме

Линейные диаграммы и столбчатые диаграммы с накоплением

Круговая диаграмма

Числовая диаграмма

Табличная диаграмма

Примеры

Линейная диаграмма — количество логов по сервисам во времени

Линейная диаграмма — с использованием макросов

Столбчатая диаграмма с накоплением — количество ошибок по уровням серьёзности

Табличная диаграмма — 10 конечных точек с наибольшей задержкой

Круговая диаграмма — распределение запросов по сервисам

Числовая диаграмма — общее число ошибок

Примечания