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.

Criando uma visualização baseada em SQL

Para criar uma visualização baseada em SQL, abra o editor de tile do dashboard e selecione a aba SQL. A partir daí:

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

Parâmetros de consulta

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}.

Parâmetros disponíveis

Os parâmetros disponíveis dependem do tipo de gráfico: Gráficos de Linha e Barra Empilhada:

Parâmetro	Tipo	Descrição
`{startDateMilliseconds:Int64}`	Int64	Início do intervalo de datas do dashboard (milissegundos desde epoch)
`{endDateMilliseconds:Int64}`	Int64	Fim do intervalo de datas do dashboard (milissegundos desde epoch)
`{intervalSeconds:Int64}`	Int64	Tamanho do bucket de tempo em segundos (com base na granularidade)
`{intervalMilliseconds:Int64}`	Int64	Tamanho do bucket de tempo em milissegundos (com base na granularidade)

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

Parâmetro	Tipo	Descrição
`{startDateMilliseconds:Int64}`	Int64	Início do intervalo de datas do dashboard (milissegundos desde epoch)
`{endDateMilliseconds:Int64}`	Int64	Fim do intervalo de datas do dashboard (milissegundos desde epoch)

Macros

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.

Macros de limite de tempo

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.

Macro	Expande para	Tipo da coluna
`$__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

Macros de filtro de tempo

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

Macro	Description
`$__timeFilter(column)`	Filtra uma coluna `DateTime` com base no intervalo do dashboard
`$__timeFilter_ms(column)`	Filtra uma coluna `DateTime64` (milissegundos) com base no intervalo do dashboard
`$__dateFilter(column)`	Filtra uma coluna `Date` com base no intervalo do dashboard
`$__dateTimeFilter(dateCol, timeCol)`	Filtra usando colunas `Date` e `DateTime` separadas
`$__dt(dateCol, timeCol)`	Alias de `$__dateTimeFilter`

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

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

Macros de intervalo de tempo

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.

Macro	Descrição
`$__timeInterval(column)`	Agrupa uma coluna `DateTime` em intervalos de `intervalSeconds`
`$__timeInterval_ms(column)`	Agrupa uma coluna `DateTime64` em intervalos de `intervalMilliseconds`

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

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

Macro de filtro do dashboard

Macro	Descrição
`$__filters`	Substituído pelas condições de filtro no nível do dashboard (requer que uma Source esteja selecionada)

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.

Como os resultados da consulta são exibidos nos gráficos

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.

Gráficos de linha e de barras empilhadas

Papel	Tipo de coluna	Descrição
Timestamp	Primeira coluna `Date` ou `DateTime`	Usada como eixo x.
Valor da série	Todas as colunas numéricas	Cada coluna numérica é plotada como uma série separada. Normalmente, são valores agregados.
Nomes de grupo	Colunas String, Map ou Array	Opcional. Linhas com valores de grupo diferentes são plotadas como séries separadas.

Gráfico de pizza

Função	Tipo de coluna	Descrição
Valor da fatia	Primeira coluna numérica	Determina o tamanho de cada fatia.
Rótulo da fatia	colunas String, map ou Array	Opcional. Cada valor distinto se torna o rótulo de uma fatia.

Gráfico numérico

Função	Tipo de coluna	Descrição
Número	Primeira coluna numérica	É exibido o valor da primeira linha da primeira coluna numérica.

Tabela

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

Exemplos

Acesso obrigatório à tabela do sistemaVocê precisará especificar otel_v2.otel_logs ou otel_v2.otel_traces se executar os exemplos a seguir em play-clickstack.clickhouse.com.

Gráfico de linhas — contagem de logs ao longo do tempo por serviço

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.

Gráfico de linhas — usando macros

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

Gráfico de barras empilhadas — contagem de erros por nível de severidade

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

Gráfico de tabela — 10 endpoints mais lentos

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

gráfico de pizza — distribuição de solicitações por serviço

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.

Gráfico numérico — contagem total de erros

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.

Observações

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.

Features

Guides

Criando uma visualização baseada em SQL

Parâmetros de consulta

Parâmetros disponíveis

Macros

Macros de limite de tempo

Macros de filtro de tempo

Macros de intervalo de tempo

Macro de filtro do dashboard

Como os resultados da consulta são exibidos nos gráficos

Gráficos de linha e de barras empilhadas

Gráfico de pizza

Gráfico numérico

Tabela

Exemplos

Gráfico de linhas — contagem de logs ao longo do tempo por serviço

Gráfico de linhas — usando macros

Gráfico de barras empilhadas — contagem de erros por nível de severidade

Gráfico de tabela — 10 endpoints mais lentos

gráfico de pizza — distribuição de solicitações por serviço

Gráfico numérico — contagem total de erros

Observações

​Criando uma visualização baseada em SQL

​Parâmetros de consulta

​Parâmetros disponíveis

​Macros

​Macros de limite de tempo

​Macros de filtro de tempo

​Macros de intervalo de tempo

​Macro de filtro do dashboard

​Como os resultados da consulta são exibidos nos gráficos

​Gráficos de linha e de barras empilhadas

​Gráfico de pizza

​Gráfico numérico

​Tabela

​Exemplos

​Gráfico de linhas — contagem de logs ao longo do tempo por serviço

​Gráfico de linhas — usando macros

​Gráfico de barras empilhadas — contagem de erros por nível de severidade

​Gráfico de tabela — 10 endpoints mais lentos

​gráfico de pizza — distribuição de solicitações por serviço

​Gráfico numérico — contagem total de erros

​Observações

Criando uma visualização baseada em SQL

Parâmetros de consulta

Parâmetros disponíveis

Macros

Macros de limite de tempo

Macros de filtro de tempo

Macros de intervalo de tempo

Macro de filtro do dashboard

Como os resultados da consulta são exibidos nos gráficos

Gráficos de linha e de barras empilhadas

Gráfico de pizza

Gráfico numérico

Tabela

Exemplos

Gráfico de linhas — contagem de logs ao longo do tempo por serviço

Gráfico de linhas — usando macros

Gráfico de barras empilhadas — contagem de erros por nível de severidade

Gráfico de tabela — 10 endpoints mais lentos

gráfico de pizza — distribuição de solicitações por serviço

Gráfico numérico — contagem total de erros

Observações