Visualizações baseadas em SQL

O ClickStack oferece suporte a visualizações baseadas em consultas SQL puras. Isso dá a você controle total sobre a lógica da consulta, sem perder a integração com intervalos de tempo no nível do dashboard, filtros e renderização de gráficos.

As visualizações baseadas em SQL são úteis quando você precisa ir além do Chart Explorer integrado — por exemplo, para fazer JOIN entre tabelas ou criar agregações complexas que não são compatíveis com o construtor de gráficos.

Para criar uma visualização baseada em SQL, abra o editor de bloco do dashboard e selecione a aba SQL.

A partir daí:

1. Selecione uma conexão do ClickHouse para executar a consulta.
2. Opcionalmente, selecione uma Source — isso permite aplicar filtros no nível do dashboard ao seu gráfico por meio da macro $__filters.
3. Escreva sua consulta SQL no editor, usando parâmetros de consulta e macros para integrá-la ao intervalo de tempo, aos filtros e às variáveis do dashboard.
4. Clique no botão play para visualizar os resultados e depois em Save.

Parâmetros de consulta permitem que seu SQL faça referência ao intervalo de tempo e à granularidade atuais do dashboard. Eles usam a sintaxe de consultas parametrizadas do ClickHouse: {paramName:Type}.

Os parâmetros disponíveis dependem do tipo de gráfico:

Gráficos de Linha e Barra Empilhada:

Gráficos de Tabela, Pizza e Número:

Macros são atalhos que se expandem em expressões comuns do ClickHouse SQL. Elas são precedidas por $__ e substituídas antes de a consulta ser enviada ao ClickHouse.

Essas macros retornam uma expressão do ClickHouse que representa a hora de início ou de término do dashboard. Elas não recebem argumentos.

Essas macros geram um fragmento de cláusula WHERE que filtra uma coluna com base no intervalo de tempo do dashboard.

Exemplo de expansão de $__timeFilter(TimestampTime):

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

Essas macros agrupam uma coluna de timestamp em intervalos que correspondem à granularidade do dashboard. Elas geralmente são usadas nas cláusulas SELECT e GROUP BY para gráficos de séries temporais. Estão disponíveis apenas para visualizações de linha e de barras empilhadas.

Expansão de exemplo de $__timeInterval(TimestampTime):

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

Quando uma Source é selecionada no gráfico e os filtros do dashboard estão ativos, $__filters se expande para as condições SQL WHERE correspondentes. Quando nenhuma Source é selecionada ou nenhum filtro é aplicado, ele se expande para (1=1), portanto é sempre seguro incluí-lo em uma cláusula WHERE.

Somente os filtros com a Condição de filtro de transmissão ativada são aplicados por $__filters. Os filtros expostos como variáveis são referenciados explicitamente, conforme descrito abaixo.

Quando um filtro de dashboard está disponível como variável, é possível fazer referência aos valores selecionados em qualquer parte da consulta. Essas macros estão disponíveis apenas em blocos pertencentes a um dashboard que declara pelo menos uma variável.

Os valores de uma variável também podem ser interpolados diretamente como $name ou ${name}, com um formato opcional: ${name:sqlstring} (o padrão), ${name:csv} ou ${name:regex}. No formato padrão, uma referência direta é renderizada como NULL antes de qualquer seleção; portanto, prefira as macros acima sempre que for esperado um predicado.

O ClickStack mapeia automaticamente as colunas do resultado para elementos do gráfico com base nos tipos de coluna. As regras de mapeamento variam conforme o tipo de gráfico.

Todas as colunas do resultado são exibidas diretamente como colunas da tabela.

Esta consulta conta eventos de log por serviço, agrupando-os em intervalos de tempo de acordo com a granularidade do dashboard.

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) é usado como timestamp do eixo X.
• count (numérico) é exibido como o valor da série.
• ServiceName (string) cria uma linha separada para cada serviço.

A mesma consulta escrita com macros, para ficar mais concisa:

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

Em um dashboard com uma variável service em ServiceName e uma variável severity em SeverityText, esta consulta restringe o gráfico à seleção atual de serviço e exclui as severidades selecionadas. Ambas as macros são expandidas para 1=1 quando suas variáveis não têm nenhuma seleção; portanto, o gráfico é exibido sem filtros até que o visualizador escolha um valor.

SELECT
  $__timeInterval(TimestampTime) AS ts,
  count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND $__filter(ServiceName, $service)
  AND $__conditionalAll(SeverityText NOT IN ($severity), $severity)
GROUP BY 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

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 (numérico) determina o tamanho de cada segmento.
• ServiceName (string) identifica cada segmento.

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

O único valor numérico total_errors da primeira linha é exibido.

• As visualizações baseadas em SQL são executadas com o modo readonly ativado — somente consultas SELECT são permitidas.
• As visualizações baseadas em SQL devem conter exatamente uma única consulta SQL - várias consultas não são compatíveis.
• O editor SQL fornece sugestões de preenchimento automático tanto para parâmetros de consulta quanto para macros.
• É necessário selecionar uma source para aplicar os filtros do dashboard às visualizações baseadas em SQL. A source deve corresponder à tabela consultada, para garantir uma filtragem precisa.
• As variáveis do dashboard não exigem uma source — os valores vêm dos menus suspensos de filtro do dashboard, não da source do próprio bloco.
• Alertas em um bloco SQL que faz referência a uma variável do dashboard são avaliados com todas as variáveis em seu estado vazio, e não com os valores selecionados no dashboard.