ducklocal schema ./data/Scopri le relazioni
Elenca file, tabelle, viste e le loro colonne prima di scrivere 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.
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.
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.
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.
Esegui filtri, join e aggregazioni in DuckDB invece di sommare un'anteprima troncata nel contesto dell'agente. Restituisci solo le evidenze necessarie alla risposta.
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).
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.
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.
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.
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 →
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.
$ 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}
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.
$ 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/Elenca file, tabelle, viste e le loro colonne prima di scrivere SQL.
ducklocal schema sales.csv --statsOttieni nulli esatti, valori distinti, intervalli, mediane e copertura delle date.
ducklocal query --sql "…"Ricevi JSON tipizzato per impostazione predefinita, oppure una tabella Markdown con --format md.
ducklocal open --title "…" --run --sql "…"Apri una query nell'app desktop quando il risultato richiede revisione o ulteriori esplorazioni.
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.
row_count, truncated ed elapsed_msLa 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.
Leggi: cosa mi hanno insegnato le Claude Dashboards su DuckLocal →
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.
--read-write solo per una modifica intenzionale del databaseducklocal --help prima di affidarti a un comandoPreferisci il flusso di lavoro visivo? Scopri l'analisi dei dati locali nell'app desktop →
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.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.AGENTS.md o in una regola di progetto.Correlati: DuckDB GUI · Visualizzatore Parquet · Interrogare CSV con SQL · Dashboard SQL · DuckLocal vs DBeaver
Installa DuckLocal, aggiungi il comando al PATH e inizia chiedendo cosa c'è davvero nei dati.