Visualizaciones basadas en SQL

Creación de visualizaciones con consultas SQL en ClickStack

ClickStack admite visualizaciones basadas en consultas SQL directas. Esto te da un control total sobre la lógica de la consulta, sin dejar de integrarse con los intervalos de tiempo, los filtros y la representación de gráficos a nivel de dashboard.

Las visualizaciones basadas en SQL son útiles cuando necesitas ir más allá del Chart Explorer integrado; por ejemplo, para hacer join entre tablas o crear agregaciones complejas que el chart builder no admite.

​

Creación de una visualización basada en SQL

Para crear una visualización basada en SQL, abra el editor de mosaicos de un dashboard y seleccione la pestaña SQL.

Desde allí:

1. Seleccione una conexión de ClickHouse en la que ejecutar la consulta.
2. De forma opcional, seleccione una Source; esto permite aplicar filtros del dashboard a su gráfico mediante la macro $__filters.
3. Escriba su consulta SQL en el editor, usando parámetros de consulta y macros para integrarla con el intervalo de tiempo y los filtros del dashboard.
4. Haga clic en el botón play para obtener una vista previa de los resultados y, a continuación, en Save.

​

Parámetros de consulta

Los parámetros de consulta permiten que su SQL haga referencia al intervalo de tiempo y a la granularidad actuales del dashboard. Utilizan la sintaxis de consultas parametrizadas de ClickHouse: {paramName:Type}.

​

Parámetros disponibles

Los parámetros disponibles dependen del tipo de gráfico:

Gráficos de líneas y barras apiladas:

Parámetro	Tipo	Descripción
{startDateMilliseconds:Int64}	Int64	Inicio del rango de fechas del dashboard (milisegundos desde la época Unix)
{endDateMilliseconds:Int64}	Int64	Fin del rango de fechas del dashboard (milisegundos desde la época Unix)
{intervalSeconds:Int64}	Int64	Tamaño del bucket de tiempo en segundos (según la granularidad)
{intervalMilliseconds:Int64}	Int64	Tamaño del bucket de tiempo en milisegundos (según la granularidad)

Gráficos de tabla, circular y numérico:

Parámetro	Tipo	Descripción
{startDateMilliseconds:Int64}	Int64	Inicio del rango de fechas del dashboard (milisegundos desde la época Unix)
{endDateMilliseconds:Int64}	Int64	Fin del rango de fechas del dashboard (milisegundos desde la época Unix)

​

Macros

Las macros son atajos que se expanden en expresiones habituales de ClickHouse SQL. Llevan el prefijo $__ y se sustituyen antes de enviar la consulta a ClickHouse.

​

Macros de límites temporales

Estas macros devuelven una expresión de ClickHouse que representa la hora de inicio o de fin del dashboard. No aceptan argumentos.

Macro	Se expande a	Tipo de columna
$__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 tiempo

Estas macros generan un fragmento de cláusula WHERE que filtra una columna según el intervalo de tiempo del dashboard.

Macro	Descripción
$__timeFilter(column)	Filtra una columna DateTime según el intervalo de tiempo del dashboard
$__timeFilter_ms(column)	Filtra una columna DateTime64 (milisegundos) según el intervalo de tiempo del dashboard
$__dateFilter(column)	Filtra una columna Date según el intervalo de tiempo del dashboard
$__dateTimeFilter(dateCol, timeCol)	Filtra usando columnas Date y DateTime separadas
$__dt(dateCol, timeCol)	Alias de $__dateTimeFilter

Ejemplo de expansión de $__timeFilter(TimestampTime):

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

​

Macros de intervalos de tiempo

Estas macros agrupan una columna de marca de tiempo en intervalos que coinciden con la granularidad del dashboard. Normalmente se usan en las cláusulas SELECT y GROUP BY para gráficos de series temporales. Solo están disponibles para las visualizaciones Line y Stacked-bar.

Macro	Descripción
$__timeInterval(column)	Agrupa una columna DateTime en intervalos de intervalSeconds
$__timeInterval_ms(column)	Agrupa una columna DateTime64 en intervalos de intervalMilliseconds

Ejemplo de expansión de $__timeInterval(TimestampTime):

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

​

Macro de filtro del dashboard

Macro	Descripción
$__filters	Se sustituye por las condiciones de filtro a nivel de dashboard (requiere que haya una Source seleccionada)

Cuando se selecciona una Source en el gráfico y los filtros del dashboard están activos, $__filters se expande a las condiciones WHERE de SQL correspondientes. Cuando no hay ninguna Source seleccionada o no se aplica ningún filtro, se expande a (1=1), por lo que siempre es seguro incluirlo en una cláusula WHERE.

​

Cómo se representan los resultados de la consulta

ClickStack asigna automáticamente las columnas del resultado a los elementos del gráfico en función de los tipos de columna. Las reglas de asignación varían según el tipo de gráfico.

​

Gráficos de líneas y de barras apiladas

Rol	Tipo de columna	Descripción
Timestamp	Primera columna Date o DateTime	Se utiliza como eje X.
Valor de la serie	Todas las columnas numéricas	Cada columna numérica se representa como una serie independiente. Suelen ser valores agregados.
Nombres de grupo	Columnas String, Map o Array	Opcional. Las filas con distintos valores de grupo se representan como series independientes.

​

Gráfico circular

Función	Tipo de columna	Descripción
Valor del sector	Primera columna numérica	Determina el tamaño de cada sector.
Etiqueta del sector	Columnas String, Map o Array	Opcional. Cada valor único pasa a ser una etiqueta de sector.

​

Gráfico numérico

Función	Tipo de columna	Descripción
Número	Primera columna numérica	Se muestra el valor de la primera fila de la primera columna numérica.

​

Gráfico de tabla

Todas las columnas del resultado se muestran directamente como columnas de la tabla.

​

Ejemplos

Acceso requerido a las tablas del sistema

Deberá especificar otel_v2.otel_logs o otel_v2.otel_traces si ejecuta los siguientes ejemplos en play-clickstack.clickhouse.com.

​

Gráfico de líneas — recuento de logs a lo largo del tiempo por servicio

Esta consulta cuenta los eventos de log por servicio, agrupándolos en intervalos de tiempo que se ajustan a la granularidad del 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) se usa como la marca de tiempo del eje X.
• count (numeric) se representa como el valor de la serie.
• ServiceName (cadena) crea una línea independiente para cada servicio.

​

Gráfico de líneas — uso de macros

La misma consulta, escrita con macros para mayor brevedad:

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 apiladas — recuento de errores por severidad

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 tabla — los 10 endpoints más 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 circular — distribución de solicitudes por servicio

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

• request_count (numérico) determina el tamaño de cada segmento.
• ServiceName (cadena) identifica cada segmento.

​

Gráfico numérico — recuento total de errores

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

Se muestra el valor numérico único total_errors de la primera fila.

​

Notas

• Las visualizaciones basadas en SQL se ejecutan con el modo readonly activado; solo se permiten consultas SELECT.
• Las visualizaciones basadas en SQL deben consistir en una única consulta SQL; no se admiten varias consultas.
• El editor SQL proporciona sugerencias de autocompletado tanto para los parámetros de consulta como para las macros.
• Se debe seleccionar un source para aplicar los filtros del dashboard a las visualizaciones basadas en SQL. El source debe coincidir con la tabla consultada para que el filtrado sea preciso.