Aller au contenu

Tableaux de bord (.dash) ​

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 pour demander des changements.

Un exemple complet ​

Ce tableau de bord interroge le fichier d'exemple du tutoriel. Téléchargez 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).

Les graphiques se disposent sur une grille de 12 colonnes : chacun occupe son width, 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 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 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 ​

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.

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, 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 enseigne cette boucle, si bien qu'un agent qui l'a n'a qu'à s'entendre dire « traite les commentaires de sales.dash ».

Nouveau dans 0.4.0

Un agent peut proposer un changement 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 ​

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 couvre les options. Ces indicateurs montrent l'activité locale ; ils n'envoient pas de travail à un agent.

Blocs ​

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.

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 ​

AttributRequisValeur
pathouiUn 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 ​

AttributRequisValeur
sqlouiUne instruction SQL en lecture seule, sous forme de heredoc ou de chaîne

Un bloc de requête contient sql et rien d'autre. Il peut lire $name pour un filtre.

plot ​

AttributPourValeur
typetous, requis"line", "bar", "stacked_bar", "area", "scatter", "pie", "heatmap", "histogram", "map", "timeline", "table", "card" ou "text" — une chaîne entre guillemets
querytous sauf text, requisUne référence à un bloc de requête : query.by_channel
xgraphiques, requisLa 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
ygraphiques, requisLa colonne à tracer ; doit être numérique. La taille des parts d'un pie. Un histogram et un timeline n'en prennent pas
seriesline, bar, stacked_bar, area, scatter, heatmap, timelineUne colonne dont les valeurs séparent les lignes en une série chacune ; les lignes d'un heatmap ; les couloirs d'un timeline
titletousUn titre pour le graphique, sous forme de chaîne entre guillemets ; l'étiquette d'une carte
widthtousCombien des 12 colonnes de la grille le graphique occupe, 1–12. Par défaut 12, ou 3 pour une carte
valuecardLa colonne à afficher, de la première ligne. Par défaut : la première colonne
notecardDu texte sous la valeur : une chaîne entre guillemets, ou un nom de colonne nu à lire sur la première ligne
tonecard"accent", "good", "warning" ou "critical" ; colore le filet supérieur et la valeur
formatgraphiques et cardCe que sont les nombres : voir Formats de nombres et variation. Un map ou un table n'en prend pas
deltacardUne colonne numérique portant la variation, affichée sous la valeur
delta_formatcardUn format pour la variation. Par défaut : celui de la carte
down_is_goodcardtrue rend une baisse verte et une hausse rouge, pour les coûts, la latence ou le churn
descriptiontous, 0.4.0+Ce que le graphique montre et comment le lire ; apparaît au survol d'un ⓘ à côté du titre
texttextLe texte du corps, en chaîne ou en heredoc ; fournissez title, text, ou les deux, sans query
captiontimelineLa colonne qui dit ce que chaque événement était, écrite sous son point quand elle tient et au survol
lat, lngmapColonnes 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
colormapUne colonne pour colorer les points ; omise, une est choisie quand une colonne de texte n'a que peu de valeurs
sizemapUne colonne numérique pour dimensionner les points
size_scalemap"sqrt" (par défaut) ou "log", pour la façon dont size s'échelonne
tooltipmapUne 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 ​

AttributRequisValeur
plotouiLe graphique sur lequel un clic choisit une valeur : plot.revenue_by_channel. Un bar, un stacked_bar ou un table
columnpour un tableLa colonne dont la valeur est choisie. Pour un bar ou stacked_bar, son x quand elle est omise
multiplebar, stacked_bartrue 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 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 ​

TypeDessine
lineUne ligne par série, non remplie
areaUne aire remplie par série
barUne 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_barUne 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
heatmapx 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
histogramLes 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
scatterUn point par valeur, non reliés, une couleur par série
pieUne 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
textUn titre, un texte explicatif, ou les deux ; aucune requête ne s'exécute
mapUn point par ligne, à son lat et son lng ; voir Cartes géographiques
timelineUn é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
tableLe résultat de la requête en grille, colonnes dimensionnées à leur contenu ; cliquez un en-tête pour trier
cardUn 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.

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 ​

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 ​

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

ValeurSe 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 ​

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 ​

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) ; 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 ​

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.

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 ​

FormeExempleServent à
Chaîne"Revenue by channel"type, title, path, size_scale, tone, note littéral, text, noms de colonnes entre guillemets, sql court
Heredoc<<SQL … SQLsql, text
Référencequery.daily, plot.revenue_by_channelle query d'un graphique, le plot d'un filtre
Nom nuchannelattributs de colonne
Nombre6width
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 ​

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 ​

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 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 ​

LimiteCe qui se passe
12 séries par graphiqueLes séries suivantes sont omises, et un avis dit combien il y en avait
1 500 points par sérieLes points sont moyennés par classes pour tenir
200 barresLes barres suivantes sont omises
8 parts de diagramme circulaireLes plus petites se replient en une seule part « autre »
200 colonnes de heatmap, 12 lignesLes colonnes et les lignes suivantes sont omises
5–40 classes d'histogrammeEnviron √lignes classes, chacune de 1, 2, 2,5 ou 5 × une puissance de dix de large
20 000 points de carteLes points suivants sont omis, et un avis le dit
12 couloirs, 1 000 événements par timelineLes é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 ​

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 donne les détails.

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.

Messages courants ​

MessageCorrectif
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, textUtilisez l'un des types listés
plot block "p" requires yTout type de graphique a besoin d'un y ; table, map, card et text non
plot "p" draws query "q", which the file does not defineAjoutez le bloc de requête, ou corrigez le nom dans query = query.…
query names a query block: query = query.some_nameL'attribut query prend une référence, pas une chaîne
plot "p" draws y = "channel" (VARCHAR), which is not numericPointez y vers une colonne numérique, ou utilisez type = "table"
A map plot places points by lat and lng; it takes no xUne 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 plotPointez le filtre vers un graphique en barres ou un tableau
a dashboard query must be a single read-only statementDéplacez les écritures vers l'éditeur SQL, ou nommez les valeurs d'un PIVOT imbriqué avec IN ; voir Règles SQL
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 SQLAjoutez 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.

Publié sous licence Apache-2.0.