ducklocal schema ./data/Découvrir les relations
Listez les fichiers, les tables, les vues et leurs colonnes avant d’écrire du SQL.
Donnez à Claude Code, Codex, Cursor et aux autres agents de codage un flux de travail DuckDB sans interface pour vos données CSV, Parquet, JSON et DuckDB. Aucune automatisation d’interface, aucun serveur de base de données et aucune API personnalisée.
La CLI affiche du JSON par défaut et utilise des codes de sortie explicites pour les erreurs d’arguments, de SQL et d’entrées-sorties.
Le flux de travail officiel évite à un agent de deviner les noms de colonnes ou de prendre un aperçu partiel pour l’ensemble du jeu de données.
Exécutez ducklocal schema ./data/ pour obtenir les relations, les expressions FROM prêtes à l’emploi, les colonnes et les types. Les catalogues volumineux renvoient un résumé avec des pistes pour approfondir.
Utilisez une seule requête SQL et un petit --limit pour inspecter des lignes représentatives. Vérifiez le code de sortie de la commande et le champ truncated du JSON.
Exécutez les filtres, les jointures et les agrégations dans DuckDB plutôt que d’additionner un aperçu tronqué dans le contexte de l’agent. Ne renvoyez que les éléments dont la réponse a besoin.
Chaque agent a besoin de deux choses : la commande ducklocal dans son PATH, et des instructions pour l’utiliser. Les deux viennent de Command line & AI… dans l’application (le bouton robot de la barre de titre, ou le menu DuckLocal).
Cliquez sur Install command, puis sur Add to Claude Code. Le skill est écrit dans ~/.claude/skills/ducklocal, où Claude Code le trouve dans tous les projets. Quand une demande lui correspond, Claude Code charge le skill et suit le flux « schéma d’abord » sans qu’on le lui dise.
# In any project, ask in plain language:
Which channel brought in the most revenue in data/sales.csv?
Use DuckLocal and show me the query.
Pour réserver le skill à un seul projet, copiez skills/ducklocal dans le .claude/skills/ de ce projet.
Cliquez sur Install command, puis sur Copy brief, et collez les instructions dans AGENTS.md à la racine de votre projet. Codex lit ce fichier au début de chaque session. Les instructions, en version courte :
DuckLocal is installed on this machine. Its command, ducklocal, runs DuckDB SQL over local CSV, TSV, Parquet, JSON and Excel files and databases, and prints JSON. - Start with `ducklocal --help` for the options. - See what there is to query, with columns, before writing SQL: `ducklocal schema ./data/` (or `--database file.duckdb`). - Profile what you will chart or summarize: `ducklocal schema data.csv --stats`. - Compute totals in SQL, not from sample rows; check `truncated` in the output. - It opens data read-only by default. Answer from the values it returns, and say which query produced them.
Si votre version de Codex prend en charge les skills, vous pouvez à la place copier les mêmes SKILL.md et references/cli.md dans son répertoire de skills.
Cliquez sur Install command, puis sur Copy brief, et enregistrez les instructions comme règle de projet, par exemple .cursor/rules/ducklocal.mdc. L’agent de Cursor connaît alors la commande dès qu’il travaille dans ce projet. Son outil de terminal doit avoir le droit d’exécuter ducklocal : autorisez schema et query, et continuez à approuver tout ce qui écrit des fichiers.
# Then ask the agent:
Compare monthly order counts in exports/orders-*.csv
for 2025 and 2026 with DuckLocal.
Le texte exact des instructions vient de l’application installée, et il contient le chemin complet de la commande si ducklocal n’est pas encore dans le PATH. Installer et inspecter le skill →
Un agent qui lit des lignes et les additionne dans son propre contexte répond à partir de ce qu’on lui a montré. Avec un fichier de 1,2 million de lignes et la limite par défaut de 1 000 lignes, il voit moins de 0,1 % des données. Le total annoncé peut sembler plausible et être faux de plusieurs ordres de grandeur.
DuckLocal rend cet écart visible plutôt que silencieux. Un aperçu indique "truncated": true, et total_rows montre combien de lignes le résultat comptait vraiment. Quand le comptage s’arrête tôt, total_rows_exact vaut false et le total n’est qu’une borne inférieure. Le skill dit à l’agent de traiter cela comme un échantillon et de renvoyer le calcul à DuckDB, qui lit chaque ligne.
$ ducklocal query --sql \ "SELECT * FROM 'events.csv'" {..., "row_count":1000, "truncated":true, "total_rows":101000, "total_rows_exact":false} $ ducklocal query --sql \ "SELECT count(*) AS n, sum(amount) AS total FROM 'events.csv'" {..., "rows":[[1204381,8812094.5]], "truncated":false}
Chaque appel crée une connexion DuckDB dédiée, vérifie que l’entrée contient exactement une requête et écrit un résultat lisible par machine sur stdout. Les erreurs sont du JSON sur stderr avec un code de sortie non nul.
$ ducklocal query --sql \ "SELECT channel, round(sum(revenue), 2) AS revenue FROM 'sales.csv' GROUP BY channel ORDER BY revenue DESC" {"columns":[...], "rows":[["Mobile app",290549.76],...], "row_count":4, "truncated":false, "elapsed_ms":14}
ducklocal schema ./data/Listez les fichiers, les tables, les vues et leurs colonnes avant d’écrire du SQL.
ducklocal schema sales.csv --statsObtenez les valeurs nulles exactes, les valeurs distinctes, les plages, les médianes et la couverture des dates.
ducklocal query --sql "…"Recevez du JSON typé par défaut, ou un tableau Markdown avec --format md.
ducklocal open --title "…" --run --sql "…"Ouvrez une requête dans l’application de bureau quand le résultat demande une relecture ou un examen plus poussé.
La limite de retour par défaut est de 1 000 lignes, avec un budget supplémentaire de 2 000 000 de cellules. DuckLocal lit une ligne de plus pour déterminer si la réponse a été écourtée et l’expose via truncated.
Les requêtes comme GROUP BY, ORDER BY et les agrégations sont tout de même calculées sur l’intégralité de l’entrée avant de renvoyer leur résultat borné.
row_count, truncated et elapsed_msLa compétence DuckLocal open source apprend à un agent à inspecter le schéma, à prévisualiser un échantillon borné, à agréger en SQL, à vérifier la troncature et à répondre à partir des valeurs renvoyées. Installez-la pour Claude Code depuis l’application, ou copiez le même brief dans un autre agent de codage.
Installer et inspecter la compétence
À lire : ce que les tableaux de bord Claude m’ont appris sur DuckLocal →
DuckLocal ne téléverse pas vos fichiers locaux vers un service DuckLocal, mais il ne prétend pas pour autant qu’un SQL arbitraire est sans danger. Le mode base de données en lecture seule n’est pas un bac à sable pour le système de fichiers ni pour le réseau : un SQL comme COPY, l’installation d’extensions ou un accès externe explicite peuvent avoir des effets de bord.
--read-write que pour une modification volontaire de la baseducklocal --help avant de vous appuyer sur une commandeBesoin plutôt du flux de travail visuel ? Voir l’analyse de données locales dans l’application de bureau →
ducklocal schema pour découvrir les relations et les colonnes, puis ducklocal query avec une seule requête SQL. La commande renvoie du JSON structuré par défaut, sans ouvrir la fenêtre de bureau ni démarrer un serveur.ducklocal query accepte exactement une requête SQL. Les scripts à plusieurs requêtes sont refusés plutôt qu’exécutés partiellement, ce qui rend chaque appel d’outil plus facile à inspecter.AGENTS.md ou dans une règle de projet.À voir aussi : DuckDB GUI · Visionneuse Parquet · Interroger un CSV avec SQL · Tableaux de bord SQL · DuckLocal ou DBeaver
Installez DuckLocal, ajoutez la commande à votre PATH et commencez par demander ce que contiennent réellement les données.