CLI IA et compétence officielle
Pour la vue d'ensemble orientée tâches, voir Du SQL pour les agents IA sur des données locales. Cette page est la référence complète des commandes et de la sortie.
Fonctionner sans fenêtre
ducklocal --help liste dix sous-commandes :
| Commande | Effet |
|---|---|
ducklocal query | Exécute une instruction SQL et affiche le résultat en JSON |
ducklocal schema | Liste ce qu'il y a à interroger, avec les colonnes ; --stats pour les statistiques de colonnes d'une relation |
ducklocal open | Affiche du SQL, un tableau de bord ou des données dans la fenêtre en cours ; --state relit ce qu'elle affiche |
ducklocal check | Valide un tableau de bord .dash |
ducklocal metrics | Liste les métriques d'un modèle sémantique ; compile ou query pour les compiler ou les interroger |
ducklocal comments | Lit et répond aux commentaires de relecture laissés sur un tableau de bord |
ducklocal propose | Suggère une modification du tableau de bord, que la personne relit et applique |
ducklocal project | Vérifie un dossier d'analyse portable et ce dont il a besoin ; relink corrige les chemins déplacés |
ducklocal session | Relit comment une analyse est arrivée là où elle est |
ducklocal presence | Montre qui travaille sur un tableau de bord ouvert et où une modification va atterrir |
ducklocal lsp, le serveur de langage que les éditeurs lancent pour les fichiers .dash, et ducklocal profile, l'ancien alias de schema --stats, fonctionnent toujours mais sont omis de --help.
propose, project et session, ainsi que les options --restricted, --wait et --if-revision, sont arrivés en 0.4.0 et sont décrits dans Flux de travail d'agent. metrics et --format html sont plus récents que 0.4.1 : ils sont sur la branche main et sortiront avec la prochaine version. metrics est décrit dans Métriques sémantiques.
ducklocal query exécute du SQL sans initialiser l'interface, l'historique, les fichiers enregistrés, les paramètres de langue ni la connexion globale de l'interface. Chaque appel crée une connexion dédiée. Lancer DuckLocal sans commande — ou seulement avec des chemins de fichiers, des dossiers et des motifs glob — ouvre l'interface habituelle. Pour ouvrir dans l'interface un chemin dont le nom correspond à une commande (query, schema, open, check, metrics, comments, propose, project, session, presence, profile ou lsp), préfixez-le par ./, par exemple ./query.
Obtenir la commande
DuckLocal fonctionne sur macOS 12 et versions ultérieures (Apple silicon), Windows (x86_64) et Linux (x86_64). La CLI s'exécute directement depuis l'exécutable de l'application, vous n'avez donc pas besoin d'installer un binaire DuckDB CLI séparé.
Le plus rapide pour l'ajouter à votre PATH est de passer par l'application (0.1.1 et versions ultérieures) : ouvrez Ligne de commande et IA… — le bouton robot de la barre de titre, ou le menu DuckLocal — puis cliquez sur Installer la commande. La même boîte de dialogue installe la compétence pour les agents IA ; voir Installer la compétence officielle. Si vous sautez l'installation, appelez l'exécutable là où il se trouve :
# macOS
/Applications/DuckLocal.app/Contents/MacOS/ducklocal --help
# Linux: wherever you extracted the tarball
./ducklocal-linux-x86_64/ducklocal --help
# Windows (PowerShell): wherever you extracted the zip
.\ducklocal-windows-x86_64\ducklocal.exe --helpDepuis un dépôt source, cargo build --locked construit ./target/debug/ducklocal. Les exemples ci-dessous supposent que ducklocal est dans votre PATH. Les anciennes versions peuvent ne pas avoir query ; vérifiez d'abord --help. Le support JSON et Parquet est intégré, pas téléchargé au moment de la requête.
Options de requête
ducklocal --help
ducklocal --version
ducklocal query --help
ducklocal query --sql "SELECT 1 AS n"
ducklocal query --sql "SELECT 1 AS n" --format md
ducklocal query --sql-file analysis.sql --limit 100
ducklocal query --sql-file - < analysis.sql
ducklocal query --database warehouse.duckdb --sql "SHOW TABLES"- Il faut exactement l'un de
--sql SQLet--sql-file FILE. Les fichiers doivent être en UTF-8 ;-lit stdin. Le SQL doit contenir exactement une instruction. Le parseur de DuckDB le vérifie avant d'ouvrir la base cible ou d'exécuter quoi que ce soit ; les commentaires, les points-virgules entre guillemets et le point-virgule final passent. Les scripts sont refusés, pas exécutés partiellement. --database PATHouvre un fichier existant, en lecture seule par défaut. Omettez-la pour une base en mémoire neuve.--read-writeexige--databaseet autorise explicitement les écritures et la création d'une base (pas des dossiers parents). Une erreur de base ne retombe jamais sur la mémoire. Quand DuckDB refuse un fichier, le message d'erreur commence par la raison que DuckLocal lit dans l'en-tête du fichier — écrit par un DuckDB plus récent, fichier de l'époque v0.9, fichier SQLite, ou pas une base du tout — et par ce qu'il faut lancer à la place (pour un fichier plus récent, la copieATTACH … (STORAGE_VERSION)/COPY FROM DATABASEà faire dans cette version ; pour SQLite, l'ATTACHqui le lit), avant le message de DuckDB lui-même.--limit Nest un entier positif, vaut 1000 par défaut et plafonne les lignes renvoyées. Un budget de 2 000 000 de cellules s'applique aussi. Une fois le plafond atteint, la CLI continue à compter jusqu'à 100 000 lignes de plus sans encoder leurs valeurs, en rapportanttotal_rowsettotal_rows_exact. Cela limite la sortie, pas le calcul ni la mémoire : un tri ou une agrégation peut encore traiter toute l'entrée. Une erreur d'exécution rencontrée après le plafond de sortie fait quand même échouer la commande.--format json(par défaut) est le contrat décrit plus bas.--format mdrend le même résultat en tableau Markdown, pour un document ou un agent qui le lit.--format htmlle rend en une seule page web autonome ; voir Sortie HTML. Rien d'autre ne change : le même SQL, les mêmes limites, les mêmes erreurs.- Les options répétées ou inconnues, les valeurs manquantes, le SQL vide et les limites invalides sont des erreurs. Les options prennent une valeur séparée, pas
--flag=value. Les chemins relatifs se résolvent par rapport au répertoire de travail du processus, pas au répertoire du fichier SQL. Mettez les chemins du shell entre guillemets ; dans le SQL, doublez les apostrophes ('O''Brien.csv'). Les identifiants SQL utilisent des guillemets doubles.
Le mode lecture seule n'est pas un bac à sable de fichiers ni de réseau. Un SQL comme COPY peut écrire des fichiers même quand la base est en lecture seule. Autorisez les chemins de sortie, les écrasements, les modifications de la base, l'installation d'extensions et les accès externes avant exécution. DuckLocal n'installe pas d'extensions automatiquement et ne réessaie pas les opérations. Un INSTALL/LOAD explicite reste possible avec autorisation ; les extensions installées peuvent se charger automatiquement. Une commande échouée peut déjà avoir eu des effets de bord (par exemple avant une erreur de sortie) ; inspectez la destination avant de réessayer.
Sortie Markdown
--format md est un rendu, pas un second contrat : les valeurs sont celles que contient le JSON, écrites comme la grille de résultats les affiche.
| Valeur | Rendu |
|---|---|
NULL | NULL |
| entier, décimal, flottant | les chiffres que la valeur porte, exactement — un DECIMAL(38,10) garde son échelle, NaN/inf/-inf sont écrits en toutes lettres |
DATE | YYYY-MM-DD |
TIMESTAMP | YYYY-MM-DD HH:MM:SS[.fffffffff], avec la fraction seulement quand la valeur en a une, et autant de chiffres qu'elle en a. Aucun fuseau n'est ajouté ; --format json garde le compte brut |
TIME | HH:MM:SS[.ffffff] |
INTERVAL | comme DuckDB l'écrit : 1 month 2 days 00:00:00.000003 |
BLOB, GEOMETRY | 0x00ff, abrégé par … quand c'est long |
LIST, STRUCT, MAP | [1, 2], {x: 1}, abrégé par … au-delà de 120 caractères |
Un | dans une cellule est échappé et un saut de ligne devient <br>, si bien qu'une valeur ne peut pas casser le tableau qui la contient. Un résultat sans ligne est suivi de _0 rows._, et un résultat écourté par --limit ou le budget de cellules par _Truncated at 2 of 5000 rows, so this is not the whole answer._ (of at least … au-delà du comptage de 100 000 lignes) — un aperçu ne doit pas se lire comme une réponse complète. Les erreurs ne changent pas : JSON sur stderr, stdout vide.
Sortie HTML
ducklocal query --sql "SELECT * FROM 'sales.csv'" --format html > sales.html--format html écrit les mêmes valeurs que --format md sous forme d'une seule page web :
- Le nombre de lignes et de colonnes, le temps écoulé et le SQL à l'origine du résultat, replié.
- Les noms des colonnes avec leurs types. Les nombres sont alignés à droite et les
NULLsont signalés. - Cliquez sur un en-tête pour trier ; les
NULLrestent à la fin. Tapez dans le champ de filtre pour ne garder que les lignes qui correspondent. - Un résultat tronqué par
--limitou par le budget de cellules l'indique, comme en Markdown.
Le style et le script sont intégrés et la page ne télécharge rien : elle s'ouvre depuis le disque et peut être publiée telle quelle, par exemple sur GitHub Pages. Chaque cellule est échappée en HTML.
Cartographier ce qui est interrogeable
ducklocal schema répond en un appel à « qu'y a-t-il, et quelles sont ses colonnes ? », là où DESCRIBE répond une relation à la fois. C'est la première chose qu'un agent devrait lancer.
ducklocal schema ./data/ # files, folders, globs
ducklocal schema --database warehouse.duckdb # tables and views
ducklocal schema warehouse.duckdb --table orders # one relation, whole
ducklocal schema ./logs/ --full # everything, however largeLes PATH s'étendent comme un fichier déposé sur la fenêtre : les fichiers de données d'un dossier récursivement (les fichiers cachés sont ignorés, 256 au plus), les correspondances d'un glob, et un fichier de base comme s'il était passé avec --database. Un objet JSON revient :
{"detail":"full","relations":[{"name":"data/orders.csv","kind":"file","from":"'data/orders.csv'","rows":null,"column_count":2,"path":"data/orders.csv","columns":[{"name":"channel","type":"VARCHAR"},{"name":"amount","type":"BIGINT"}]}],"without_columns":0}| Champ | Sens |
|---|---|
name | Le chemin d'un fichier tel que donné (relatif au répertoire de travail quand il est en dessous), ou le nom d'une table tel que le SQL l'atteint sur cette connexion : nu dans le schéma par défaut, schema.table ailleurs |
kind | file, glob, table, view ou workbook |
from | Le SQL qui le lit, prêt à suivre FROM : un chemin entre guillemets, ou un identifiant entre guillemets quand il en faut un |
rows | L'estimation du catalogue pour une table, exacte pour Parquet (d'après sa fin de fichier), null quand il faudrait un scan pour le savoir — CSV, JSON, vues |
column_count, columns | Les colonnes telles que DuckDB les décrit |
files | Pour un glob : combien de fichiers il correspond |
Un glob dont toutes les correspondances ont un seul format est une seule relation, lue comme le fait un source de .dash (ducklocal schema 'logs/*.csv') ; --stats le profile comme tel. Un glob sur des formats mélangés, et un dossier, listent leurs fichiers un par un.
Un petit catalogue revient en entier ("detail": "full"). Au-delà de 12 relations ou 400 colonnes, c'est un résumé ("detail": "summary") à la place. Les 5 relations qui ont le plus de lignes gardent leurs colonnes ; les autres listent nom, type, lignes et nombre de colonnes, et without_columns les compte. Pour en obtenir plus, hint nomme les deux moyens : --table NAME pour une relation (appariée par son nom, son nom de table nu ou le nom d'un fichier) et --full pour tout. Un classeur est listé avec ses sheets et sans colonnes, puisqu'il n'a pas de fonction de table ; --stats lit sa première feuille. Un PATH qui n'existe pas, ou un --table qui ne nomme rien, sort en code 2.
Le texte compressé en gzip, comme .json.gz et .csv.gz, est ici un fichier de données, tout comme pour les blocs source et la fenêtre. Un fichier dont les enregistrements tiennent dans une seule liste — {"Records": [...]} de CloudTrail, par exemple — revient avec un hint : le SQL qui lit ces enregistrements comme des lignes, puisque la ligne et la colonne uniques ne décrivent sinon que l'enveloppe.
Explorer et convertir des fichiers
Après avoir confirmé que le fichier existe réellement :
ducklocal query --sql "DESCRIBE SELECT * FROM 'sales.csv'"
ducklocal query --sql "SELECT * FROM 'sales.csv'" --limit 20
ducklocal query --sql "SELECT sum(amount) AS total FROM 'sales.csv'"
# Only after authorizing this output path:
ducklocal query --sql "COPY (SELECT * FROM 'sales.csv') TO 'sales.parquet' (FORMAT PARQUET)"
ducklocal query --sql "SELECT count(*), sum(amount) FROM 'sales.parquet'"
ducklocal query --sql "DESCRIBE SELECT * FROM 'events.json'"Ne supposez pas que amount existe : lancez d'abord ducklocal schema ou DESCRIBE. Calculez les agrégats complets en SQL plutôt que de sommer un aperçu tronqué. Les appels CLI ne partagent pas les vues enregistrées de l'interface, ni les tables en mémoire les uns des autres. Persistez explicitement quand il le faut :
# These are separate statements and separate invocations, with explicit write permission.
ducklocal query --database warehouse.duckdb --read-write --sql "CREATE TABLE sales AS SELECT * FROM 'sales.csv'"
ducklocal query --database warehouse.duckdb --sql "SELECT count(*) FROM sales"Un conflit de verrou de base est une erreur. Fermez l'autre écrivain (y compris l'interface), ou utilisez une copie autorisée ; ne supprimez jamais les fichiers de verrou et ne créez pas silencieusement une autre base.
JSONL et JSON imbriqué
read_ndjson_objects est le lecteur des JSON délimités par retours à la ligne (un objet par ligne, .jsonl/.ndjson) ; read_json/read_json_auto lisent des documents JSON (un tableau ou un objet unique). Nommez le lecteur explicitement pour un fichier JSONL plutôt que de compter sur la détection automatique. json_extract_string(col, '$.a.b[0].c') parcourt un chemin imbriqué — clés d'objet et index de tableau — et répond en VARCHAR :
ducklocal query --sql "SELECT json_extract_string(event, '$.payload.items[0].sku') AS sku, count(*) AS n FROM read_ndjson_objects('events.jsonl') GROUP BY 1 ORDER BY n DESC"Utilisez plutôt json_extract quand la feuille n'est pas une chaîne et que vous la voulez en JSON.
Statistiques de colonnes
ducklocal schema --stats répond aux questions qui décident d'un graphique, d'une échelle et d'un format de nombre, avant que quoi que ce soit ne se construise dessus. DESCRIBE dit qu'une colonne est un DOUBLE ; ses statistiques disent qu'elle utilise deux décimales, que sa plus grande valeur vaut mille fois sa médiane et que ses dates sautent onze jours au milieu.
ducklocal schema sales.csv --stats
ducklocal schema ./exports/ --table orders.parquet --stats
ducklocal schema --database warehouse.duckdb --table "my orders" --stats--stats profile une seule relation : la seule que les arguments nomment, ou celle que --table choisit — deux ou plus sans --table, c'est le code 2, avec un hint qui le dit. Il ne se combine pas avec --full. ducklocal profile TARGET [--database PATH] vient des versions précédentes et produit le même rapport ; il fonctionne toujours.
La relation est un fichier de données — csv, tsv, txt, parquet, json, ndjson, jsonl — ou un classeur (xlsx, xls, xlsb, ods ; sa première feuille est importée comme table TEMP et profilée), ou, avec --database, un nom de table ou de vue. Un nom avec un point est lu comme schema.table et chaque partie est mise entre guillemets, si bien qu'un nom avec un espace ou une majuscule fonctionne tel qu'écrit. Une relation qui ne nomme rien est une erreur d'argument (code 2), pas une erreur SQL.
Un objet JSON revient : target, relation (le SQL sur lequel les statistiques ont tourné), row_count, elapsed_ms, et columns dans l'ordre propre à la relation. Par colonne :
| Champ | Sens |
|---|---|
name, type | tels que DESCRIBE les rapporte |
nulls | lignes où la colonne vaut NULL |
distinct | exact, pas estimé |
unique | présent et true quand distinct égale row_count |
min, max | en texte, pour qu'un DECIMAL garde ses chiffres |
decimals | chiffres après la virgule que la colonne utilise réellement, ce qui n'est pas son échelle déclarée |
median | une valeur que la colonne contient, pas une interpolation entre deux d'entre elles |
max_over_median | combien de fois la plus grande valeur dépasse la médiane — le nombre qui décide d'un axe linéaire ou logarithmique |
covered_days, span_days, missing_days | jours que la colonne nomme, jours entre ses extrémités, et la différence : 0 est une série continue, tout le reste est un trou qu'une ligne tracerait par-dessus |
decimals, median et max_over_median apparaissent sur les colonnes numériques ; les champs de jours sur les dates et les horodatages. Les colonnes LIST, STRUCT, MAP et UNION ne rapportent que nulls — min et max n'y sont pas définis.
Une colonne de texte qui contient des nombres et un mot court, comme NA de R, rapporte aussi null_marker et null_marker_rows. Le rapport ajoute alors un hint nommant l'appel read_csv qui lit la colonne comme des nombres.
Les statistiques sont exactes et lisent toute la relation : elles coûtent donc un scan complet. --limit ne s'applique pas : le profil d'un échantillon n'est pas un profil.
Montrer le travail dans la fenêtre en cours
ducklocal open remet quelque chose à la fenêtre DuckLocal déjà en cours — en démarrant une s'il n'y en a pas — et la met au premier plan. C'est ainsi qu'un agent met son travail devant une personne, là où elle peut continuer à partir de lui :
ducklocal open --title "Revenue by channel" --run --sql "SELECT channel, sum(amount) AS total FROM 'orders.csv' GROUP BY 1"
ducklocal open sales.dash # a dashboard tab
ducklocal open ./data/ --sql-file analysis.sql
echo "SELECT 42" | ducklocal open --sql-file - --no-launch- Les PATH s'ouvrent comme un fichier déposé sur la fenêtre : un fichier
.dashen onglet, un fichier de base DuckDB comme base de la fenêtre, des fichiers de données, des dossiers et des globs attachés en vues. Les PATH relatifs se résolvent par rapport au répertoire de la commande. Une demande qui arrive pendant que la fenêtre démarre encore attend que son ouverture initiale soit terminée. --sqlou--sql-file(-lit stdin) ouvre un nouvel onglet de requête, intitulé--title.--runl'exécute une fois les PATH attachés.--no-launchéchoue avec le typenot_runningau lieu de démarrer une fenêtre — pour une machine où une fenêtre apparaissant sans qu'on l'ait demandé serait malvenue.
Le succès affiche {"delivered": true, "launched": BOOL} : une livraison, pas un résultat. Ce qui s'ouvre tourne dans la session propre à la fenêtre — sa connexion, ses vues attachées, son historique — et toute erreur s'affiche là, pas sur stdout. Code 2 pour les arguments ; 1 avec le type not_running (aucune fenêtre joignable), refused (la fenêtre a rejeté la demande) ou launch.
La fenêtre écoute sur un port de bouclage. Elle écrit le port et un jeton aléatoire dans un fichier que seul votre compte peut lire (voir Paramètres et données de l'app) ; un autre utilisateur de la machine, ou une page web visant localhost, ne peut pas l'atteindre.
Lire ce que la fenêtre affiche
ducklocal open --state va dans l'autre sens : il n'ouvre rien, ne démarre jamais de fenêtre et affiche ce que montre la fenêtre en cours — ainsi un agent peut reprendre là où une personne s'est arrêtée, au lieu de lui demander de coller sa requête.
ducklocal open --state
ducklocal open --state sales.dash
ducklocal open --state --active{"database":":memory:","attached":[{"path":"/Users/me/data/orders.csv","name":"orders","rows":224}],"active_tab":1,"tabs":[{"kind":"query","title":"Query 1","active":false,"sql":"SELECT …","result":{"status":"rows","columns":[…],"row_count":5,"truncated":false,"preview":[["Web","132771.24"],…],"sql":"SELECT …","elapsed_ms":4}},{"kind":"dashboard","title":"sales","active":true,"path":"/Users/me/data/sales.dash","unsaved":false,"dashboard":{"running":false,"error":null,"stale":null,"plots":[…],"filters":[{"name":"channel","plot":"revenue_by_channel","column":"channel","picked":true,"value":"Web"}]}}]}databaseest le fichier de base ouvert, ou":memory:";attachedliste les fichiers que la fenêtre a enregistrés comme vues, avec lenamede la vue. Une requête CLI ne peut pas lire ces vues — utilisez lepath.- Un onglet requête a
sql, le texte de l'éditeur, qu'il ait été exécuté ou non, etresult:statusvautempty,running,rows,affected,failed,explainouprofile. Pour des lignes :columns,row_count,truncated,preview(les 20 premières lignes telles que la grille les montre, en chaînes),elapsed_mset lesqlqui les a produites ; pouraffected,countetelapsed_ms; pour un échec,error. - Une fois que la personne a choisi des colonnes dans l'onglet Graphique, un résultat a aussi
chart:type,x,y,split, etdash, un blocqueryet un blocplotqui dessinent le même graphique dans un tableau de bord. explainest ce qu'affiche Expliquer :plan, la sortie d'EXPLAINde DuckDB sous forme de liste de lignes de texte, etelapsed_ms.profileest ce qu'affiche Profiler (voir Éditeur SQL) :plan, l'arbre d'opérateurs qu'EXPLAIN ANALYZEa mesuré, sous forme de liste de racines, chacune{operator, seconds, rows, estimated, children}—secondsest le temps propre de l'opérateur, ses enfants exclus,rowsce qu'il a produit,estimatedl'estimation de l'optimiseur pourrows(nullquand le plan n'en donne pas),childrenla même forme à nouveau.operator_secondsest la somme du temps propre de chaque opérateur, ce à quoi les parts s'additionnent, pas le temps réel écoulé ;elapsed_msest l'exécution entière.- Un onglet tableau de bord a
path,unsaved, etdashboard: son chemincomments_file, sesplots(nom, type, titre, requête, lignes,open_comments, etfailurequand l'un ne peut pas se dessiner) et sesfiltersavec ce que chacun a choisi :picked,value(la première valeur),values(toutes les valeurs choisies, dans l'ordre) etmultiple.value: nullavecpicked: truesignifie que la valeur NULL a été choisie.
Utilisez --state sales.dash pour ne garder que les onglets montrant ce tableau de bord, ou --state --active pour seulement l'onglet actif. Un chemin qui n'est pas ouvert renvoie le code 1, type not_open, avec les tableaux de bord ouverts dans le hint. active_tab est l'index de l'onglet actif dans les tabs renvoyés, ou null s'il n'en fait pas partie ; database et attached restent inclus.
--state accepte soit un PATH .dash, soit --active, pas les deux. --no-launch est accepté et ne change rien. Les autres options, dont --sql et --run, sont invalides (code 2). Code 1 avec le type not_running quand aucune fenêtre n'est ouverte, et timeout quand elle ne répond pas en 5 secondes.
Vérifier une spec de tableau de bord
Le format lui-même — blocs, attributs, types de graphique, règles SQL et messages courants — est décrit dans Tableaux de bord (.dash) ; cette section couvre la commande.
Un fichier .dash déclare un tableau de bord comme Terraform déclare de l'infrastructure — des requêtes et des graphiques en blocs, des références entre eux — plutôt que de le scripter. Une personne ou un agent peut facilement l'écrire et le comparer dans un diff.
query "latency" {
sql = <<SQL
SELECT timestamp, service, avg(latency) AS latency
FROM logs
GROUP BY timestamp, service
SQL
}
plot "latency" {
type = "line"
query = query.latency
x = timestamp
y = latency
series = service
}ducklocal check dashboard.dash
ducklocal check dashboard.dash --database warehouse.duckdb
ducklocal check dashboard.dash --summaryUn bloc source nomme des fichiers de données, relatifs au fichier .dash, que les requêtes lisent, et un bloc view contient du SQL que plusieurs requêtes partagent. Un bloc query contient un attribut sql — une instruction en lecture seule, sous forme de heredoc ou de chaîne. SELECT, WITH, les requêtes commençant par FROM, VALUES, SHOW, DESCRIBE, SUMMARIZE et PIVOT sont acceptés ; tout ce qui pourrait écrire — DDL, DML, COPY, ATTACH, INSTALL — est un diagnostic, et l'interface refuse de l'exécuter, parce que les requêtes d'un tableau de bord tournent à chaque ouverture du fichier. Un bloc plot contient type (l'un de line, bar, stacked_bar, area, scatter, pie, heatmap, histogram, map, timeline, table, card, text), query (une référence comme query.latency vers un bloc de requête du même fichier), ses colonnes, et éventuellement title et width. Un bloc filter rend un graphique en barres ou un tableau cliquable — une valeur, ou plusieurs avec multiple = true sur un graphique en barres — et une requête lit le choix comme $name. # et // commentent jusqu'à la fin de la ligne. Tableaux de bord (.dash) donne chaque attribut.
Un graphique text est l'exception : il contient title, text, ou les deux, et ne prend pas de query. Les cartes peuvent aussi utiliser note et tone ; voir Cartes et panneaux de texte.
D'abord les vérifications statiques : le SQL de chaque requête passe par le vrai parseur DuckDB sur une connexion jetable, comme query le valide avant d'exécuter, et chaque $name est confronté aux blocs de filtre — le SQL est analysé, puis exécuté, avec chaque $name à TRUE, ce que le tableau de bord exécute avant tout choix.
Puis chaque requête s'exécute, exactement comme l'ouverture du tableau de bord l'exécuterait — en lecture seule, avec ses sources, par le même chemin de code et le même budget de lignes — et les colonnes de chaque graphique sont vérifiées contre les colonnes que la requête renvoie réellement : un y non numérique est une erreur pour tous les types de graphique, comme des coordonnées ou un size non numériques pour une carte, ou une column de filtre que la requête de son graphique ne renvoie pas.
- Sans
--database, les requêtes tournent en mémoire, ce qui suffit à un tableau de bord construit sur ses propres fichierssource. Une requête qui lit une table qu'aucune source ne définit peut viser une base qui n'a pas été fournie à la vérification : elle est listée sousunresolved(requête, ligne, raison) plutôt que mise en échec, et les colonnes de ses graphiques ne sont pas vérifiées. - Avec
--database PATH(fichier existant, en lecture seule), elles tournent sur cette base. Passez-la dès que les requêtes lisent les tables d'une base : tout ce qui est sousunresolvedn'a pas été vérifié.
Chaque requête qui lit un filtre est aussi liée à une valeur choisie, sans exécuter cette variante. Cela détecte une colonne de filtre absente d'une requête consommatrice, même quand la version initiale $name = TRUE fonctionne. Un filtre doit aussi référencer une colonne renvoyée par son graphique de sélection.
Exécuter, et pas seulement planifier, a son importance : certaines défaillances, comme un cast que la construction ne sait pas faire ou une valeur qui ne se convertit pas, n'apparaissent qu'une fois des lignes lues, et une vérification qui les laisserait passer livrerait un tableau de bord incapable de se dessiner. Les requêtes tournent en entier, donc une vérification sur une grande base prend aussi longtemps que l'ouverture du tableau de bord.
Le succès est un objet JSON listant les sources du fichier (avec chaque chemin resolved), les vues, les requêtes (avec leurs colonnes de résultat et rows, combien chacune a renvoyé sans aucun choix, plus truncated: true quand le budget de lignes du tableau de bord l'a coupée), les filtres (avec les queries qui lisent chacun d'eux), les graphiques, unresolved et empty — les requêtes qui ont tourné et n'ont renvoyé aucune ligne. Une requête vide passe toutes les autres vérifications, mais c'est en général une regex, un filtre ou une jointure qui n'a rien trouvé : regardez chacune. Avec --summary, le succès tient en une ligne JSON compacte :
{"file":"sales.dash","ok":true,"sources":1,"views":0,"queries":3,"filters":1,"plots":6,"unresolved":[],"empty":[]}Les cinq champs de blocs sont des comptes ; unresolved liste les requêtes qui n'ont pas pu être vérifiées, et empty celles qui n'ont renvoyé aucune ligne.
Un bloc fautif est écarté tandis que les blocs valides continuent d'être validés. Les erreurs de spec et les échecs de requête sont rassemblés dans la même exécution, un file:line: message chacun. S'il existe un diagnostic de spec, la sortie est en code 2 avec le type spec ; si seule l'exécution ou la liaison SQL échoue, le code est 1 avec le type sql. Les échecs de base et d'E/S sortent aussi en 1. --summary ne cache pas les diagnostics.
Le même fichier s'ouvre comme onglet de tableau de bord dans l'interface — ducklocal dashboard.dash, ducklocal open dashboard.dash, ou en le faisant glisser sur la fenêtre — avec les graphiques sur une grille de 12 colonnes et un graphique qui ne peut pas se dessiner affichant la raison sur place. Voir Tableaux de bord (.dash).
Métriques d'un modèle sémantique
ducklocal metrics # ./model.ossie.yaml
ducklocal metrics compile --metric error_count,event_count --by events.ip
ducklocal metrics query --metric event_count --by events.event_time:day \
--views reports/investigation.dash --restricted --allow-read dataducklocal metrics lit un modèle Apache Ossie, model.ossie.yaml, et liste ses métriques et ses champs. compile affiche l'unique SELECT DuckDB qui répond à une requête, sans lire de données ; query l'exécute comme le fait ducklocal query, avec un objet semantic qui indique le SQL et le sha256 du modèle. Une requête à laquelle le modèle ne peut pas répondre exactement est refusée, code de sortie 2, avec un kind comme metric_fanout. Métriques sémantiques décrit le format du modèle, chaque option et chaque refus.
Revoir les commentaires d'un tableau de bord
On relit un tableau de bord en commentant ses graphiques dans la fenêtre — survolez un graphique, cliquez sur la bulle (voir Revoir avec des commentaires). ducklocal comments est le côté agent : il lit les fils et y répond, sans fenêtre.
ducklocal comments sales.dash [--all]
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" [--resolve]
ducklocal comments sales.dash --resolve c1
ducklocal comments sales.dash --reopen c1
ducklocal comments sales.dash --add revenue_by_channel --text "Is this net of refunds?"- Sans action, affiche les fils ouverts :
{file, comments_file, open, threads}.--allinclut ceux qui sont résolus. - Chaque fil a
id,plot, et ce dont l'agent a besoin pour le retrouver dans la spec :plot_title,plot_query, etplot_lines, la première et la dernière ligne du blocplot(nullquand la spec ne s'analyse pas).plot_missingvauttruequand aucun graphique de ce nom ne reste. Puisresolved, etcomments, chacun avecauthor(userouagent), sur un commentaire d'agent sonname(le nom que montrepresence),textetat(RFC 3339, heure locale). --reply ID --text TEXTajoute la réponse de l'agent. Une réponse à un fil résolu le rouvre, sauf si--resolveest aussi donné.--resolve IDet--reopen IDchangent l'état d'un fil ;--add PLOT --text TEXTen ouvre un, signé comme l'agent.- Le numéro d'un fil vaut son identifiant :
--reply 1signifiec1.--addrefuse un graphique que la spec n'a pas (code 2), et le hint liste ses graphiques. - Une action affiche
{thread}, tel que modifié.
Les fils sont conservés à côté de la spec, dans FILE.comments.json. Une fenêtre en cours remarque un changement en moins d'une seconde et l'affiche sur le graphique. Un identifiant de fil inconnu sort en code 2, avec un hint pour lister les fils ; un fichier de spec inexistant sort en code 1.
Une relecture, de bout en bout : lire les fils ouverts, modifier la spec, lancer ducklocal check, puis répondre à chaque fil avec ce qui a changé et le --resolve. Utilisez --reply sans --resolve pour poser une question à la personne.
Montrer l'activité de l'agent
check et comments informent automatiquement une fenêtre en cours du tableau de bord sur lequel l'agent travaille. presence peut annoncer une modification avant qu'elle n'ait lieu :
ducklocal presence sales.dash --doing editing --plot revenue_by_channel,daily_revenue
ducklocal presence sales.dash --doing reading --agent "Analyst"
ducklocal presence sales.dash --doing idle--doingacceptereading,editingouidle(doneest un alias d'idle).--plotprend des noms de graphique séparés par des virgules. Avecediting, les nouveaux noms sont permis et apparaissent comme des espaces réservés. Avecreadingouidle, un nom inconnu sort en code 2.- Le nom affiché vient de
--agent, puisDUCKLOCAL_AGENT, puis de l'environnement d'agent détecté (Claude, Codex, Cursor ou Gemini), et à défautAgent. - La sortie est
{delivered}. Sans fenêtre en cours, la sortie est{"delivered":false}, sans erreur et sans lancer de fenêtre.
Le nom reste dans le coin du tableau de bord tant que des commandes gardent la session active. Cliquez dessus pour le journal d'activité. Trente secondes de silence ou --doing idle terminent la session ; les graphiques modifiés et ajoutés restent marqués jusqu'à ce qu'ils soient vus, et les avis de graphique supprimé restent jusqu'à ce qu'ils soient écartés. Voir Voir un agent au travail.
Modifier une spec de tableau de bord avec LSP
ducklocal lsp est un serveur Language Server Protocol pour les fichiers .dash, sur stdio, que les éditeurs lancent. Il donne à tout éditeur compatible LSP ce que l'éditeur de spec de l'interface a :
- Diagnostics : ceux que rapporte
check, publiés à chaque ouverture et modification (synchronisation du document entier, tous en sévérité Error — ce sont des fautes, pas du style). - Complétion : types de blocs, noms d'attributs, types de graphique et les noms après
query.etplot., chacun avec une édition de texte qui remplace le mot en cours de frappe. - Survol : documentation des blocs, attributs et références.
- Aller à la définition : depuis une référence
query.nameouplot.namevers le nom de son bloc.
Avec --database PATH, le SQL de chaque requête est en plus validé par le vrai parseur DuckDB, comme le fait check --database.
Pointez le support LSP générique de votre éditeur vers ducklocal lsp pour les fichiers *.dash — la commande ne prend aucun argument de document ; l'éditeur lui parle sur stdio. Dans Neovim (0.10+) :
vim.api.nvim_create_autocmd("FileType", {
pattern = "dash",
callback = function(event)
vim.lsp.start({
name = "ducklocal",
cmd = { "ducklocal", "lsp" },
root_dir = vim.fs.dirname(vim.api.nvim_buf_get_name(event.buf)),
})
end,
})Dans VS Code, n'importe quelle extension LSP générique fait de même avec la commande ducklocal, les arguments ["lsp"], un sélecteur de document dash. Codes de sortie : 0 après un shutdown/exit propre, 1 quand le client disparaît sans lui, 2 pour une ligne de commande fautive ou une poignée de main de protocole échouée.
Contrat JSON
Les requêtes réussies écrivent exactement un objet JSON sur stdout, suivi d'un saut de ligne :
{"columns":[{"name":"n","type":"Int32"}],"rows":[[1]],"row_count":1,"truncated":false,"total_rows":1,"total_rows_exact":true,"elapsed_ms":1}columns et chaque ligne préservent l'ordre des colonnes et les noms de colonnes en double. type est la représentation de débogage Arrow, pas le nom du type SQL DuckDB d'origine (par exemple HUGEINT et DECIMAL peuvent partager un porteur Arrow). row_count compte les lignes renvoyées. total_rows compte les lignes produites, y compris celles comptées après le plafond de sortie ; total_rows_exact: false signifie que le comptage s'est arrêté après jusqu'à 100 000 lignes supplémentaires, donc ce total est une borne inférieure. Aucun des deux comptes n'est un compte de lignes affectées. elapsed_ms mesure la préparation, l'exécution et l'encodage des lignes, pas le chargement des fichiers ni l'établissement de la connexion. Les résultats à zéro ligne gardent leurs métadonnées. DDL/DML exposent le résultat DuckDB réel, y compris les colonnes Count : INSERT/COPY renvoient couramment [[N]] ; CREATE TABLE ne renvoie couramment aucune ligne. Ils ne sont pas classés d'après le premier mot-clé SQL.
Encodages de cellules :
| Valeur SQL | Encodage JSON |
|---|---|
| NULL | null (jamais la chaîne "NULL") |
| Booléen, flottant fini | booléen/nombre JSON |
| Entier dans ±9 007 199 254 740 991 | nombre JSON |
| Entier plus grand, y compris HUGEINT/UHUGEINT | {"encoding":"integer","value":"9007199254740992"} |
| Décimal | {"encoding":"decimal","value":"123.450"} avec le texte décimal exact |
| Texte, énumération | chaîne JSON |
| Blob, géométrie | {"encoding":"hex","value":"00ff"} ; octets en minuscules, la géométrie utilise WKB |
| Date | {"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"} ; jours depuis 1970-01-01 |
| Horodatage | {"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"} ; compte signé depuis l'époque Unix ; l'unité peut aussi être Second/Millisecond/Microsecond |
| Heure | {"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"} ; compte depuis minuit |
| Intervalle | {"encoding":"interval","months":1,"days":2,"nanos":"3000"} |
| NaN, infini positif/négatif | {"encoding":"float","value":"NaN"} / "inf" / "-inf" |
| Liste, tableau | tableau JSON, encodé récursivement (y compris les valeurs nulles imbriquées) |
| Structure | {"encoding":"struct","fields":[["name",VALUE],...]} |
| Map | {"encoding":"map","entries":[[KEY,VALUE],...]} ; pas un objet JSON, donc les clés gardent leurs types |
| Union | {"encoding":"union-value","value":VALUE} ; valeur active seulement, l'étiquette de membre n'est pas conservée |
Les value temporelles sont des comptes exacts, donc aucune précision fractionnaire n'est perdue ; les sentinelles d'infini de date et d'horodatage restent des comptes bruts. À côté de chacune, iso donne la même valeur en texte ISO 8601 pour la lecture, avec autant de chiffres de fraction que l'unité en tient. Un horodatage issu d'une colonne avec fuseau horaire (métadonnées Arrow) est un instant UTC, et son iso finit par Z. --format md rend aussi les dates et les horodatages lisibles. Comme le wrapper Arrow de DuckDB épinglé ne distingue pas les HUGEINT, UHUGEINT et DECIMAL(38,0) imbriqués, les occurrences non nulles produisent une erreur claire au lieu de changer silencieusement de signe ou de précision. Convertissez explicitement ces champs en VARCHAR dans le SQL. Les types inconnus non pris en charge produisent aussi une erreur ; ne prenez pas une erreur pour un résultat vide. L'encodage Union est une représentation de la valeur active, pas un aller-retour sans perte d'une union.
Les erreurs écrivent un objet JSON sur stderr, laissant stdout vide :
{"error":{"kind":"argument","message":"Unknown query option: --limt","hint":"Did you mean --limit?"}}hint est là quand l'étape suivante est connue, dans les termes de cette CLI : l'option qu'un nom mal orthographié visait, --read-write pour une écriture refusée sur une base en lecture seule, ducklocal schema pour une table qui n'existe pas, TRY_CAST pour une valeur qui ne se convertit pas, le découpage d'un script qui contient plus d'une instruction, ou AS pour un mot-clé utilisé comme alias de colonne nu (SELECT count(*) AS minutes, ou mettez-le entre guillemets). Un agent devrait agir dessus avant de réécrire le SQL. Il est absent quand il n'y a rien à ajouter au message de DuckDB, comme pour une erreur de syntaxe.
Codes de sortie : 0 succès, 2 arguments ou nombre d'instructions invalides, 1 échec SQL, de base, d'E/S ou de sortie. Les types d'erreur sont argument, sql, database, io, output, spec pour check, et not_running, not_open, refused, timeout ou launch pour open. Vérifiez le code de sortie avant d'analyser stdout et inspectez truncated avant de déclarer une réponse complète. L'aide et la version sont des exceptions en texte brut. Les échecs de transport, comme un tube stdout fermé, ne peuvent pas garantir un flux de sortie vide ou complet.
Installer la compétence officielle
La compétence enseigne à un agent les habitudes qui gardent ses réponses honnêtes : inspecter le schéma, prévisualiser un échantillon borné, calculer les agrégats en SQL, vérifier truncated et répondre à partir des valeurs renvoyées. Elle couvre l'inspection de schéma, les statistiques de colonnes, les conversions, les requêtes de base, les tableaux de bord .dash et leurs commentaires de relecture, ainsi que la remise du travail à la fenêtre et sa relecture ; elle ne fournit ni navigation S3, ni commandes propres au spatial, ni mémoire de session, ni serveur MCP.
Depuis l'application. Ouvrez Ligne de commande et IA… (le bouton robot de la barre de titre, ou le menu DuckLocal) :
- Installer la commande met
ducklocaldans votrePATH, pour que le shell d'un agent puisse la lancer. - Ajouter à Claude Code écrit la compétence dans
~/.claude/skills/ducklocal, où Claude Code la trouve dans chaque projet. Seuls les deux fichiers de la compétence sont écrits ; tout le reste de ce dossier est conservé. Quand une mise à jour de DuckLocal livre une compétence plus récente, la boîte de dialogue propose Mettre à jour la compétence. - Copier le résumé copie une courte explication pour tout autre agent — Codex, Cursor, une fenêtre de chat — nommant la commande et son usage.
À la main. La compétence est skills/ducklocal. Pour l'ajouter à un seul projet à la place (exemple pour Claude Code) :
# Run from the DuckLocal checkout; replace the destination with your project.
mkdir -p /path/to/your-project/.claude/skills
cp -R skills/ducklocal /path/to/your-project/.claude/skills/Inspectez d'abord une destination existante plutôt que d'écraser des modifications locales. Les autres agents peuvent utiliser le même SKILL.md plus references/cli.md dans le répertoire de compétences qu'ils prennent en charge.
