# Tableaux de bord (.dash)

> Construisez des tableaux de bord DuckLocal en fichiers .dash : graphiques, filtres croisés, commentaires pour un agent IA et validation avec ducklocal check.

Source: https://ducklocal.app/docs/fr/dashboards

Un fichier `.dash` décrit un tableau de bord comme des données : les blocs **source** nomment des fichiers de données, les blocs **query** contiennent du SQL, les blocs **plot** dessinent les résultats et les blocs **filter** permettent qu'un clic sur un graphique en restreigne d'autres. Il n'y a pas de code à écrire. Les personnes comme les agents IA peuvent créer le fichier, le relire dans un diff et le valider avant que quiconque ne l'ouvre.

Un fichier `.dash` dessine des graphiques, des tableaux, des nombres et des cartes géographiques standard à partir de requêtes enregistrées. Son format en texte brut le rend aussi utile avec un agent IA : l'agent écrit ou modifie le fichier, `ducklocal check` vérifie qu'il s'exécute, et vous [commentez les graphiques](#review-with-comments) pour demander des changements.

## Un exemple complet {#a-complete-example}

Ce tableau de bord interroge le [fichier d'exemple du tutoriel](tutorial.md#sample-file). Téléchargez [sales.dash](https://ducklocal.app/docs/samples/sales.dash) dans le même dossier que `sales.csv`, puis ouvrez-le.

```hcl
source "sales" {
  path = "sales.csv"
}

query "totals" {
  sql = <<SQL
    SELECT round(sum(revenue), 2) AS revenue, sum(orders) AS orders,
           count(DISTINCT region) AS regions
    FROM sales
    WHERE $channel
  SQL
}

query "by_channel" {
  sql = <<SQL
    SELECT channel, round(sum(revenue), 2) AS revenue
    FROM sales
    GROUP BY channel
    ORDER BY revenue DESC
  SQL
}

query "daily" {
  sql = <<SQL
    SELECT date, region, round(sum(revenue), 2) AS revenue
    FROM sales
    WHERE $channel
    GROUP BY date, region
    ORDER BY date
  SQL
}

plot "revenue" {
  type  = "card"
  query = query.totals
  value = revenue
  title = "Revenue"
  width = 4
}

plot "orders" {
  type  = "card"
  query = query.totals
  value = orders
  title = "Orders"
  width = 4
}

plot "regions" {
  type  = "card"
  query = query.totals
  value = regions
  title = "Regions"
  width = 4
}

plot "revenue_by_channel" {
  type  = "bar"
  query = query.by_channel
  x     = channel
  y     = revenue
  title = "Revenue by channel"
  width = 5
}

plot "daily_revenue" {
  type   = "line"
  query  = query.daily
  x      = date
  y      = revenue
  series = region
  title  = "Daily revenue, per region"
  width  = 7
}

plot "daily_table" {
  type  = "table"
  query = query.daily
  title = "The numbers behind it"
}

filter "channel" {
  plot = plot.revenue_by_channel
}
```

Il s'ouvre avec trois nombres en haut, le graphique en barres et le graphique en courbes côte à côte, et le tableau en dessous. Chaque requête s'exécute une fois, quel que soit le nombre de graphiques qui la dessinent : `totals` alimente les trois cartes, et `daily` alimente à la fois la courbe et le tableau. Cliquez sur une barre dans **Revenue by channel** et les cartes, la courbe et le tableau se restreignent à ce canal ; le graphique en barres lui-même reste entier, pour que vous puissiez en cliquer une autre.

## Ouvrir un tableau de bord

N'importe laquelle de ces actions ouvre un fichier `.dash` comme onglet de tableau de bord, à côté de vos requêtes :

- le **+** au bout de la barre d'onglets, puis **Ouvrir un tableau de bord** ;
- le fichier glissé sur la fenêtre ;
- son nom sur la ligne de commande : `ducklocal sales.dash` ;
- depuis un script ou un agent, dans la fenêtre déjà en cours : `ducklocal open sales.dash` (voir le [guide de la CLI](cli.md#show-work-in-the-running-window)).

Les graphiques se disposent sur une grille de 12 colonnes : chacun occupe son [`width`](#layout), les graphiques remplissent une ligne de gauche à droite, et un graphique qui ne tient plus commence la ligne suivante. Faites glisser les séparateurs entre les lignes pour les redimensionner ; un tableau de bord plus haut que l'onglet défile. Un graphique qui ne peut pas se dessiner — sa requête a échoué, ou une colonne manque — affiche la raison dans son propre panneau, et le reste du tableau de bord se dessine quand même. Les tableaux de bord ouverts reviennent au lancement suivant, et les plus récents sont listés sous **Tableaux de bord** dans la barre latérale.

Survolez un graphique pour révéler ses commandes dans le coin supérieur droit :

- **SQL** bascule le graphique vers le SQL que sa requête a exécuté en dernier — ses sources et les choix de filtre du moment intégrés, pour qu'il s'exécute tel quel — avec **Copier** et **Ouvrir dans un onglet de requête**. **Graphique** le remet.
- La bulle ouvre les [commentaires](#review-with-comments) du graphique.
- **Agrandir ce graphique** l'étend à tout l'onglet du tableau de bord. Utilisez **Retour au tableau de bord (Échap)** ou appuyez sur **Échap** pour revenir à la grille.

La vue SQL colore la syntaxe. Faites un clic droit sur une cellule d'un tableau de bord pour copier la cellule, sa ligne séparée par des tabulations, ou sa colonne dans l'ordre affiché.

Cliquez sur l'en-tête de colonne d'un graphique `table` pour le trier : décroissant, croissant, puis retour à l'ordre de la requête. Les nombres se trient comme des nombres et `NULL` se trie en dernier ; une ligne choisie pour un [filtre](#filters) reste choisie à travers un tri.

La commande **Voir la spec** de la barre d'outils bascule l'onglet vers un éditeur du fichier, avec coloration syntaxique (le SQL des heredocs est coloré comme dans l'éditeur SQL), complétion et diagnostics en ligne. **Enregistrer** ou **⌘S** l'écrit et redessine. Si le fichier enregistré échoue à la validation, l'onglet garde le dernier tableau de bord fonctionnel et affiche l'erreur au-dessus. La même chose se produit quand un autre programme modifie le fichier. **Retour au tableau de bord** revient aux graphiques. **Recharger** relit le fichier et exécute à nouveau chaque requête.

## Revoir avec des commentaires {#review-with-comments}

Les commentaires permettent de relire un tableau de bord comme un document, et de confier les changements à un agent IA. La réflexion produit derrière ce flux de travail est explorée dans [Ce que les tableaux de bord Claude m'ont appris sur DuckLocal](https://ducklocal.app/blog/claude-dashboards-ducklocal/).

**Dans la fenêtre**, survolez un graphique et cliquez sur la bulle. Un panneau s'ouvre au-dessus du tableau de bord, citant le titre du graphique, avec les fils déjà présents et une zone pour écrire. Écrivez ce qui devrait changer — *« classez-les, le plus gros canal d'abord »* — et appuyez sur **Commenter** (ou **⌘/Ctrl+Entrée**). Chaque fil a **Répondre** et **Résoudre** ; un fil résolu reste, atténué, jusqu'à ce que quelqu'un y réponde. Un graphique avec des fils ouverts garde une bulle avec leur nombre en vue, pour que vous voyiez d'un coup d'œil ce qui attend.

**L'agent** lit et répond aux fils avec [`ducklocal comments`](cli.md#review-comments-on-a-dashboard), sans fenêtre :

```bash
ducklocal comments sales.dash
```

```json
{
  "file": "sales.dash",
  "comments_file": "sales.dash.comments.json",
  "open": 1,
  "threads": [
    {
      "id": "c1",
      "plot": "revenue_by_channel",
      "plot_title": "Revenue by channel",
      "plot_query": "by_channel",
      "plot_lines": [68, 75],
      "plot_missing": false,
      "resolved": false,
      "comments": [
        { "author": "user", "text": "Rank these, biggest channel first", "at": "2026-10-10T14:03:00+08:00" }
      ]
    }
  ]
}
```

Chaque fil nomme son graphique, la requête du graphique et les lignes de son bloc `plot` dans le fichier, pour que l'agent sache quoi modifier. Il change la spec, lance `ducklocal check` et répond :

```bash
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" --resolve
```

La fenêtre surveille les deux fichiers. En moins d'une seconde, le graphique se redessine à partir de la spec modifiée, et la réponse de l'agent apparaît dans son fil, marquée **Agent**.

Les fils sont conservés à côté du tableau de bord, dans `NAME.dash.comments.json`, pour qu'ils voyagent avec lui comme le font ses fichiers `source`. Ce sont des notes de travail, pas une partie du tableau de bord : laissez-les hors du contrôle de version, ou supprimez le fichier une fois la relecture terminée.

La [compétence d'agent officielle](cli.md#install-the-official-skill) enseigne cette boucle, si bien qu'un agent qui l'a n'a qu'à s'entendre dire *« traite les commentaires de sales.dash »*.

::: info Nouveau dans 0.4.0
Un agent peut [proposer un changement](agent-workflows.md#propose) plutôt que modifier le fichier. L'onglet propose alors **Relire**, avec le diff et les vérifications, et vous seul pouvez l'appliquer.
:::

### Voir un agent au travail {#agent-presence}

Pendant qu'un agent lance `check`, `comments` ou `presence` pour ce tableau de bord ouvert, son nom apparaît dans le coin, avec la marque de son fabricant — Claude, OpenAI, Gemini, Cursor, DeepSeek — ou son initiale. Cliquez sur le nom pour voir le journal de session. Quand il modifie le fichier, les graphiques modifiés et ajoutés restent marqués (**Claude a modifié ceci**, **Claude a ajouté ceci**) jusqu'à ce que vous les ayez eus en vue un moment ; un graphique supprimé laisse un avis que vous pouvez écarter.

Un agent peut annoncer sa prochaine modification avec `ducklocal presence sales.dash --doing editing --plot revenue_by_channel`. Ce graphique reçoit un anneau ; un nom de graphique qui n'existe pas encore reçoit un espace réservé sous le tableau de bord. La session se termine après 30 secondes sans activité, ou avec un `--doing idle` explicite. Un agent terminé reste dans le coin tant qu'un fil auquel il a répondu attend votre réponse, avec le compte sur son avatar. Les commentaires notent quel agent les a écrits et affichent sa marque. La [référence CLI](cli.md#agent-presence) couvre les options. Ces indicateurs montrent l'activité locale ; ils n'envoient pas de travail à un agent.

## Blocs {#blocks}

Un fichier est une suite de blocs, chacun avec un type, un nom entre guillemets et un corps :

```hcl
source "name" { ... }
view "name" { ... }
query "name" { ... }
plot "name" { ... }
filter "name" { ... }
dashboard "name" { ... }
```

Les noms doivent être uniques dans leur type : deux requêtes ne peuvent pas partager un nom, et deux graphiques non plus — mais une requête et un graphique peuvent.

::: info Nouveau dans 0.4.1
Un bloc `view` porte une mise en forme que plusieurs requêtes partagent, un `filter` peut collecter plusieurs valeurs (`multiple = true`), un graphique `timeline` place les événements selon leur distance réelle dans le temps, et un bloc `dashboard` fixe le fuseau dans lequel chaque `TIMESTAMPTZ` est affiché.
:::

### source

| Attribut | Requis | Valeur |
| --- | --- | --- |
| `path` | oui | Un fichier `.csv`, `.tsv`, `.txt`, `.parquet`, `.json`, `.jsonl` ou `.ndjson` (compressé en gzip aussi, comme `.csv.gz`), ou un glob de tels fichiers (`exports/orders-*.csv`) lu comme une seule relation |

Une source donne un nom à des fichiers de données que les requêtes lisent : avec `source "sales"`, une requête dit `FROM sales`. Le chemin est **relatif au fichier `.dash`**, pas à l'endroit d'où DuckLocal a été lancé, ainsi un tableau de bord et ses données peuvent se déplacer ensemble ; `~` et les chemins absolus fonctionnent aussi.

Une source ne touche jamais la connexion : elle devient un `WITH sales AS (…)` devant chaque requête qui la nomme, donc rien n'apparaît dans la barre latérale, rien ne survit à l'onglet, et une source masque une table de même nom pour les requêtes de ce tableau de bord seulement. Le nom doit être un identifiant simple (lettres, chiffres et `_`). Un classeur ne peut pas être une source ; ouvrez-le dans DuckLocal et interrogez la table qu'il devient.

### view

Une vue porte une mise en forme que plusieurs requêtes partagent, écrite une fois. Elle contient un attribut `sql`, soumis aux mêmes règles que celui d'une requête, et chaque requête qui la nomme la lit comme une table :

```hcl
view "events" {
  sql = <<SQL
    SELECT r.eventName AS event_name, r.eventTime AS event_time
    FROM (SELECT unnest(Records) AS r FROM trail)
  SQL
}

query "totals" {
  sql = "SELECT count(*) AS events, count(DISTINCT event_name) AS kinds FROM events"
}
```

Une vue lit les sources et les vues définies au-dessus d'elle, partage ses noms avec les sources, et ne prend pas de `$filter` — lisez le filtre dans les requêtes qui lisent la vue. Comme une source, elle est placée devant chaque requête qui la nomme et ne crée rien sur la connexion. Recourez-y quand des requêtes répéteraient sinon la même CTE, comme l'aplatissement de JSON imbriqué.

### query

| Attribut | Requis | Valeur |
| --- | --- | --- |
| `sql` | oui | Une instruction SQL en lecture seule, sous forme de [heredoc](#heredocs) ou de chaîne |

Un bloc de requête contient `sql` et rien d'autre. Il peut lire `$name` pour un [filtre](#filters).

### plot

| Attribut | Pour | Valeur |
| --- | --- | --- |
| `type` | tous, requis | `"line"`, `"bar"`, `"stacked_bar"`, `"area"`, `"scatter"`, `"pie"`, `"heatmap"`, `"histogram"`, `"map"`, `"timeline"`, `"table"`, `"card"` ou `"text"` — une chaîne entre guillemets |
| `query` | tous sauf `text`, requis | Une référence à un bloc de requête : `query.by_channel` |
| `x` | graphiques, requis | La colonne de l'axe horizontal ; les parts d'un `pie` ; le nombre qu'un `histogram` regroupe ; le temps d'un `timeline`. Un `table` montre toutes les colonnes et n'en a besoin d'aucune |
| `y` | graphiques, requis | La colonne à tracer ; doit être numérique. La taille des parts d'un `pie`. Un `histogram` et un `timeline` n'en prennent pas |
| `series` | `line`, `bar`, `stacked_bar`, `area`, `scatter`, `heatmap`, `timeline` | Une colonne dont les valeurs séparent les lignes en une série chacune ; les lignes d'un `heatmap` ; les couloirs d'un `timeline` |
| `title` | tous | Un titre pour le graphique, sous forme de chaîne entre guillemets ; l'étiquette d'une carte |
| `width` | tous | Combien des 12 colonnes de la grille le graphique occupe, `1`–`12`. Par défaut 12, ou 3 pour une carte |
| `value` | `card` | La colonne à afficher, de la première ligne. Par défaut : la première colonne |
| `note` | `card` | Du texte sous la valeur : une chaîne entre guillemets, ou un nom de colonne nu à lire sur la première ligne |
| `tone` | `card` | `"accent"`, `"good"`, `"warning"` ou `"critical"` ; colore le filet supérieur et la valeur |
| `format` | graphiques et `card` | Ce que sont les nombres : voir [Formats de nombres et variation](#number-formats-and-change). Un `map` ou un `table` n'en prend pas |
| `delta` | `card` | Une colonne numérique portant la variation, affichée sous la valeur |
| `delta_format` | `card` | Un format pour la variation. Par défaut : celui de la carte |
| `down_is_good` | `card` | `true` rend une baisse verte et une hausse rouge, pour les coûts, la latence ou le churn |
| `description` | tous, **0.4.0+** | Ce que le graphique montre et comment le lire ; apparaît au survol d'un ⓘ à côté du titre |
| `text` | `text` | Le texte du corps, en chaîne ou en heredoc ; fournissez `title`, `text`, ou les deux, sans `query` |
| `caption` | `timeline` | La colonne qui dit ce que chaque événement était, écrite sous son point quand elle tient et au survol |
| `lat`, `lng` | `map` | Colonnes de latitude et de longitude, en degrés. L'une ou l'autre peut être omise quand le nom de la colonne numérique indique la coordonnée — `lat`, `latitude`, `geo_lat` ; `lng`, `lon`, `longitude` |
| `color` | `map` | Une colonne pour colorer les points ; omise, une est choisie quand une colonne de texte n'a que peu de valeurs |
| `size` | `map` | Une colonne numérique pour dimensionner les points |
| `size_scale` | `map` | `"sqrt"` (par défaut) ou `"log"`, pour la façon dont `size` s'échelonne |
| `tooltip` | `map` | Une liste des colonnes qu'affiche l'infobulle d'un point : `[name, passengers]` |

Les attributs de colonne nomment des colonnes du résultat de la requête, appariées sans tenir compte de la casse. Écrivez un nom simple nu (`x = date`) ; mettez entre guillemets un nom qui n'est pas un identifiant simple (`y = "revenue (EUR)"`). Un attribut dont le type du graphique n'a pas l'usage — `lat` sur une courbe, `x` sur une carte, `series` sur un diagramme circulaire — est une faute, pas quelque chose d'ignoré en silence.

### filter

| Attribut | Requis | Valeur |
| --- | --- | --- |
| `plot` | oui | Le graphique sur lequel un clic choisit une valeur : `plot.revenue_by_channel`. Un `bar`, un `stacked_bar` ou un `table` |
| `column` | pour un `table` | La colonne dont la valeur est choisie. Pour un `bar` ou `stacked_bar`, son `x` quand elle est omise |
| `multiple` | `bar`, `stacked_bar` | `true` fait que chaque clic ajoute sa valeur et qu'un second clic la retire ; `$name` devient `IN (…)`. Un tableau sélectionne une ligne, donc `multiple` sur un tableau est une erreur de vérification |

Voir [Filtres](#filters) pour ce que fait un filtre.

### dashboard

Un bloc `dashboard` facultatif contient des réglages pour tout le fichier :

```hcl
dashboard "Ops" {
  timezone = "+08:00"     # or "UTC", or "local"
}
```

`timezone` est le fuseau dans lequel chaque `TIMESTAMPTZ` du tableau de bord est affiché ; le fuseau est indiqué au-dessus des graphiques. Un décalage (`"+08:00"`), `"UTC"` et `"local"` sont acceptés ; les noms IANA comme `Asia/Shanghai` ne le sont pas. Un `TIMESTAMP` simple n'a pas de fuseau et s'affiche tel qu'écrit, et une colonne qu'un filtre choisit garde sa valeur stockée, pour que les choix correspondent toujours. Un fichier contient au plus un bloc `dashboard`.

## Types de graphique {#plot-types}

| Type | Dessine |
| --- | --- |
| `line` | Une ligne par série, non remplie |
| `area` | Une aire remplie par série |
| `bar` | Une barre par ligne, une couleur par série. Avec `series`, les barres de chaque série côte à côte dans chaque groupe. Une série unique étiquette chaque barre avec sa valeur |
| `stacked_bar` | Une barre par `x`, son `series` empilé : les parts positives vers le haut depuis zéro, les négatives vers le bas, avec le total au-dessus et dans l'infobulle |
| `heatmap` | `x` en travers et `series` en descendant, chaque cellule colorée par `y` sur un seul bleu, plus foncé pour plus (plus clair en thème sombre). Un couple que la requête ne renvoie pas reste vide |
| `histogram` | Les lignes comptées dans chaque plage d'un `x` numérique, en classes de largeur ronde. Laissez sa requête renvoyer les lignes elles-mêmes, pas un regroupement |
| `scatter` | Un point par valeur, non reliés, une couleur par série |
| `pie` | Une part par valeur de `x`, dimensionnée par `y`, la plus grande d'abord ; au-delà de 8 parts, les plus petites se replient dans « autre ». Dessiné en anneau avec le total au milieu ; cliquez une entrée de la légende pour isoler une part, et de nouveau pour la rétablir |
| `text` | Un titre, un texte explicatif, ou les deux ; aucune requête ne s'exécute |
| `map` | Un point par ligne, à son `lat` et son `lng` ; voir [Cartes géographiques](#maps) |
| `timeline` | Un événement par ligne à son temps `x`, placé selon sa distance réelle aux autres, pour que les écarts se voient. `series` donne à chaque acteur un couloir, `caption` dit ce qui s'est passé, et `tooltip` liste les colonnes survolées. Ne prend pas de `y` ; dessine au plus 12 couloirs et 1 000 événements (éclaircis régulièrement au-delà, et signalé), et compte les lignes dont le temps ne peut pas être lu au lieu de les dessiner |
| `table` | Le résultat de la requête en grille, colonnes dimensionnées à leur contenu ; cliquez un en-tête pour trier |
| `card` | Un nombre, grand, avec le `title` comme étiquette. Groupé par milliers, une longue fraction arrondie (`11439704.020000005` → `11,439,704.02`), et réduit pour tenir dans la carte plutôt que coupé |

Survolez un graphique pour ses valeurs, formatées comme l'axe les montre (`4.4M`, pas `4400000`).

Un graphique en barres étiquette **chaque** catégorie. Quand les étiquettes ne tiennent pas sous leurs barres, le graphique se couche, les étiquettes dans une colonne à gauche. Seul un axe temporel éclaircit ses étiquettes, en gardant autant qu'il en tient — toujours la première et la dernière — et une barre sur une colonne `DATE` remplit les jours pour lesquels la requête n'a rien renvoyé par des bandes vides, pour qu'une période calme se lise comme un trou plutôt que de disparaître. Les axes des courbes, des aires et des nuages de points éclaircissent leurs étiquettes de la même façon.

L'axe des x est catégoriel pour tous les types de graphique : les valeurs sont espacées régulièrement dans l'ordre où la requête les renvoie, pas selon leur distance les unes aux autres. Un `scatter` de deux colonnes numériques n'est donc pas un vrai tracé x–y.

Les lignes sont tracées dans l'ordre où la requête les renvoie, donc terminez par `ORDER BY` une requête qui alimente un graphique.

::: info Nouveau dans 0.4.0
Un `line` ou un `scatter` de tableau de bord sur des temps est placé selon le temps, donc des écarts irréguliers paraissent irréguliers, et il se dessine dans l'ordre temporel quel que soit l'`ORDER BY`. Une ligne avec un temps NULL est omise, avec une note. Un NULL renvoyé par la requête casse la ligne. Un `area` reste régulièrement espacé et le dit. Une série garde sa couleur par son nom, et chaque graphique dit quand sa requête a été coupée.
:::

Une carte de type `card` montre la première ligne de sa requête. Quand la requête renvoie plus d'une ligne, la carte le dit sous le nombre ; quand elle n'en renvoie aucune, elle affiche `—`.

### Cartes et panneaux de texte {#cards-and-text-panels}

Les cartes peuvent expliquer un nombre avec `note` et lui donner une couleur de statut avec `tone`. Les cartes d'une même ligne partagent une taille de police pour la valeur. Les panneaux de texte ajoutent des titres ou du contexte sans exécuter de SQL :

```hcl
plot "revenue_summary" {
  type  = "card"
  query = query.totals
  value = revenue
  title = "Revenue"
  note  = "Current channel selection"
  tone  = "accent"
  width = 4
}

plot "reading_guide" {
  type  = "text"
  title = "How to read this dashboard"
  text  = "Click a channel to filter the daily chart and revenue cards."
  width = 8
}
```

Un panneau de texte n'accepte que `type`, `title`, `text` et `width`. Utilisez `text = <<TEXT` avec une ligne `TEXT` de fermeture pour une explication plus longue. Les graphiques, diagrammes circulaires et cartes géographiques utilisent huit teintes distinctes, avec des nuances adaptées au thème courant et une légende pour plusieurs séries.

### Formats de nombres et variation {#number-formats-and-change}

`format` façonne la valeur d'une carte, l'axe des valeurs, les étiquettes des barres et les infobulles :

| Valeur | Se lit |
| --- | --- |
| `"num0"`, `"num1"`, `"num2"` | Un nombre avec ce nombre de décimales |
| `"pct"` (identique à `"pct1"`), `"pct0"`, `"pct2"` | Une part : 0,421 se lit 42,1 %, donc renvoyez la fraction, pas ×100 |
| `"usd"`, `"eur"`, `"gbp"`, `"cny"` | De l'argent, avec deux décimales |
| `"usd0"`, `"eur0"`, `"gbp0"`, `"cny0"`, `"jpy"` | De l'argent, en unités entières |

Une carte montre une variation avec `delta`, sous la valeur, comme `▲ 12.3%` ou `▼ $125`. Elle est verte quand c'est bon et rouge sinon, et la `note` la suit pour dire par rapport à quoi. Calculez la variation dans la requête de la carte :

```hcl
plot "revenue_total" {
  type         = "card"
  query        = query.totals
  value        = revenue
  format       = "usd0"
  delta        = growth
  delta_format = "pct1"
  note         = "vs last week"
}
```

### Disposition {#layout}

`width` est le nombre des douze colonnes du tableau de bord qu'un graphique occupe. Les graphiques remplissent une ligne depuis la gauche dans l'ordre où ils sont écrits et passent à la ligne quand le suivant ne tient pas, si bien que quatre cartes (`3` chacune) font une ligne de nombres, et deux graphiques `width = 6` se placent côte à côte en dessous. Une ligne qui n'atteint pas douze laisse le reste vide. Une ligne de cartes seulement commence à une hauteur courte, une ligne de tableaux seulement commence aussi haute que les lignes de son plus long tableau, jusqu'à la hauteur d'un graphique. Une ligne de panneaux de texte tient à son texte ; les autres lignes commencent à la hauteur d'un graphique. Les poignées de redimensionnement de ligne apparaissent au survol.

### Cartes géographiques {#maps}

```hcl
plot "stations" {
  type       = "map"
  query      = query.stations
  lat        = geo_lat
  lng        = geo_lng
  color      = line
  size       = passengers
  size_scale = "log"
  tooltip    = [name, passengers]
}
```

Une carte géographique trace chaque ligne comme un point, sur une projection Web Mercator ajustée aux points, au-dessus d'une grille de latitude/longitude étiquetée en degrés.

- **`color`** : jusqu'à cinq valeurs reçoivent chacune une couleur ; au-delà, les quatre plus fréquentes en reçoivent une et le reste partage une couleur « autre ». Une légende les relit. Omis, les points sont colorés par une colonne de texte n'ayant que peu de valeurs distinctes, quand le résultat en a une.
- **`size`** : l'*aire* d'un point suit la valeur, donc deux fois la valeur fait deux fois l'encre. `size_scale = "log"` convient à des valeurs qui couvrent des ordres de grandeur. Une légende dans le coin relit les tailles.
- **`tooltip`** : sans lui, l'infobulle d'un point liste la colonne de taille et les autres nombres, puis les coordonnées.

Sous les points, une carte peut dessiner un fond de carte **OpenStreetMap**. Il est désactivé tant que vous ne l'activez pas — **Affichage → Fond de carte en ligne (OpenStreetMap)** — parce que charger les tuiles demande le réseau. Ce qu'il envoie, ce sont les tuiles qu'il veut, ce qui révèle grosso modo la zone regardée, jamais une ligne de vos données. Les tuiles sont mises en cache sur le disque une semaine (voir [Paramètres et données de l'app](settings-and-data.md#where-things-are-stored)) ; hors ligne ou désactivé, la carte se dessine sur sa seule grille de latitude/longitude. Le même réglage couvre la carte de l'onglet **Graphique** des résultats de requête.

## Filtres {#filters}

Un filtre rend un graphique cliquable et laisse la valeur choisie restreindre d'autres requêtes :

```hcl
filter "channel" {
  plot = plot.revenue_by_channel     # a click on a bar picks its channel
}

filter "day" {
  plot   = plot.days                 # a table: a selected row picks …
  column = day                       # … the value of this column
}

filter "channel" {
  plot     = plot.revenue_by_channel
  multiple = true                    # clicks collect channels
}

query "daily" {
  sql = "SELECT date, sum(orders) AS orders FROM sales WHERE $channel AND $day GROUP BY 1"
}
```

Une requête lit un filtre comme **`$name`, une condition** : écrivez-le là où va une condition. Tant que rien n'est choisi, il vaut `TRUE`, donc le tableau de bord s'ouvre exactement comme sans le filtre. Une fois une valeur choisie, il devient `("channel" = 'Web')` — la colonne nommée comme la `column` du filtre, comparée à la valeur choisie ; une cellule affichée comme `NULL` correspond au NULL SQL ou au texte littéral `NULL`. Avec `multiple = true` sur un graphique en barres ou en barres empilées, chaque clic ajoute sa valeur et un second clic la retire, et `$name` devient `("channel" IN ('Web', 'App'))`, avec `OR "channel" IS NULL` quand NULL en fait partie. Plusieurs filtres se combinent comme la requête les combine.

- **Sur un graphique en barres**, cliquez une barre pour la choisir : elle garde sa couleur tandis que les autres s'atténuent. Cliquez-la de nouveau pour effacer le choix. Avec `multiple = true`, chaque clic ajoute une valeur et un second clic la retire.
- **Sur un tableau**, sélectionnez une ligne, au clic ou avec les flèches du clavier.
- Les choix en vigueur apparaissent comme des jetons au-dessus des graphiques ; le ✕ de chaque jeton efface son filtre, et **Tout effacer** efface tous les choix. Un filtre à sélection multiple affiche un jeton par valeur choisie.
- **Le graphique de sélection n'est jamais restreint par son propre filtre.** Sa requête lit `$channel` comme `TRUE` même quand un canal est choisi — sinon un clic réduirait le graphique en barres à la barre qu'on vient de cliquer, sans plus rien à cliquer ensuite. C'est du filtrage croisé, comme dans Mosaic ou crossfilter.
- **Seul ce qui a changé se réexécute.** Un choix réexécute les requêtes dont le SQL change ; une requête qui ne lit aucun filtre garde son résultat.

Un filtre porte une valeur à la fois, ou plusieurs avec `multiple = true`. Les graphiques sélectionnables incluent une indication de clic pour filtrer sous le titre. Les séries gardent leurs couleurs quand le filtrage change les groupes qui restent. Une requête qui utilise `$channel` doit exposer la colonne du filtre là où ce prédicat est utilisé ; `ducklocal check` lie désormais aussi une variante avec une valeur choisie, pour qu'une colonne manquante soit détectée avant le premier clic.

::: info Nouveau dans 0.4.0
Choisir une cellule affichée comme `NULL` ne sélectionne que le NULL SQL, et le texte `'NULL'` ne se sélectionne que lui-même. Les graphiques sélectionnables n'affichent plus d'indication de clic pour filtrer sous le titre.
:::

La valeur choisie entre dans le SQL comme un littéral entre guillemets, et DuckDB la convertit vers le type de la colonne au moment de la comparaison, si bien que les dates et les nombres marchent aussi bien que le texte. Les choix durent tant que l'onglet est ouvert et survivent à un rechargement, tant que le filtre est encore dans le fichier ; ils ne sont pas mémorisés entre deux lancements.

## Valeurs

| Forme | Exemple | Servent à |
| --- | --- | --- |
| Chaîne | `"Revenue by channel"` | `type`, `title`, `path`, `size_scale`, `tone`, `note` littéral, `text`, noms de colonnes entre guillemets, `sql` court |
| Heredoc | `<<SQL` … `SQL` | `sql`, `text` |
| Référence | `query.daily`, `plot.revenue_by_channel` | le `query` d'un graphique, le `plot` d'un filtre |
| Nom nu | `channel` | attributs de colonne |
| Nombre | `6` | `width` |
| Liste | `[name, "Unique IPs"]` | `tooltip` |

Une chaîne se termine à sa ligne et comprend `\n`, `\t`, `\"` et `\\`.

`#` et `//` ouvrent un commentaire qui court jusqu'à la fin de la ligne. Les attributs n'ont pas besoin de séparateur ; les sauts de ligne ne sont que des espaces.

Voilà tout le langage : pas de variables, pas de fonctions, pas de conditionnelles, et pas d'interpolation au-delà du `$name` d'un filtre.

### Heredocs {#heredocs}

Un heredoc contient du texte sur plusieurs lignes — en pratique, du SQL :

```hcl
  sql = <<SQL
    SELECT 1
  SQL
```

- Le délimiteur après `<<` est un mot quelconque (`SQL` par convention), et rien ne peut le suivre sur sa ligne.
- Le heredoc se termine à la première ligne qui est exactement le délimiteur, à quelques espaces près.
- L'indentation de la ligne de fermeture est retirée de chaque ligne du texte, pour que le SQL puisse se tenir à l'indentation du bloc sans la porter.

## Règles SQL {#sql-rules}

Un tableau de bord exécute ses requêtes chaque fois qu'il est ouvert, rechargé ou enregistré, et quand DuckLocal démarre avec l'onglet restauré — donc une requête ne peut que **lire** :

- **Permis :** `SELECT`, `WITH …`, les requêtes commençant par `FROM`, `VALUES`, `SHOW`, `DESCRIBE`, `SUMMARIZE`, `PIVOT` et `UNPIVOT`.
- **Refusé :** tout ce qui pourrait changer des données ou des fichiers — `CREATE`, `INSERT`, `UPDATE`, `DELETE`, `DROP`, `COPY`, `ATTACH`, `INSTALL`, `LOAD`, etc. Ouvrir un fichier `.dash` que quelqu'un vous a envoyé ne peut pas changer vos données.
- **Une instruction par requête.**
- **Un `PIVOT` à l'intérieur d'une autre requête nomme ses valeurs.** Une requête qui commence par `PIVOT` peut laisser DuckDB trouver les valeurs (`PIVOT orders ON channel USING sum(amount)`). Un `PIVOT` imbriqué dans un `SELECT` ou un `WITH` a besoin d'une liste explicite : `ON channel IN ('Web', 'Store')`.
- **`$name` doit nommer un bloc de filtre.** La vérification en lecture seule juge le SQL avec chaque `$name` à `TRUE`. Un `$` dans une chaîne, un identifiant entre guillemets, un commentaire ou une chaîne `$$ … $$` est laissé tranquille.

Les requêtes tournent sur la connexion propre à la fenêtre, donc elles voient tout ce que voit l'éditeur SQL : fichiers ouverts, bases attachées et état de la connexion comme les tables `TEMP`.

### Chemins dans le SQL

Depuis la v0.2.2, les chemins de fichiers relatifs dans le SQL d'un tableau de bord sont aussi cherchés depuis le dossier du fichier `.dash`. Par exemple, `FROM 'sales.csv'` peut lire le CSV à côté du tableau de bord quand il est ouvert depuis un autre répertoire. Cela vaut dans la fenêtre et dans `ducklocal check`.

DuckDB vérifie toujours d'abord le répertoire de travail pour un fichier unique nommé directement dans le SQL : un fichier de même nom qui s'y trouve peut l'emporter. Un bloc [source](#source) résout son chemin explicitement par rapport au dossier du tableau de bord et évite cette ambiguïté. Les chemins absolus et les vues enregistrées restent disponibles.

## Limites

| Limite | Ce qui se passe |
| --- | --- |
| 12 séries par graphique | Les séries suivantes sont omises, et un avis dit combien il y en avait |
| 1 500 points par série | Les points sont moyennés par classes pour tenir |
| 200 barres | Les barres suivantes sont omises |
| 8 parts de diagramme circulaire | Les plus petites se replient en une seule part « autre » |
| 200 colonnes de heatmap, 12 lignes | Les colonnes et les lignes suivantes sont omises |
| 5–40 classes d'histogramme | Environ √lignes classes, chacune de 1, 2, 2,5 ou 5 × une puissance de dix de large |
| 20 000 points de carte | Les points suivants sont omis, et un avis le dit |
| 12 couloirs, 1 000 événements par timeline | Les événements suivants sont éclaircis régulièrement et un avis le dit ; les lignes dont le temps ne peut pas être lu sont comptées, pas dessinées |

## Valider un tableau de bord {#validate-a-dashboard}

`ducklocal check` valide un fichier sans ouvrir de fenêtre — l'étape à lancer avant de confier un tableau de bord à quiconque :

```bash
ducklocal check sales.dash
ducklocal check sales.dash --database warehouse.duckdb
ducklocal check sales.dash --summary
```

D'abord les vérifications statiques : la syntaxe, les noms et les références, les attributs requis, chaque `$name` confronté aux blocs de filtre, et le SQL de chaque requête passé au parseur de DuckDB. Puis **chaque requête s'exécute**, en lecture seule, avec ses sources et sans aucun choix, et les colonnes de chaque graphique sont vérifiées contre les colonnes que sa requête renvoie vraiment — y compris que `y`, les coordonnées d'une carte et son `size` sont numériques, et que la `column` de chaque filtre est une que renvoie la requête de son graphique. Exécuter a son importance : un cast qui échoue ou un glob qui ne correspond à rien n'apparaît qu'une fois des lignes lues.

- **Sans `--database`**, les requêtes tournent en mémoire, ce qui suffit à un tableau de bord construit sur ses propres fichiers `source`. Une requête qui lit une table qu'aucune source ne définit est listée sous `unresolved` plutôt que mise en échec, et les colonnes de ses graphiques ne sont pas vérifiées — elle est probablement destinée à une base.
- **Avec `--database PATH`**, elles tournent contre cette base, ouverte en lecture seule. Passez-la dès que les requêtes lisent les tables d'une base.

Chaque requête qui utilise un filtre est aussi liée à une valeur choisie, sans exécuter cette variante. Cela détecte les prédicats qui renvoient à une colonne indisponible dans cette requête. Les blocs fautifs n'empêchent pas les blocs sains d'être vérifiés : les diagnostics incluent les erreurs de spec et les échecs de requête d'une même exécution.

Le succès affiche un résumé JSON des sources, des requêtes (avec leurs colonnes de résultat et le nombre de `rows` que chacune a renvoyées), des filtres et des graphiques, plus `empty` : les requêtes qui ont tourné et n'ont renvoyé aucune ligne. Ce n'est pas une erreur, mais en général une regex, un filtre ou une jointure qui n'a rien trouvé : regardez chacune avant de confier le tableau de bord. `--summary` affiche une ligne JSON de comptes et les noms des requêtes non résolues et vides. Une faute sort au statut **2** pour les diagnostics de spec et liste tous les problèmes d'un coup, un `file:line: message` chacun. Les échecs purement SQL, de base ou de fichier sortent en **1**. Le [guide de la CLI](cli.md#check-a-dashboard-spec) donne les détails.

::: info Nouveau dans 0.4.0
`ducklocal check FILE --restricted --allow-read PATH` vérifie, sous contraintes, un tableau de bord que vous n'avez pas écrit. Voir [Limiter du SQL que vous n'avez pas écrit](agent-workflows.md#restricted).
:::

### Messages courants

| Message | Correctif |
| --- | --- |
| `type is a string in quotes` | Écrivez `type = "line"`, pas `type = line` |
| `Unknown plot type: "donut"; one of line, bar, area, scatter, pie, map, table, card, text` | Utilisez l'un des types listés |
| `plot block "p" requires y` | Tout type de graphique a besoin d'un `y` ; `table`, `map`, `card` et `text` non |
| `plot "p" draws query "q", which the file does not define` | Ajoutez le bloc de requête, ou corrigez le nom dans `query = query.…` |
| `query names a query block: query = query.some_name` | L'attribut `query` prend une référence, pas une chaîne |
| `plot "p" draws y = "channel" (VARCHAR), which is not numeric` | Pointez `y` vers une colonne numérique, ou utilisez `type = "table"` |
| `A map plot places points by lat and lng; it takes no x` | Une carte géographique n'a pas d'axes : donnez `lat` et `lng`, ou laissez-les aux noms de colonnes |
| `width is how many of the dashboard's 12 columns the plot spans` | Écrivez un nombre entier de 1 à 12 |
| `query "q" reads $chanel, but no filter block is named "chanel"` | Corrigez le nom, ou ajoutez le bloc `filter` |
| `filter "f" picks on plot "p", a line; a value is picked on a bar or table plot` | Pointez le filtre vers un graphique en barres ou un tableau |
| `a dashboard query must be a single read-only statement` | Déplacez les écritures vers l'éditeur SQL, ou nommez les valeurs d'un `PIVOT` imbriqué avec `IN` ; voir [Règles SQL](#sql-rules) |
| `Unknown block: "card"; a card is a plot: plot "x" { type = "card" … }` | Chaque panneau est un bloc plot, cartes et panneaux de texte compris |
| `"minutes" is a SQL keyword, so as a column alias it needs AS` | Écrivez `count(*) AS minutes`, ou mettez l'alias entre guillemets |
| `Unterminated heredoc: no line is exactly SQL` | Ajoutez le délimiteur de fermeture sur une ligne à lui |

## Modifier dans votre propre éditeur

`ducklocal lsp` est un serveur de langage pour les fichiers `.dash` : diagnostics pendant la frappe, complétion des types de blocs, des attributs, des types de graphique et des noms après `query.` et `plot.`, documentation au survol, et aller à la définition depuis une référence `query.name` ou `plot.name` vers son bloc. La configuration pour Neovim et VS Code est dans le [guide de la CLI](cli.md#edit-a-dashboard-spec-with-lsp).
