Constructeur de requêtes

Utilisation du constructeur de requêtes dans le plugin Grafana de ClickHouse

N’importe quelle requête peut être exécutée avec le plugin ClickHouse. Le query builder est une option pratique pour les requêtes simples, mais pour les requêtes plus complexes, vous devrez utiliser le SQL Editor.

Toutes les requêtes du query builder ont un type de requête et nécessitent la sélection d’au moins une colonne.

Les types de requête disponibles sont les suivants :

• Table : le type de requête le plus simple pour afficher les données sous forme de tableau. Il convient aussi bien aux requêtes simples qu’aux requêtes complexes contenant des fonctions d’agrégation.
• Logs : optimisé pour créer des requêtes sur les logs. Fonctionne le mieux dans la vue Explore avec les valeurs par défaut configurées.
• Time Series : particulièrement adapté à la création de requêtes de séries temporelles. Permet de sélectionner une colonne de temps dédiée et d’ajouter des fonctions d’agrégation.
• Traces : optimisé pour rechercher et afficher les traces. Fonctionne le mieux dans la vue Explore avec les valeurs par défaut configurées.
• SQL Editor : le SQL Editor peut être utilisé lorsque vous souhaitez garder un contrôle total sur la requête. Dans ce mode, toute requête SQL peut être exécutée.

​

Types de requête

Le paramètre Type de requête modifie la disposition du générateur de requêtes afin qu’elle corresponde au type de requête en cours de création. Le type de requête détermine également le panneau utilisé pour visualiser les données.

​

Tableau

Le type de requête le plus flexible est la requête de type tableau. Il s’agit d’une option générique qui regroupe les autres constructeurs de requêtes conçus pour gérer les requêtes simples et les requêtes d’agrégation.

Champ	Description
Builder Mode	Les requêtes simples n’incluent pas Aggregates ni Group By, tandis que les requêtes d’agrégation incluent ces options.
Columns	Les colonnes sélectionnées. Vous pouvez saisir du Raw SQL dans ce champ pour utiliser des fonctions et définir des alias de colonnes.
Aggregates	Une liste de aggregate functions. Permet de définir des valeurs personnalisées pour la fonction et la colonne. Visible uniquement en mode Aggregate.
Group By	Une liste d’expressions GROUP BY. Visible uniquement en mode Aggregate.
Order By	Une liste d’expressions ORDER BY.
Limit	Ajoute une instruction LIMIT à la fin de la requête. Si cette valeur est définie sur 0, elle est exclue. Certaines visualizations peuvent nécessiter que cette valeur soit définie sur 0 pour afficher toutes les données.
Filters	Une liste de filtres à appliquer dans la clause WHERE.

Ce type de requête affiche les données sous forme de tableau.

​

Journaux

Le type de requête logs propose un query builder axé sur l’interrogation des données de logs. Des valeurs par défaut peuvent être configurées dans la configuration des logs de la source de données afin de précharger le query builder avec une base de données/table et des colonnes par défaut. OpenTelemetry peut également être activé pour sélectionner automatiquement les colonnes en fonction d’une version de schéma.

Les filtres Time et Level sont ajoutés par défaut, ainsi qu’un Order By sur la colonne Time. Ces filtres sont liés à leurs champs respectifs et se mettront à jour lorsque les colonnes seront modifiées. Le filtre Level est exclu du SQL par défaut ; il est activé dès que vous remplacez l’option IS ANYTHING.

Le type de requête logs prend en charge les liens de données.

Champ	Description
Use OTel	Active les colonnes OpenTelemetry. Remplace les colonnes sélectionnées par celles définies par la version du schéma OTel choisie (désactive la sélection de colonnes).
Colonnes	Colonnes supplémentaires à ajouter aux lignes de log. Vous pouvez saisir du Raw SQL dans ce champ pour utiliser des fonctions et le column aliasing.
Time	Colonne timestamp principale du log. Affiche les types temporels, mais permet aussi des valeurs/fonctions personnalisées.
Niveau de log	Facultatif. Le niveau ou la sévérité du log. Les valeurs ressemblent généralement à INFO, error, Debug, etc.
Message	Contenu du message de log.
Order By	Une liste d’expressions ORDER BY.
Limite	Ajoute une instruction LIMIT à la fin de la requête. Si elle est définie sur 0, elle sera exclue, mais cela n’est pas recommandé pour les grands jeux de données de logs.
Filtres	Une liste de filtres à appliquer dans la clause WHERE.
Filtre de message	Champ de saisie permettant de filtrer facilement les logs avec un LIKE %value%. Exclu lorsque le champ est vide.

Ce type de requête affiche les données dans le panneau de logs, avec un panneau d’histogramme des logs en haut.

Les colonnes supplémentaires sélectionnées dans la requête peuvent être consultées dans la ligne de log développée :

​

Séries temporelles

Le type de requête de séries temporelles est similaire à table, mais se concentre sur les données de séries temporelles.

Les deux vues sont globalement identiques, avec toutefois les différences notables suivantes :

• Un champ Time dédié.
• En Aggregate mode, une macro d’intervalle de temps est automatiquement appliquée, avec un Group By sur le champ Time.
• En Aggregate mode, le champ “Columns” est masqué.
• Un filtre sur l’intervalle de temps et un Order By sont automatiquement ajoutés pour le champ Time.

Des données manquent dans votre visualisation ?

Dans certains cas, le panneau de séries temporelles peut sembler tronqué, car la limite par défaut est de 1000.

Essayez de supprimer la clause LIMIT en la définissant sur 0 (si votre jeu de données le permet).

Field	Description
Builder Mode	Les requêtes simples excluent Aggregates et Group By, tandis que les requêtes d’agrégation incluent ces options.
Time	La colonne temporelle principale de la requête. Affiche les types apparentés au temps, mais autorise également des valeurs/fonctions personnalisées.
Columns	Les colonnes sélectionnées. Il est possible de saisir du Raw SQL dans ce champ pour utiliser des fonctions et le column aliasing. Visible uniquement en Simple mode.
Aggregates	Une liste de aggregate functions. Permet de définir des valeurs personnalisées pour la fonction et la colonne. Visible uniquement en Aggregate mode.
Group By	Une liste d’expressions GROUP BY. Visible uniquement en Aggregate mode.
Order By	Une liste d’expressions ORDER BY.
Limit	Ajoute une instruction LIMIT à la fin de la requête. S’il est défini sur 0, il est exclu ; cela est recommandé pour certains jeux de données de séries temporelles afin d’afficher la visualisation complète.
Filters	Une liste de filtres à appliquer dans la clause WHERE.

Ce type de requête affichera les données dans le panneau de séries temporelles.

​

Traces

Le type de requête de trace propose un générateur de requêtes pour rechercher et afficher facilement des traces. Il est conçu pour les données OpenTelemetry, mais il est possible de sélectionner des colonnes pour afficher des traces à partir d’un autre schéma. Des valeurs par défaut peuvent être configurées dans la configuration des traces de la source de données afin de précharger le générateur de requêtes avec une base de données/table et des colonnes par défaut. Si des valeurs par défaut sont configurées, la sélection des colonnes sera réduite par défaut. OpenTelemetry peut également être activé pour sélectionner automatiquement les colonnes en fonction d’une version de schéma.

Des filtres par défaut sont ajoutés afin de n’afficher que les spans de premier niveau. Un ORDER BY sur les colonnes Time et Duration Time est également inclus. Ces filtres sont associés à leurs champs respectifs et se mettront à jour lorsque les colonnes seront modifiées. Le filtre Service Name est exclu du SQL par défaut ; le modifier depuis l’option IS ANYTHING l’activera.

Le type de requête de trace prend en charge les liens de données.

Champ	Description
Trace Mode	Fait passer la requête de Trace Search à la recherche par Trace ID.
Use OTel	Active les colonnes OpenTelemetry. Remplace les colonnes sélectionnées pour utiliser celles définies par la version de schéma OTel choisie (désactive la sélection de colonnes).
Trace ID Column	L’ID de la trace.
Span ID Column	L’ID du span.
Parent Span ID Column	L’ID du span parent. Ce champ est généralement vide pour les traces de premier niveau.
Service Name Column	Le nom du service.
Operation Name Column	Le nom de l’opération.
Start Time Column	La colonne temporelle principale du trace span. L’heure à laquelle le span a commencé.
Duration Time Column	La durée du span. Par défaut, Grafana attend ici un float en millisecondes. Une conversion est automatiquement appliquée via la liste déroulante Duration Unit.
Duration Unit	L’unité de temps utilisée pour la durée. Nanosecondes par défaut. L’unité sélectionnée sera convertie en float en millisecondes, comme l’exige Grafana.
Tags Column	Les tags du span. Excluez cette colonne si vous n’utilisez pas un schéma basé sur OTel, car un type de colonne Map spécifique est attendu.
Service Tags Column	Les tags du service. Excluez cette colonne si vous n’utilisez pas un schéma basé sur OTel, car un type de colonne Map spécifique est attendu.
Order By	Une liste d’expressions ORDER BY.
Limit	Ajoute une instruction LIMIT à la fin de la requête. Si la valeur est définie sur 0, elle sera exclue, mais cela n’est pas recommandé pour les grands jeux de données de traces.
Filters	Une liste de filtres à appliquer dans la clause WHERE.
Trace ID	L’ID de trace sur lequel filtrer. Utilisé uniquement en mode Trace ID et lors de l’ouverture d’un lien de données de type Trace ID.

Ce type de requête affichera les données dans la vue tableau pour le mode Trace Search, et dans le panneau de traces pour le mode Trace ID.

​

SQL Editor

Pour les requêtes trop complexes pour le query builder, vous pouvez utiliser le SQL Editor. Il vous donne un contrôle total sur la requête en vous permettant d’écrire et d’exécuter directement du ClickHouse SQL.

Le SQL Editor peut être ouvert en sélectionnant “SQL Editor” en haut de l’éditeur de requêtes.

Les fonctions macro peuvent toujours être utilisées dans ce mode.

Vous pouvez basculer entre les types de requêtes pour obtenir la visualisation la mieux adaptée à votre requête. Ce changement a également un effet en vue dashboard, notamment avec les données de séries temporelles.

​

Liens de données

Les liens de données de Grafana peuvent être utilisés pour créer des liens vers de nouvelles requêtes. Cette fonctionnalité a été activée dans le plugin ClickHouse pour lier une trace aux logs et inversement. Elle fonctionne mieux lorsque OpenTelemetry est configuré à la fois pour les logs et les traces dans la configuration de la source de données

Exemple de liens de traces dans un tableau

Exemple de liens de traces dans les logs

​

Comment créer un lien de données

Vous pouvez créer un lien de données en sélectionnant une colonne nommée traceID dans votre requête. Ce nom n’est pas sensible à la casse et accepte l’ajout d’un trait de soulignement avant « ID ». Par exemple : traceId, TraceId, TRACE_ID et tracE_iD sont tous valides.

Si OpenTelemetry est activé dans une requête de logs ou de trace, une colonne d’ID de trace sera ajoutée automatiquement.

En incluant une colonne d’ID de trace, les liens “View Trace” et “View Logs” seront associés aux données.

​

Fonctionnalités de liaison

Avec les data links en place, vous pouvez ouvrir des traces et des logs à l’aide du trace ID fourni.

“View Trace” ouvre un panneau fractionné contenant la trace, et “View Logs” ouvre une requête de logs filtrée sur le trace ID. Si vous cliquez sur le lien depuis un dashboard plutôt que depuis la vue Explore, il s’ouvrira dans un nouvel onglet de la vue Explore.

Il est nécessaire de configurer des valeurs par défaut pour les logs et les traces lorsque vous passez d’un type de requête à l’autre (des logs vers les traces et des traces vers les logs). En revanche, aucune valeur par défaut n’est requise lors de l’ouverture d’un lien du même type de requête, car la requête peut simplement être copiée.

Exemple d’affichage d’une trace (panneau de droite) à partir d’une requête de logs (panneau de gauche)

​

Macros

Les macros sont un moyen simple d’ajouter du SQL dynamique à votre requête. Avant qu’une requête ne soit envoyée au serveur ClickHouse, le plugin développe la macro et la remplace par l’expression complète.

Les requêtes du SQL Editor comme du Query Builder peuvent utiliser des macros.

​

Utilisation des macros

Les macros peuvent être utilisées n’importe où dans la requête, et plusieurs fois si nécessaire.

Voici un exemple d’utilisation de la macro $__timeFilter :

Entrée :

SELECT log_time, log_message
FROM logs
WHERE $__timeFilter(log_time)

Résultat final de la requête :

SELECT log_time, log_message
FROM logs
WHERE log_time >= toDateTime(1415792726) AND log_time <= toDateTime(1447328726)

Dans cet exemple, l’intervalle de temps du tableau de bord Grafana est appliqué à la colonne log_time.

Le plugin prend également en charge la notation avec des accolades {}. Utilisez cette notation lorsqu’il est nécessaire d’utiliser des requêtes dans les paramètres.

​

Liste des macros

Voici la liste de toutes les macros disponibles dans le plugin :

Macro	Description	Exemple de sortie
$__dateFilter(columnName)	Remplacé par un filtre sur l’intervalle de temps de la colonne fournie, en utilisant l’intervalle de temps du panneau Grafana comme Date.	columnName >= toDate('2022-10-21') AND columnName <= toDate('2022-10-23')
$__timeFilter(columnName)	Remplacé par un filtre sur l’intervalle de temps de la colonne fournie, en utilisant l’intervalle de temps du panneau Grafana comme DateTime.	columnName >= toDateTime(1415792726) AND time <= toDateTime(1447328726)
$__timeFilter_ms(columnName)	Remplacé par un filtre sur l’intervalle de temps de la colonne fournie, en utilisant l’intervalle de temps du panneau Grafana comme DateTime64.	columnName >= fromUnixTimestamp64Milli(1415792726123) AND columnName <= fromUnixTimestamp64Milli(1447328726456)
$__dateTimeFilter(dateColumn, timeColumn)	Raccourci qui combine $__dateFilter() et $__timeFilter() en utilisant des colonnes Date et DateTime distinctes. Alias : $__dt()	$__dateFilter(dateColumn) AND $__timeFilter(timeColumn)
$__fromTime	Remplacé par l’heure de début de l’intervalle du panneau Grafana, convertie en DateTime.	toDateTime(1415792726)
$__fromTime_ms	Remplacé par l’heure de début de l’intervalle du panneau, convertie en DateTime64.	fromUnixTimestamp64Milli(1415792726123)
$__toTime	Remplacé par l’heure de fin de l’intervalle du panneau Grafana, convertie en DateTime.	toDateTime(1447328726)
$__toTime_ms	Remplacé par l’heure de fin de l’intervalle du panneau, convertie en DateTime64.	fromUnixTimestamp64Milli(1447328726456)
$__timeInterval(columnName)	Remplacé par une fonction qui calcule l’intervalle en fonction de la taille de la fenêtre en secondes.	toStartOfInterval(toDateTime(columnName), INTERVAL 20 second)
$__timeInterval_ms(columnName)	Remplacé par une fonction qui calcule l’intervalle en fonction de la taille de la fenêtre en millisecondes.	toStartOfInterval(toDateTime64(columnName, 3), INTERVAL 20 millisecond)
$__interval_s	Remplacé par l’intervalle du tableau de bord en secondes.	20
$__conditionalAll(condition, $templateVar)	Remplacé par le premier paramètre lorsque la variable de template du second paramètre ne sélectionne pas toutes les valeurs. Remplacé par 1=1 lorsque la variable de template sélectionne toutes les valeurs.	condition ou 1=1