Laissez les agents IA interroger vos données locales en 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.

D’abord découvrir, ensuite interroger

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.

  1. Cartographier le schéma

    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.

  2. Prévisualiser dans les limites

    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.

  3. Calculer la réponse en SQL

    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.

La mise en place dans Claude Code, Codex ou Cursor

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).

Claude Code : installer le skill

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.

Codex : coller les instructions dans AGENTS.md

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.

Cursor : enregistrer les instructions comme règle de projet

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.

Pourquoi l’agent ne doit pas additionner l’aperçu

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.

Limites, budgets et format de sortie

Terminal
$ 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}

Une commande, une requête SQL

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.

Lire le contrat des requêtes

Terminal
$ 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}

Une petite interface aux contrats explicites

ducklocal schema ./data/

Découvrir les relations

Listez les fichiers, les tables, les vues et leurs colonnes avant d’écrire du SQL.

ducklocal schema sales.csv --stats

Profiler une relation

Obtenez les valeurs nulles exactes, les valeurs distinctes, les plages, les médianes et la couverture des dates.

ducklocal query --sql "…"

Exécuter une seule requête

Recevez du JSON typé par défaut, ou un tableau Markdown avec --format md.

ducklocal open --title "…" --run --sql "…"

Passer le travail à une personne

Ouvrez une requête dans l’application de bureau quand le résultat demande une relecture ou un examen plus poussé.

Une sortie qui signale à l’agent quand elle est incomplète

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é.

  • Colonnes et lignes typées dans une enveloppe JSON stable
  • Champs explicites row_count, truncated et elapsed_ms
  • Code de sortie 2 pour des arguments invalides ; code 1 pour un échec d’exécution
  • Erreurs JSON sur stderr, stdout laissé vide
  • Sortie Markdown pour des rapports lisibles par un humain

Enseigner le flux de travail, pas seulement la commande

La 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 →

Une CLI locale, pas un service cloud caché ni un bac à sable

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.

  • Autorisez les chemins de sortie, les écrasements et les modifications de la base
  • Autorisez l’installation d’extensions et l’accès externe
  • Inspectez une destination avant de relancer une écriture qui a échoué
  • N’utilisez --read-write que pour une modification volontaire de la base
  • Consultez ducklocal --help avant de vous appuyer sur une commande

Questions sur le SQL pour les agents IA

Comment un agent IA interroge-t-il des données locales avec DuckLocal ?
L’agent exécute 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.
La CLI renvoie-t-elle des données complètes par défaut ?
Non. La sortie des requêtes est volontairement bornée : la limite par défaut est de 1 000 lignes et un budget de 2 000 000 de cellules s’applique aussi. La réponse JSON indique si elle a été tronquée. Les agrégations complètes doivent être calculées dans le SQL.
DuckLocal peut-il exécuter des scripts SQL pour un agent ?
Chaque appel de 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.
DuckLocal fonctionne-t-il avec Codex et Cursor, ou seulement avec Claude Code ?
Tout agent capable de lancer une commande de terminal peut l’utiliser. Claude Code reçoit le skill officiel en un clic depuis l’application. Pour Codex, Cursor et les autres agents, le bouton Copy brief de l’application produit des instructions à coller dans AGENTS.md ou dans une règle de projet.
DuckLocal est-il un serveur MCP ou un bac à sable de sécurité ?
Non. DuckLocal fournit une interface en ligne de commande et une compétence d’agent facultative, pas un serveur MCP ni un bac à sable de sécurité. Les écritures potentielles, l’installation d’extensions et l’accès externe demandent toujours une autorisation normale.

Donnez à votre agent un flux de travail SQL qui commence par le schéma

Installez DuckLocal, ajoutez la commande à votre PATH et commencez par demander ce que contiennent réellement les données.