Visualizaciones basadas en SQL

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.

Para crear una visualización basada en SQL, abra el editor de tile 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, los filtros y las variables del dashboard.
4. Haga clic en el botón play para obtener una vista previa de los resultados y, a continuación, en Save.

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

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

Gráficos de líneas y barras apiladas:

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

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.

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

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

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

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

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.

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

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

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.

$__filters solo aplica los filtros que tienen habilitada la condición de filtro de difusión. Los filtros expuestos como variables se referencian explícitamente, como se describe a continuación.

Cuando un filtro de dashboard está disponible como variable, se puede hacer referencia a los valores seleccionados en cualquier parte de la consulta. Estas macros solo están disponibles en los tiles que pertenecen a un dashboard que declara al menos una variable.

Los valores de una variable también se pueden interpolar directamente como $name o ${name}, con un formato opcional: ${name:sqlstring} (el predeterminado), ${name:csv} o ${name:regex}. En el formato predeterminado, una referencia directa se muestra como NULL antes de seleccionar cualquier valor, por lo que se recomienda usar las macros anteriores donde se espere un predicado.

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.

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

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.

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

Dado un dashboard con una variable service para ServiceName y una variable severity para SeverityText, esta consulta limita el gráfico a la selección actual del servicio y excluye las severidades seleccionadas. Ambas macros se expanden a 1=1 cuando su variable no tiene ninguna selección, por lo que el gráfico se muestra sin filtrar hasta que el Viewer selecciona un 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 el tamaño de cada segmento.
• ServiceName (cadena) identifica cada segmento.

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.

• 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.
• Las variables del dashboard no necesitan un source; los valores proceden de los menús desplegables de filtros del dashboard, no del source del propio tile.
• Las alertas en un tile SQL que hace referencia a una variable del dashboard se evalúan con todas las variables en su estado vacío, no con los valores seleccionados en el dashboard.