Visualisations SQL

ClickStack prend en charge les visualisations basées sur des requêtes SQL écrites manuellement. Cela vous donne un contrôle total sur la logique de la requête, tout en restant intégré aux intervalles de temps, aux filtres et au rendu des graphiques au niveau du tableau de bord.

Les visualisations basées sur SQL sont utiles lorsque vous devez aller au-delà du Chart Explorer — par exemple, pour effectuer des jointures entre des tables ou créer des agrégations complexes qui ne sont pas prises en charge par le chart builder.

Pour créer une visualisation basée sur SQL, ouvrez l’éditeur d’une tuile de tableau de bord et sélectionnez l’onglet SQL.

À partir de là :

1. Sélectionnez une connexion ClickHouse sur laquelle exécuter la requête.
2. Sélectionnez éventuellement une Source — cela permet d’appliquer à votre visualisation des filtres au niveau du tableau de bord via la macro $__filters.
3. Rédigez votre requête SQL dans l’éditeur, en utilisant des paramètres de requête et des macros pour l’intégrer à l’intervalle de temps, aux filtres et aux variables du tableau de bord.
4. Cliquez sur le bouton play pour prévisualiser les résultats, puis sur Save.

Les paramètres de requête permettent à votre SQL de référencer l’intervalle de temps actuel du dashboard et sa granularité. Ils utilisent la syntaxe de requête paramétrée de ClickHouse : {paramName:Type}.

Les paramètres disponibles dépendent du type de graphique :

Graphiques en courbes et à barres empilées :

Graphiques de tableau, en secteurs et numériques :

Les macros sont des raccourcis qui se développent en expressions courantes de ClickHouse SQL. Elles sont préfixées par $__ et remplacées avant l’envoi de la requête à ClickHouse.

Ces macros renvoient une expression ClickHouse représentant l’heure de début ou de fin du dashboard. Elles ne prennent aucun argument.

Ces macros génèrent un fragment de clause WHERE qui filtre une colonne selon l’intervalle de temps du tableau de bord.

Exemple d’expansion de $__timeFilter(TimestampTime):

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

Ces macros regroupent une colonne d’horodatage en intervalles correspondant à la granularité du dashboard. Elles sont généralement utilisées dans les clauses SELECT et GROUP BY pour les graphiques de séries temporelles. Elles sont uniquement disponibles pour les visualisations Line et Stacked-bar.

Exemple d’expansion de $__timeInterval(TimestampTime):

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

Lorsqu’une Source est sélectionnée dans le graphique et que les filtres du tableau de bord sont actifs, $__filters se développe en conditions WHERE SQL correspondantes. Lorsqu’aucune source n’est sélectionnée ou qu’aucun filtre n’est appliqué, il se développe en (1=1) ; il peut donc toujours être inclus sans risque dans une clause WHERE.

Seuls les filtres pour lesquels la Condition de filtre de diffusion est activée sont appliqués par $__filters. Les filtres exposés en tant que variables sont référencés explicitement, comme décrit ci-dessous.

Lorsqu'un filtre de tableau de bord est disponible sous forme de variable, ses valeurs sélectionnées peuvent être référencées n'importe où dans la requête. Ces macros ne sont disponibles que dans les tuiles d'un tableau de bord déclarant au moins une variable.

Les valeurs d'une variable peuvent également être interpolées directement sous la forme $name ou ${name}, avec un format facultatif : ${name:sqlstring} (par défaut), ${name:csv} ou ${name:regex}. Dans le format par défaut, une référence directe renvoie NULL tant qu'aucune valeur n'est sélectionnée ; utilisez donc de préférence les macros ci-dessus partout où un prédicat est attendu.

ClickStack associe automatiquement les colonnes du résultat de la requête aux éléments du graphique en fonction des types de colonnes. Les règles de correspondance varient selon le type de graphique.

Toutes les colonnes de résultat sont affichées directement sous forme de colonnes de tableau.

Cette requête compte les événements de log par service, regroupés en intervalles de temps correspondant à la granularité du tableau de bord.

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) est utilisé comme horodatage pour l’axe des x.
• count (numérique) est représenté comme valeur de la série.
• ServiceName (chaîne) crée une ligne distincte pour chaque service.

La même requête, écrite avec des macros pour plus de concision :

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

Étant donné un tableau de bord comportant une variable service sur ServiceName et une variable severity sur SeverityText, cette requête limite le graphique à la sélection actuelle du service et exclut les niveaux de gravité sélectionnés. Les deux macros se développent en 1=1 lorsqu’aucune valeur n’est sélectionnée pour leur variable ; le graphique s’affiche donc sans filtre jusqu’à ce que l’utilisateur sélectionne une valeur.

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érique) détermine la taille de chaque secteur.
• ServiceName (chaîne) correspond à l’étiquette de chaque secteur.

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

L’unique valeur numérique total_errors de la première ligne est affichée.

• Les visualisations basées sur SQL s’exécutent en mode readonly — seules les requêtes SELECT sont autorisées.
• Les visualisations basées sur SQL doivent contenir exactement une requête SQL — les requêtes multiples ne sont pas prises en charge.
• L’éditeur SQL propose des suggestions d’autocomplétion pour les paramètres de requête comme pour les macros.
• Une source doit être sélectionnée pour appliquer les filtres du tableau de bord aux visualisations basées sur SQL. Pour un filtrage précis, la source doit correspondre à la table interrogée.
• Les variables de tableau de bord n’ont pas besoin de source — les valeurs proviennent des listes déroulantes de filtres du tableau de bord, et non de la source propre à la tuile.
• Les alertes sur une tuile SQL qui référence une variable de tableau de bord sont évaluées avec chaque variable dans son état vide, et non avec les valeurs sélectionnées sur le tableau de bord.