---
title: SQL pour les agents IA sur des données locales | DuckLocal CLI
description: Laissez les agents IA inspecter les schémas et interroger des fichiers locaux avec une requête DuckDB SQL unique et une sortie JSON bornée.
image: https://ducklocal.app/og-image.jpg?v=2
language: fr
---

# Laissez les agents IA interroger vos données locales en SQL

**D’abord le schéma. Une seule requête. Une sortie structurée.**

DuckLocal offre à 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 n’est nécessaire.

## D’abord découvrir, ensuite interroger

1. **Cartographier le schéma.** `ducklocal schema ./data/` renvoie 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.** Exécutez une seule requête SQL avec une petite limite. Vérifiez le code de sortie et le champ `truncated` du JSON.
3. **Calculer en SQL.** Effectuez les filtres, les jointures et les agrégations dans DuckDB plutôt que d’additionner un aperçu partiel dans le contexte de l’agent.

```bash
ducklocal schema ./data/
ducklocal schema sales.csv --stats
ducklocal query --sql "SELECT channel, sum(revenue) FROM 'sales.csv' GROUP BY channel"
```

Chaque appel de `query` crée une connexion dédiée, vérifie qu’il n’y a qu’une seule requête SQL et écrit un résultat lisible par machine sur stdout. Les erreurs sont du JSON sur stderr avec un code de sortie non nul.

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

```text

# 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`](https://github.com/JetSquirrel/DuckLocal/tree/main/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 :

```text
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.

```text

# 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 →](https://ducklocal.app/docs/fr/cli#install-the-official-skill)

## 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](https://ducklocal.app/docs/fr/cli#query-options)

```bash
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 sortie bornée et explicite

La limite par défaut est de 1 000 lignes, avec un budget de 2 000 000 de cellules. DuckLocal lit une ligne de plus pour déterminer si le résultat a été écourté.

L’enveloppe JSON contient :

- des colonnes et des lignes typées
- `row_count`
- `truncated`
- `elapsed_ms`

Le code de sortie 2 signale des arguments invalides ; le code 1 un échec d’exécution. `--format md` affiche le même résultat sous forme de tableau Markdown lisible par un humain.

## Compétence d’agent officielle

La compétence 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. Elle s’installe pour Claude Code depuis l’application, ou sert de brief à un autre agent.

Un agent peut confier du travail à l’application de bureau ouverte avec `ducklocal open`, puis lire les onglets visibles et les aperçus de résultats avec `ducklocal open --state`.

## Limite de sécurité

DuckLocal ne téléverse pas les fichiers locaux vers un service DuckLocal, mais ce n’est pas un bac à sable de sécurité. Le mode base de données en lecture seule n’empêche pas un SQL d’écrire d’autres fichiers ou d’accéder au réseau.

Autorisez les chemins de sortie, les écrasements, les modifications de la base, l’installation d’extensions et l’accès externe avant l’exécution.

## Liens

- [Télécharger DuckLocal](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [Référence complète de la CLI](https://ducklocal.app/docs/fr/cli)
- [Installer la compétence officielle](https://ducklocal.app/docs/fr/cli#install-the-official-skill)
- [Analyse de données locales](https://ducklocal.app/fr/use-cases/local-data-analysis/)
- [Ce que les tableaux de bord Claude m’ont appris sur DuckLocal](https://ducklocal.app/fr/blog/claude-dashboards-ducklocal/)
- [DuckDB GUI](https://ducklocal.app/fr/use-cases/duckdb-gui/)
- [Visionneuse Parquet](https://ducklocal.app/fr/use-cases/parquet-viewer/)
- [Interroger un CSV avec SQL](https://ducklocal.app/fr/use-cases/query-csv-with-sql/)
- [Tableaux de bord SQL](https://ducklocal.app/fr/use-cases/sql-dashboards/)
- [DuckLocal ou DBeaver](https://ducklocal.app/fr/compare/ducklocal-vs-dbeaver/)

Source: https://ducklocal.app/fr/use-cases/ai-agent-sql/
