> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Utilisation du constructeur de requêtes dans le plugin Grafana de ClickHouse
# Constructeur de requêtes
export const ClickHouseSupportedBadge = () => {
return
Compatible avec ClickHouse
;
};
export const Image = ({img, alt, size}) => {
return
;
};
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](#sql-editor).
Toutes les requêtes du query builder ont un [type de requête](#query-types) et nécessitent la sélection d’au moins une colonne.
Les types de requête disponibles sont les suivants :
* [Table](#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](#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](/fr/integrations/connectors/data-visualization/grafana/config#logs).
* [Time Series](#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](#traces) : optimisé pour rechercher et afficher les traces. Fonctionne le mieux dans la vue Explore avec les [valeurs par défaut configurées](/fr/integrations/connectors/data-visualization/grafana/config#traces).
* [SQL Editor](#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](/fr/reference/functions/aggregate-functions/index). 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](/fr/reference/statements/select/group-by). Visible uniquement en mode Aggregate. |
| Order By | Une liste d’expressions [ORDER BY](/fr/reference/statements/select/order-by). |
| Limit | Ajoute une instruction [LIMIT](/fr/reference/statements/select/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](/fr/integrations/connectors/data-visualization/grafana/config#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](#data-links).
| 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](/fr/reference/statements/select/order-by). |
| Limite | Ajoute une instruction [LIMIT](/fr/reference/statements/select/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](#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](/fr/reference/functions/aggregate-functions/index). 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](/fr/reference/statements/select/group-by). Visible uniquement en Aggregate mode. |
| Order By | Une liste d’expressions [ORDER BY](/fr/reference/statements/select/order-by). |
| Limit | Ajoute une instruction [LIMIT](/fr/reference/statements/select/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](/fr/integrations/connectors/data-visualization/grafana/config#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](#data-links).
| 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](/fr/reference/statements/select/order-by). |
| Limit | Ajoute une instruction [LIMIT](/fr/reference/statements/select/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](#data-links) 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](#macros) 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](https://grafana.com/docs/grafana/latest/panels-visualizations/configure-data-links)
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](/fr/integrations/connectors/data-visualization/grafana/config#opentelemetry)
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](#logs) ou de [trace](#traces), 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](/fr/integrations/connectors/data-visualization/grafana/config#logs) et les [traces](/fr/integrations/connectors/data-visualization/grafana/config#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 :
```sql theme={null}
SELECT log_time, log_message
FROM logs
WHERE $__timeFilter(log_time)
```
Résultat final de la requête :
```sql theme={null}
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](/fr/reference/syntax#defining-and-using-query-parameters).
### 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](/fr/reference/data-types/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](/fr/reference/data-types/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](/fr/reference/data-types/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](/fr/reference/data-types/datetime). | `toDateTime(1415792726)` |
| `$__fromTime_ms` | Remplacé par l'heure de début de l'intervalle du panneau, convertie en [DateTime64](/fr/reference/data-types/datetime64). | `fromUnixTimestamp64Milli(1415792726123)` |
| `$__toTime` | Remplacé par l'heure de fin de l'intervalle du panneau Grafana, convertie en [DateTime](/fr/reference/data-types/datetime). | `toDateTime(1447328726)` |
| `$__toTime_ms` | Remplacé par l'heure de fin de l'intervalle du panneau, convertie en [DateTime64](/fr/reference/data-types/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` |