Lascia che gli agenti AI interroghino i dati locali con SQL

Offri 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 servono automazione della GUI, server di database o API personalizzate.

La CLI stampa JSON per impostazione predefinita e usa codici di uscita espliciti per errori di argomenti, SQL e I/O.

Prima scopri, poi interroga

Il flusso di lavoro ufficiale impedisce a un agente di indovinare i nomi delle colonne o di trattare un'anteprima parziale come l'intero dataset.

  1. Mappa lo schema

    Esegui ducklocal schema ./data/ per ottenere 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

    Usa una sola istruzione SQL e un --limit ridotto per ispezionare righe rappresentative. Controlla lo stato di uscita del comando e il campo JSON truncated.

  3. Calcola la risposta in SQL

    Esegui filtri, join e aggregazioni in DuckDB invece di sommare un'anteprima troncata nel contesto dell'agente. Restituisci solo le evidenze necessarie alla risposta.

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.

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

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.

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

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

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}

Un comando, un'istruzione SQL

Ogni invocazione crea una connessione DuckDB dedicata, verifica che l'input contenga esattamente un'istruzione e scrive un risultato leggibile dalla macchina su stdout. Gli errori sono JSON su stderr con un codice di uscita diverso da zero.

Leggi il contratto delle query

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

Un'interfaccia piccola con contratti espliciti

ducklocal schema ./data/

Scopri le relazioni

Elenca file, tabelle, viste e le loro colonne prima di scrivere SQL.

ducklocal schema sales.csv --stats

Analizza una relazione

Ottieni nulli esatti, valori distinti, intervalli, mediane e copertura delle date.

ducklocal query --sql "…"

Esegui una sola istruzione

Ricevi JSON tipizzato per impostazione predefinita, oppure una tabella Markdown con --format md.

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

Passa il lavoro a una persona

Apri una query nell'app desktop quando il risultato richiede revisione o ulteriori esplorazioni.

Un output che dice all'agente quando è incompleto

Il limite predefinito è 1.000 righe, con un budget aggiuntivo di 2.000.000 di celle. DuckLocal legge una riga in più per stabilire se la risposta è stata troncata e lo espone come truncated.

Query come GROUP BY, ORDER BY e le aggregazioni calcolano comunque sull'input completo prima di restituire il risultato limitato.

  • Colonne e righe tipizzate in una struttura JSON stabile
  • Campi espliciti row_count, truncated ed elapsed_ms
  • Uscita 2 per argomenti non validi; uscita 1 per errori di esecuzione
  • Errori JSON su stderr, con stdout vuoto
  • Output Markdown per report leggibili da una persona

Insegna il flusso di lavoro, non solo il comando

La skill open source di DuckLocal 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. Installala per Claude Code dall'app oppure copia lo stesso brief in un altro agente di programmazione.

Installa e ispeziona la skill

Leggi: cosa mi hanno insegnato le Claude Dashboards su DuckLocal →

Una CLI locale, non un servizio cloud nascosto o una sandbox

DuckLocal non carica i file locali su un servizio DuckLocal, ma non finge che SQL arbitrario sia innocuo. La modalità di database in sola lettura non è una sandbox del filesystem o della rete: SQL come COPY, l'installazione di estensioni o l'accesso esterno esplicito possono avere effetti collaterali.

  • Autorizza percorsi di output, sovrascritture e modifiche al database
  • Autorizza l'installazione di estensioni e l'accesso esterno
  • Ispeziona la destinazione prima di riprovare una scrittura non riuscita
  • Usa --read-write solo per una modifica intenzionale del database
  • Controlla ducklocal --help prima di affidarti a un comando

Domande su SQL per agenti AI

Come fa un agente AI a interrogare i dati locali con DuckLocal?
L'agente esegue ducklocal schema per scoprire relazioni e colonne, poi ducklocal query con una sola istruzione SQL. Il comando restituisce JSON strutturato per impostazione predefinita, senza aprire la finestra desktop né avviare un server.
La CLI restituisce dati completi per impostazione predefinita?
No. L'output delle query è volutamente limitato: il limite predefinito è 1.000 righe e si applica anche un budget di 2.000.000 di celle. La risposta JSON indica se è stata troncata. Le aggregazioni complete vanno calcolate in SQL.
DuckLocal può eseguire script SQL per un agente?
Ogni invocazione di ducklocal query accetta esattamente un'istruzione SQL. Gli script con più istruzioni vengono rifiutati invece di essere eseguiti parzialmente, il che rende più facile ispezionare ogni chiamata dello strumento.
DuckLocal funziona con Codex e Cursor, o solo con Claude Code?
Qualsiasi agente in grado di eseguire un comando da terminale può usarlo. Claude Code ottiene la skill ufficiale con un clic dall’app. Per Codex, Cursor e altri agenti, il pulsante Copy brief dell’app genera istruzioni da incollare in AGENTS.md o in una regola di progetto.
DuckLocal è un server MCP o una sandbox di sicurezza?
No. DuckLocal fornisce un'interfaccia a riga di comando e una skill per agenti opzionale, non un server MCP né una sandbox di sicurezza. Le potenziali scritture, l'installazione di estensioni e l'accesso esterno richiedono comunque la normale autorizzazione.

Dai al tuo agente un flusso di lavoro SQL che parte dallo schema

Installa DuckLocal, aggiungi il comando al PATH e inizia chiedendo cosa c'è davvero nei dati.