---
title: SQL per agenti AI sui dati locali | CLI di DuckLocal
description: Consenti agli agenti AI di ispezionare gli schemi e interrogare file locali con SQL DuckDB a singola istruzione e output JSON limitato.
image: https://ducklocal.app/og-image.jpg?v=2
language: it
---

# Lascia che gli agenti AI interroghino i dati locali con SQL

**Prima lo schema. Una sola istruzione. Output strutturato.**

DuckLocal offre a Claude Code, Codex, Cursor e ad altri agenti di programmazione un flusso di lavoro DuckDB headless per dati CSV, Parquet, JSON e DuckDB. Non richiede automazione della GUI, server di database o API personalizzate.

## Prima scopri, poi interroga

1. **Mappa lo schema.** `ducklocal schema ./data/` restituisce relazioni, espressioni `FROM` pronte per le query, colonne e tipi. I cataloghi grandi restituiscono un riepilogo con suggerimenti per approfondire.
2. **Anteprima entro limiti definiti.** Esegui una sola istruzione SQL con un limite ridotto. Controlla lo stato di uscita e il campo JSON `truncated`.
3. **Calcola in SQL.** Esegui filtri, join e aggregazioni in DuckDB invece di sommare un'anteprima parziale nel contesto dell'agente.

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

Ogni invocazione di `query` crea una connessione dedicata, verifica che ci sia esattamente un'istruzione SQL e scrive un risultato leggibile dalla macchina su stdout. Gli errori sono JSON su stderr con un codice di uscita diverso da zero.

## Configuralo in Claude Code, Codex o Cursor

Ogni agente ha bisogno di due cose: il comando `ducklocal` nel suo `PATH` e le istruzioni per usarlo. Entrambe arrivano da **Command line & AI…** nell’app (il pulsante con il robot nella barra del titolo, o il menu DuckLocal).

### Claude Code: installa la skill

Fai clic su **Install command**, poi su **Add to Claude Code**. La skill viene scritta in `~/.claude/skills/ducklocal`, dove Claude Code la trova in ogni progetto. Quando una richiesta corrisponde, Claude Code carica la skill e segue il flusso «prima lo schema» senza che tu debba dirglielo.

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

Per usare la skill in un solo progetto, copia [`skills/ducklocal`](https://github.com/JetSquirrel/DuckLocal/tree/main/skills/ducklocal) nella cartella `.claude/skills/` di quel progetto.

### Codex: incolla le istruzioni in AGENTS.md

Fai clic su **Install command**, poi su **Copy brief**, e incolla le istruzioni in `AGENTS.md` nella radice del progetto. Codex legge quel file all’inizio di ogni sessione. Le istruzioni, in breve:

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

Se la tua versione di Codex supporta le skill, puoi invece copiare gli stessi `SKILL.md` e `references/cli.md` nella sua cartella delle skill.

### Cursor: salva le istruzioni come regola di progetto

Fai clic su **Install command**, poi su **Copy brief**, e salva le istruzioni come regola di progetto, ad esempio `.cursor/rules/ducklocal.mdc`. L’agente di Cursor conosce così il comando ogni volta che lavora in quel progetto. Il suo strumento di terminale deve avere il permesso di eseguire `ducklocal`: consenti `schema` e `query`, e continua ad approvare tutto ciò che scrive file.

```text

# Then ask the agent:
Compare monthly order counts in exports/orders-*.csv
for 2025 and 2026 with DuckLocal.
```

Il testo esatto delle istruzioni viene dall’app installata e contiene il percorso completo del comando se `ducklocal` non è ancora nel `PATH`. [Installa ed esamina la skill →](https://ducklocal.app/docs/it/cli#install-the-official-skill)

## Perché l’agente non deve sommare l’anteprima

Un agente che legge righe e le somma nel proprio contesto risponde in base a ciò che gli è stato mostrato. Con un file da 1,2 milioni di righe e il limite predefinito di 1.000 righe, vede meno dello 0,1% dei dati. Il totale che riporta può sembrare plausibile ed essere comunque sbagliato di ordini di grandezza.

DuckLocal rende visibile questo vuoto invece di tacerlo. Un’anteprima riporta `"truncated": true`, e `total_rows` mostra quante righe aveva davvero il risultato. Quando il conteggio si ferma prima, `total_rows_exact` è `false` e il totale è solo un limite inferiore. La skill dice all’agente di trattarlo come un campione e di restituire il calcolo a DuckDB, che legge ogni riga.

[Limiti, budget e formato di output](https://ducklocal.app/docs/it/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}
```

## Output limitato ed esplicito

Il limite predefinito è 1.000 righe, con un budget di 2.000.000 di celle. DuckLocal legge una riga in più per stabilire se il risultato è stato troncato.

La struttura JSON include:

- colonne e righe tipizzate
- `row_count`
- `truncated`
- `elapsed_ms`

Il codice di uscita 2 indica argomenti non validi; il codice di uscita 1 indica un'esecuzione non riuscita. `--format md` rende lo stesso risultato come tabella Markdown, leggibile da una persona.

## Skill ufficiale per agenti

La skill open source insegna a un agente a ispezionare lo schema, visualizzare un campione limitato, aggregare in SQL, verificare il troncamento e rispondere in base ai valori restituiti. Può essere installata per Claude Code dall'app oppure usata come brief per un altro agente.

Un agente può passare il lavoro all'app desktop in esecuzione con `ducklocal open`, poi leggere le schede visibili e le anteprime dei risultati con `ducklocal open --state`.

## Confine di sicurezza

DuckLocal non carica i file locali su un servizio DuckLocal, ma non è una sandbox di sicurezza. La modalità di database in sola lettura non impedisce a SQL di scrivere altri file o di accedere alla rete.

Autorizza percorsi di output, sovrascritture, modifiche al database, installazione di estensioni e accesso esterno prima dell'esecuzione.

## Link

- [Scarica DuckLocal](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [Riferimento completo sulla CLI](https://ducklocal.app/docs/it/cli)
- [Installa la skill ufficiale](https://ducklocal.app/docs/it/cli#install-the-official-skill)
- [Analisi dei dati locali](https://ducklocal.app/it/use-cases/local-data-analysis/)
- [Cosa mi hanno insegnato le Claude Dashboards su DuckLocal](https://ducklocal.app/it/blog/claude-dashboards-ducklocal/)
- [DuckDB GUI](https://ducklocal.app/it/use-cases/duckdb-gui/)
- [Visualizzatore Parquet](https://ducklocal.app/it/use-cases/parquet-viewer/)
- [Interrogare CSV con SQL](https://ducklocal.app/it/use-cases/query-csv-with-sql/)
- [Dashboard SQL](https://ducklocal.app/it/use-cases/sql-dashboards/)
- [DuckLocal vs DBeaver](https://ducklocal.app/it/compare/ducklocal-vs-dbeaver/)

Fonte: https://ducklocal.app/it/use-cases/ai-agent-sql/
