CLI di IA e skill ufficiale
Per la panoramica orientata alle attività, vedi SQL per agenti di IA sui dati locali. Questa pagina è il riferimento completo di comandi e output.
Esegui senza finestra
ducklocal --help elenca dieci sottocomandi:
| Comando | Cosa fa |
|---|---|
ducklocal query | Esegue un'istruzione SQL e stampa il risultato come JSON |
ducklocal schema | Elenca ciò che si può interrogare, con le colonne; --stats per le statistiche delle colonne di una relazione |
ducklocal open | Mostra SQL, una dashboard o dati nella finestra in esecuzione; --state rilegge cosa mostra |
ducklocal check | Valida una dashboard .dash |
ducklocal metrics | Elenca le metriche di un modello semantico; compile o query per compilarle o interrogarle |
ducklocal comments | Legge e risponde ai commenti di revisione che le persone hanno lasciato su una dashboard |
ducklocal propose | Propone una modifica a una dashboard perché la persona la riveda e la applichi |
ducklocal project | Controlla una cartella di analisi portabile e ciò di cui ha bisogno; relink sistema i percorsi spostati |
ducklocal session | Rilegge come un'analisi è arrivata dove è arrivata |
ducklocal presence | Mostra chi sta lavorando a una dashboard aperta e dove arriverà una modifica |
ducklocal lsp, il language server che gli editor avviano per i file .dash, e ducklocal profile, l'alias storico di schema --stats, funzionano ancora ma sono omessi da --help.
propose, project e session, e le opzioni --restricted, --wait e --if-revision, sono arrivati nella 0.4.0 e sono trattati in Flussi di lavoro per agenti. metrics e --format html sono successivi alla 0.4.1: sono sul branch main e arriveranno con la prossima versione. metrics è trattato in Metriche semantiche.
ducklocal query esegue SQL senza inizializzare la GUI, la cronologia, i file registrati, le impostazioni della lingua o la connessione globale della GUI. Ogni invocazione crea una connessione dedicata. Invocare DuckLocal senza comandi — o solo con percorsi di file, cartelle e pattern glob — apre la GUI normale. Per aprire nella GUI un percorso il cui nome coincide con un comando (query, schema, open, check, metrics, comments, propose, project, session, presence, profile o lsp), anteponi ./, per esempio ./query.
Ottieni il comando
DuckLocal supporta macOS 12+ su Apple silicon, Windows (x86_64) e Linux (x86_64). La CLI gira direttamente dall'eseguibile dell'applicazione, quindi non devi installare un binario della CLI di DuckDB separato.
Il modo più rapido per averla nel PATH è dall'app (0.1.1 e successive): apri Riga di comando e IA… — il pulsante del robot nella barra del titolo, o il menu DuckLocal — e fai clic su Installa comando. Lo stesso dialogo installa la skill per gli agenti di IA; vedi Installa la skill ufficiale. Se salti l'installazione, chiama l'eseguibile dove si trova:
# macOS
/Applications/DuckLocal.app/Contents/MacOS/ducklocal --help
# Linux: wherever you extracted the tarball
./ducklocal-linux-x86_64/ducklocal --help
# Windows (PowerShell): wherever you extracted the zip
.\ducklocal-windows-x86_64\ducklocal.exe --helpDa un checkout dei sorgenti, cargo build --locked compila ./target/debug/ducklocal. Gli esempi qui sotto danno per scontato che ducklocal sia nel tuo PATH. Le versioni più vecchie potrebbero non avere query; controlla prima --help. Il supporto JSON e Parquet è incluso, non viene scaricato al momento della query.
Opzioni di query
ducklocal --help
ducklocal --version
ducklocal query --help
ducklocal query --sql "SELECT 1 AS n"
ducklocal query --sql "SELECT 1 AS n" --format md
ducklocal query --sql-file analysis.sql --limit 100
ducklocal query --sql-file - < analysis.sql
ducklocal query --database warehouse.duckdb --sql "SHOW TABLES"- Si richiede esattamente uno tra
--sql SQLe--sql-file FILE. I file devono essere UTF-8;-legge da stdin. L'SQL deve contenere esattamente un'istruzione. Il parser di DuckDB lo valida prima di aprire il database di destinazione o eseguire qualcosa; i commenti, i punti e virgola tra virgolette e il punto e virgola finale funzionano. Gli script vengono rifiutati, non eseguiti parzialmente. --database PATHapre un file esistente, in sola lettura per impostazione predefinita. Omettilo per un nuovo database in memoria.--read-writerichiede--databasee consente esplicitamente scritture e la creazione di un database (non delle cartelle superiori). Gli errori del database non ripiegano mai sulla memoria. Quando DuckDB rifiuta un file, il messaggio di errore inizia con il motivo che DuckLocal legge dall'header del file — scritto da una DuckDB più recente, un file dell'epoca v0.9, un file SQLite o qualcosa che non è affatto un database — e con cosa eseguire invece (per un file più recente, la copiaATTACH … (STORAGE_VERSION)/COPY FROM DATABASEda fare in quella release; per SQLite, l'ATTACHche lo legge), prima del messaggio di DuckDB stesso.--limit Nè un intero positivo, vale 1000 per impostazione predefinita e limita le righe restituite. Si applica anche un budget di 2.000.000 di celle. Dopo il limite, la CLI continua a contare fino a 100.000 righe in più senza codificarne i valori, riportandototal_rowsetotal_rows_exact. Questo limita l'output, non il calcolo o la memoria: ordinamenti e aggregati possono comunque elaborare l'intero input. Un errore di esecuzione incontrato dopo il limite di output fa comunque fallire il comando.--format json(il valore predefinito) è il contratto qui sotto.--format mdrende lo stesso risultato come tabella Markdown, per un documento o per un agente che lo legge.--format htmllo rende come un'unica pagina web autonoma; vedi Output HTML. Nient'altro cambia: lo stesso SQL, gli stessi limiti, gli stessi errori.- Flag ripetuti o sconosciuti, valori mancanti, SQL vuoto e limiti non validi sono errori. Le opzioni usano valori separati, non
--flag=value. I percorsi relativi vengono risolti rispetto alla directory di lavoro del processo, non alla cartella del file SQL. Metti tra virgolette i percorsi della shell; dentro l'SQL, raddoppia gli apostrofi ('O''Brien.csv'). Gli identificatori SQL usano le virgolette doppie.
La sola lettura non è una sandbox del filesystem né della rete. SQL come COPY può scrivere file anche quando il database è in sola lettura. Autorizza i percorsi di output, le sovrascritture, le mutazioni del database, l'installazione di estensioni e l'accesso esterno prima dell'esecuzione. DuckLocal non installa estensioni automaticamente né ritenta operazioni. L'SQL esplicito INSTALL/LOAD resta possibile con autorizzazione; le estensioni installate possono caricarsi da sole. Un comando fallito può aver già prodotto effetti collaterali (per esempio prima di un errore di output); ispeziona la destinazione prima di riprovare.
Output Markdown
--format md è una rappresentazione, non un secondo contratto: i valori sono quelli che contiene il JSON, scritti come li mostra la griglia dei risultati.
| Valore | Reso come |
|---|---|
NULL | NULL |
| intero, decimale, float | le cifre che il valore porta, esattamente — un DECIMAL(38,10) conserva la sua scala, NaN/inf/-inf sono scritti per esteso |
DATE | YYYY-MM-DD |
TIMESTAMP | YYYY-MM-DD HH:MM:SS[.fffffffff], con la frazione solo quando il valore ne ha una, e con tante cifre quante ne ha. Non viene aggiunto alcun fuso orario; --format json conserva il conteggio grezzo |
TIME | HH:MM:SS[.ffffff] |
INTERVAL | come lo scrive DuckDB: 1 month 2 days 00:00:00.000003 |
BLOB, GEOMETRY | 0x00ff, eliso con … quando è lungo |
LIST, STRUCT, MAP | [1, 2], {x: 1}, eliso con … oltre 120 caratteri |
Un | in una cella viene escapato e un newline diventa <br>, così un valore non può rompere la tabella in cui si trova. A un risultato senza righe segue _0 rows._, e a un risultato tagliato da --limit o dal budget di celle segue _Truncated at 2 of 5000 rows, so this is not the whole answer._ (of at least … oltre il conteggio di 100.000 righe) — un'anteprima non dovrebbe leggersi come una risposta completa. Gli errori non cambiano: JSON su stderr, stdout vuoto.
Output HTML
ducklocal query --sql "SELECT * FROM 'sales.csv'" --format html > sales.html--format html scrive gli stessi valori di --format md come un'unica pagina web:
- Il numero di righe e colonne, il tempo trascorso e l'SQL dietro il risultato, compresso.
- I nomi delle colonne con i loro tipi. I numeri sono allineati a destra e i
NULLsono segnalati. - Fai clic su un'intestazione per ordinare; i
NULLrestano in fondo. Scrivi nella casella di filtro per tenere solo le righe che corrispondono. - Un risultato troncato da
--limito dal budget di celle lo dice, come in Markdown.
Lo stile e lo script sono incorporati e la pagina non scarica nulla, quindi si apre dal disco e si può pubblicare così com'è, per esempio su GitHub Pages. Ogni cella viene sottoposta a escape HTML.
Mappa ciò che si può interrogare
ducklocal schema risponde a "cosa c'è, e quali sono le sue colonne?" in una sola chiamata, mentre DESCRIBE risponde una relazione alla volta. È la prima cosa che un agente dovrebbe eseguire.
ducklocal schema ./data/ # files, folders, globs
ducklocal schema --database warehouse.duckdb # tables and views
ducklocal schema warehouse.duckdb --table orders # one relation, whole
ducklocal schema ./logs/ --full # everything, however largeI percorsi PATH si espandono come quando trascini qualcosa sulla finestra: i file di dati di una cartella in modo ricorsivo (quelli nascosti saltati, al massimo 256), le corrispondenze di un glob e un file di database come se fosse dato con --database. Torna un unico oggetto JSON:
{"detail":"full","relations":[{"name":"data/orders.csv","kind":"file","from":"'data/orders.csv'","rows":null,"column_count":2,"path":"data/orders.csv","columns":[{"name":"channel","type":"VARCHAR"},{"name":"amount","type":"BIGINT"}]}],"without_columns":0}| Campo | Significato |
|---|---|
name | Il percorso di un file come è stato dato (relativo alla directory di lavoro quando è sotto di essa), o il nome di una tabella come l'SQL su questa connessione la raggiunge: senza qualifica nello schema predefinito, schema.table altrove |
kind | file, glob, table, view o workbook |
from | L'SQL che lo legge, pronto per seguire FROM: un percorso tra virgolette, o un identificatore tra virgolette quando serve |
rows | La stima del catalogo per una tabella, esatta per Parquet (dal suo footer), null dove saperlo richiederebbe una scansione — CSV, JSON, viste |
column_count, columns | Le colonne come le descrive DuckDB |
files | Per un glob: quanti file corrispondono |
Un glob le cui corrispondenze sono tutte di un solo formato è una sola relazione, letta come la legge un source di .dash (ducklocal schema 'logs/*.csv'); --stats la profila come una. Un glob su formati misti, e una cartella, elencano i loro file uno per uno.
Un catalogo piccolo torna intero ("detail": "full"). Oltre 12 relazioni o 400 colonne diventa un riepilogo ("detail": "summary"). Le 5 relazioni con più righe conservano le loro colonne; le altre elencano nome, tipo, righe e numero di colonne, e without_columns le conta. Per ottenere di più, hint nomina i due modi: --table NAME per una relazione (cercata per il suo nome, il suo nome di tabella senza qualifica o il nome di un file) e --full per tutte. Una cartella di lavoro è elencata con i suoi sheets e senza colonne, dato che non ha una funzione tabella; --stats legge il suo primo foglio. Un percorso PATH che non esiste, o un --table che non nomina nulla, esce con codice 2.
Testo compresso con gzip come .json.gz e .csv.gz è un file di dati qui, come lo è per i blocchi source e per la finestra. Un file i cui record stanno in un'unica lista — il {"Records": [...]} di CloudTrail, per esempio — torna con un hint: l'SQL che legge quei record come righe, dato che altrimenti l'unica riga e l'unica colonna descrivono solo l'involucro.
Esplora e converti i file
Dopo aver confermato che il file reale esiste:
ducklocal query --sql "DESCRIBE SELECT * FROM 'sales.csv'"
ducklocal query --sql "SELECT * FROM 'sales.csv'" --limit 20
ducklocal query --sql "SELECT sum(amount) AS total FROM 'sales.csv'"
# Only after authorizing this output path:
ducklocal query --sql "COPY (SELECT * FROM 'sales.csv') TO 'sales.parquet' (FORMAT PARQUET)"
ducklocal query --sql "SELECT count(*), sum(amount) FROM 'sales.parquet'"
ducklocal query --sql "DESCRIBE SELECT * FROM 'events.json'"Non dare per scontato che amount esista: esegui prima ducklocal schema o DESCRIBE. Calcola gli aggregati completi in SQL invece di sommare un'anteprima troncata. Le chiamate CLI non condividono le viste registrate della GUI né le tabelle in memoria di altre chiamate. Persisti esplicitamente quando serve:
# These are separate statements and separate invocations, with explicit write permission.
ducklocal query --database warehouse.duckdb --read-write --sql "CREATE TABLE sales AS SELECT * FROM 'sales.csv'"
ducklocal query --database warehouse.duckdb --sql "SELECT count(*) FROM sales"Un conflitto di lock sul database è un errore. Chiudi l'altro scrittore (compresa la GUI) o usa una copia autorizzata; non cancellare mai i file di lock né creare in silenzio un database diverso.
JSONL e JSON annidato
read_ndjson_objects è il lettore per JSON delimitato da newline (un oggetto per riga, .jsonl/.ndjson); read_json/read_json_auto leggono documenti JSON (un array o un singolo oggetto). Nomina esplicitamente il lettore per un file JSONL invece di affidarti al rilevamento automatico. json_extract_string(col, '$.a.b[0].c') percorre un percorso annidato — chiavi di oggetto e indici di array — e restituisce VARCHAR:
ducklocal query --sql "SELECT json_extract_string(event, '$.payload.items[0].sku') AS sku, count(*) AS n FROM read_ndjson_objects('events.jsonl') GROUP BY 1 ORDER BY n DESC"Usa invece json_extract quando la foglia non è una stringa e la vuoi come JSON.
Statistiche delle colonne
ducklocal schema --stats risponde alle domande che decidono un grafico, una scala e un formato numerico, prima che su di esse si costruisca qualcosa. DESCRIBE dice che una colonna è DOUBLE; le sue statistiche dicono che usa due decimali, che il suo valore più grande è mille volte la sua mediana e che le sue date saltano undici giorni nel mezzo.
ducklocal schema sales.csv --stats
ducklocal schema ./exports/ --table orders.parquet --stats
ducklocal schema --database warehouse.duckdb --table "my orders" --stats--stats profila una sola relazione: l'unica che gli argomenti nominano, o quella scelta da --table — due o più senza --table è codice 2, con un hint che lo dice. Non si può combinare con --full. ducklocal profile TARGET [--database PATH], delle release precedenti, è lo stesso rapporto e funziona ancora.
La relazione è un file di dati — csv, tsv, txt, parquet, json, ndjson, jsonl — o una cartella di lavoro (xlsx, xls, xlsb, ods; il suo primo foglio viene importato come tabella TEMP e profilato), oppure, con --database, il nome di una tabella o vista. Un nome con punti viene letto come schema.table e ogni parte viene messa tra virgolette, così un nome con uno spazio o una maiuscola funziona così com'è scritto. Una relazione che non nomina nulla è un errore di argomenti (codice 2), non uno di SQL.
Torna un unico oggetto JSON: target, relation (l'SQL su cui sono state eseguite le statistiche), row_count, elapsed_ms e columns nell'ordine proprio della relazione. Per colonna:
| Campo | Significato |
|---|---|
name, type | come li riporta DESCRIBE |
nulls | righe in cui la colonna è NULL |
distinct | esatto, non stimato |
unique | presente e true quando distinct è uguale a row_count |
min, max | come testo, così un DECIMAL conserva le sue cifre |
decimals | cifre dopo il punto che la colonna usa realmente, che non è la sua scala dichiarata |
median | un valore che la colonna contiene, non un'interpolazione tra due di essi |
max_over_median | quante volte il valore più grande è più grande della mediana — il numero che decide un asse lineare rispetto a uno logaritmico |
covered_days, span_days, missing_days | giorni che la colonna nomina, giorni tra i suoi estremi e la differenza: 0 è una serie continua, qualsiasi altra cosa sono buchi che una linea disegnerebbe sopra |
decimals, median e max_over_median compaiono sulle colonne numeriche; i campi dei giorni su date e timestamp. Le colonne LIST, STRUCT, MAP e UNION riportano solo nulls — min e max non sono definiti su di esse.
Una colonna di testo che contiene numeri e una parola breve, come NA di R, riporta anche null_marker e null_marker_rows. Il rapporto aggiunge allora un hint che nomina la chiamata read_csv che legge la colonna come numeri.
Le statistiche sono esatte e leggono tutta la relazione, quindi costano una scansione completa. --limit non si applica: il profilo di un campione non è un profilo.
Mostra il lavoro nella finestra in esecuzione
ducklocal open consegna qualcosa alla finestra di DuckLocal già in esecuzione — avviandone una se non ce n'è — e la porta in primo piano. È il modo in cui un agente mette il suo lavoro davanti a una persona, dove può proseguire da lì:
ducklocal open --title "Revenue by channel" --run --sql "SELECT channel, sum(amount) AS total FROM 'orders.csv' GROUP BY 1"
ducklocal open sales.dash # a dashboard tab
ducklocal open ./data/ --sql-file analysis.sql
echo "SELECT 42" | ducklocal open --sql-file - --no-launch- I percorsi PATH si aprono come quando trascini qualcosa sulla finestra: un file
.dashcome scheda, un file di database DuckDB come database della finestra, file di dati, cartelle e glob collegati come viste. I percorsi PATH relativi vengono risolti rispetto alla cartella del comando. Una richiesta che arriva mentre la finestra sta ancora avviandosi attende che la sua apertura di avvio sia finita. --sqlo--sql-file(-legge da stdin) apre una nuova scheda di query, intitolata--title.--runla esegue una volta che i percorsi PATH sono stati collegati.--no-launchfallisce con kindnot_runninginvece di avviare una finestra — per una macchina dove una finestra che compare senza essere chiesta sarebbe sgradita.
Il successo stampa {"delivered": true, "launched": BOOL}: la consegna, non un risultato. Ciò che si apre viene eseguito nella sessione propria della finestra — la sua connessione, le sue viste collegate, la sua cronologia — e qualsiasi errore appare lì, non su stdout. Codice 2 per gli argomenti; 1 con kind not_running (nessuna finestra raggiungibile), refused (la finestra ha rifiutato la richiesta) o launch.
La finestra ascolta su una porta di loopback. Scrive la porta e un token casuale in un file che solo il tuo account può leggere (vedi Impostazioni e dati dell'app); un altro utente sulla macchina, o una pagina web che punta a localhost, non può raggiungerla.
Leggi cosa mostra la finestra
ducklocal open --state va nella direzione opposta: non apre nulla, non avvia mai una finestra e stampa cosa mostra la finestra in esecuzione — così un agente può riprendere da dove una persona ha lasciato, invece di chiederle di incollare la sua query.
ducklocal open --state
ducklocal open --state sales.dash
ducklocal open --state --active{"database":":memory:","attached":[{"path":"/Users/me/data/orders.csv","name":"orders","rows":224}],"active_tab":1,"tabs":[{"kind":"query","title":"Query 1","active":false,"sql":"SELECT …","result":{"status":"rows","columns":[…],"row_count":5,"truncated":false,"preview":[["Web","132771.24"],…],"sql":"SELECT …","elapsed_ms":4}},{"kind":"dashboard","title":"sales","active":true,"path":"/Users/me/data/sales.dash","unsaved":false,"dashboard":{"running":false,"error":null,"stale":null,"plots":[…],"filters":[{"name":"channel","plot":"revenue_by_channel","column":"channel","picked":true,"value":"Web"}]}}]}databaseè il file di database aperto, o":memory:";attachedelenca i file che la finestra ha registrato come viste, con ilnamedella vista. Una query della CLI non può leggere quelle viste — usa ilpath.- Una scheda di query ha
sql, il testo dell'editor eseguito o meno, eresult:statusèempty,running,rows,affected,failed,explainoprofile. Per le righe:columns,row_count,truncated,preview(le prime 20 righe come le mostra la griglia, come stringhe),elapsed_mse l'sqlche le ha prodotte; peraffected,counteelapsed_ms; per un fallimento,error. - Una volta che la persona ha scelto le colonne nella scheda Grafico, un risultato ha anche
chart:type,x,y,splitedash, un bloccoquerye un bloccoplotche disegnano lo stesso grafico in una dashboard. explainè ciò che mostra Explain:plan, l'output diEXPLAINdi DuckDB come array di righe di testo, eelapsed_ms.profileè ciò che mostra Profilo (vedi Editor SQL):plan, l'albero degli operatori misurato daEXPLAIN ANALYZE, come array di radici, ciascuna{operator, seconds, rows, estimated, children}—secondsè il tempo proprio dell'operatore esclusi i suoi figli,rowsciò che ha prodotto,estimatedla stima dell'ottimizzatore perrows(nulldove il piano non ne indica nessuna),childrendi nuovo la stessa forma.operator_secondsè la somma del tempo proprio di ogni operatore, cioè il totale a cui sommano le quote, non il tempo di orologio;elapsed_msè l'intera esecuzione.- Una scheda di dashboard ha
path,unsavededashboard: il percorso del suocomments_file, i suoiplots(nome, tipo, titolo, query, righe,open_commentsefailurequando uno non può disegnare) e i suoifilterscon ciò che ognuno ha scelto:picked,value(il primo valore),values(tutti i valori scelti, in ordine) emultiple.value: nullconpicked: truesignifica che è stato scelto il valore NULL.
Usa --state sales.dash per tenere solo le schede che mostrano quella dashboard, o --state --active per solo la scheda attiva. Un percorso che non è aperto restituisce codice 1, kind not_open, con le dashboard aperte nell'hint. active_tab è l'indice della scheda attiva dentro le tabs restituite, o null se non è tra esse; database e attached restano inclusi.
--state accetta un percorso .dash oppure --active, non entrambi. --no-launch è accettato e non cambia nulla. Altre opzioni, comprese --sql e --run, non sono valide (codice 2). Codice 1 con kind not_running quando non c'è nessuna finestra in esecuzione, e timeout quando non risponde entro 5 secondi.
Valida la specifica di una dashboard
Il formato in sé — blocchi, attributi, tipi di grafico, regole SQL e messaggi comuni — è descritto in Dashboard (.dash); questa sezione copre il comando.
Un file .dash dichiara una dashboard come Terraform dichiara l'infrastruttura — query e grafici come blocchi, riferimenti tra loro — invece di programmarla. È facile da scrivere e da confrontare con un diff, sia per una persona sia per un agente.
query "latency" {
sql = <<SQL
SELECT timestamp, service, avg(latency) AS latency
FROM logs
GROUP BY timestamp, service
SQL
}
plot "latency" {
type = "line"
query = query.latency
x = timestamp
y = latency
series = service
}ducklocal check dashboard.dash
ducklocal check dashboard.dash --database warehouse.duckdb
ducklocal check dashboard.dash --summaryUn blocco source nomina file di dati, relativi al file .dash, perché le query li leggano, e un blocco view contiene SQL condiviso da più query. Un blocco query contiene un attributo sql — una sola istruzione in sola lettura, come heredoc o come stringa. SELECT, WITH, quelli che iniziano con FROM, VALUES, SHOW, DESCRIBE, SUMMARIZE e PIVOT sono accettati; qualsiasi cosa che possa scrivere — DDL, DML, COPY, ATTACH, INSTALL — è una diagnostica, e la GUI si rifiuta di eseguirla, perché le query di una dashboard vengono eseguite ogni volta che il file si apre. Un blocco plot contiene type (uno di line, bar, stacked_bar, area, scatter, pie, heatmap, histogram, map, timeline, table, card, text), query (un riferimento come query.latency a un blocco query dello stesso file), le sue colonne e, facoltativamente, title e width. Un blocco filter rende cliccabile un grafico a barre o una tabella — un valore, o più con multiple = true su una barra — e una query legge la scelta come $name. # e // commentano fino a fine riga. Dashboard (.dash) ha ogni attributo.
Un grafico text è l'eccezione: contiene title, text, o entrambi, e non accetta query. Le card possono usare anche note e tone; vedi Card e pannelli di testo.
Prima i controlli statici: l'SQL di ogni query passa dal vero parser di DuckDB su una connessione usa e getta, come query valida prima di eseguire, e ogni $name viene confrontato con i blocchi filter — l'SQL viene analizzato ed eseguito con ogni $name come TRUE, che è ciò che esegue la dashboard prima che si scelga qualcosa.
Poi ogni query viene eseguita, esattamente come la eseguirebbe aprire la dashboard — in sola lettura, con le sue origini, attraverso lo stesso percorso di codice e lo stesso budget di righe — e le colonne di ogni grafico vengono confrontate con le colonne che la query restituisce realmente: una y non numerica è un errore per ogni tipo di grafico, e così le coordinate non numeriche di una mappa o la sua size, e una column di filtro che la query del suo grafico non restituisce.
- Senza
--databasele query vengono eseguite in memoria, che è tutto ciò di cui ha bisogno una dashboard sulle proprie originisource. Una query che legge una tabella che nessuna origine definisce può essere destinata a un database che non è stato passato al controllo: viene elencata inunresolved(query, riga, motivo) invece di fallire, e le colonne dei suoi grafici non vengono controllate. - Con
--database PATH(file esistente, in sola lettura) vengono eseguite su quel database. Passalo ogni volta che le query leggono tabelle di un database: tutto ciò che finisce inunresolvednon è stato controllato.
Ogni query che legge un filtro viene anche associata a un valore scelto, senza eseguire quella variante. Questo intercetta una colonna di filtro mancante in una query che la consuma, anche quando la versione iniziale con $name = TRUE funziona. Un filtro deve anche referenziare una colonna restituita dal grafico che lo sceglie.
Eseguire e non solo pianificare conta: alcuni fallimenti, come un cast che la build non può eseguire o un valore che non si convertirà, appaiono solo quando si leggono le righe, e un controllo che li lasciasse passare consegnerebbe una dashboard che non può disegnare. Le query vengono eseguite per intero, quindi un controllo su un database grande richiede lo stesso tempo che aprire la dashboard.
Il successo è un unico oggetto JSON che elenca le origini del file (con il loro percorso resolved), le viste, le query (con le loro colonne di risultato e rows, quante ne ha restituite ciascuna senza nulla scelto, più truncated: true quando il budget di righe della dashboard l'ha tagliata), i filtri (con le queries che leggono ciascuno), i grafici, unresolved e empty — le query che sono state eseguite e non hanno restituito righe. Una query vuota supera tutti gli altri controlli, ma di solito è una regex, un filtro o un join che non ha trovato nulla, quindi guardale una per una. Con --summary, il successo è una riga JSON compatta:
{"file":"sales.dash","ok":true,"sources":1,"views":0,"queries":3,"filters":1,"plots":6,"unresolved":[],"empty":[]}I cinque campi dei blocchi sono conteggi; unresolved elenca le query che non si sono potute controllare, e empty quelle che non hanno restituito righe.
Un blocco difettoso viene escluso mentre i blocchi validi proseguono nella validazione. Gli errori di specifica e i fallimenti delle query vengono raccolti nella stessa esecuzione, uno file:line: message ciascuno. Se esiste qualche diagnostica di specifica, l'uscita è 2 con kind spec; se falliscono solo l'esecuzione o il binding SQL, è 1 con kind sql. Anche i fallimenti di database e I/O escono con 1. --summary non nasconde le diagnostiche.
Lo stesso file si apre come scheda di dashboard nella GUI — ducklocal dashboard.dash, ducklocal open dashboard.dash, o trascinalo sulla finestra — con i grafici su una griglia di 12 colonne e un grafico che non può disegnare che mostra il motivo in linea. Vedi Dashboard (.dash).
Metriche da un modello semantico
ducklocal metrics # ./model.ossie.yaml
ducklocal metrics compile --metric error_count,event_count --by events.ip
ducklocal metrics query --metric event_count --by events.event_time:day \
--views reports/investigation.dash --restricted --allow-read dataducklocal metrics legge un modello Apache Ossie, model.ossie.yaml, ed elenca le sue metriche e i suoi campi. compile stampa l'unica SELECT DuckDB che risponde a una richiesta, senza leggere dati; query la esegue come fa ducklocal query, con un oggetto semantic che indica l'SQL e lo sha256 del modello. Una richiesta a cui il modello non può rispondere con esattezza viene rifiutata, con codice di uscita 2 e un kind come metric_fanout. Metriche semantiche descrive il formato del modello, ogni opzione e ogni rifiuto.
Rivedi i commenti di una dashboard
Le persone rivedono una dashboard commentando i suoi grafici nella finestra — passa il cursore su un grafico, fai clic sulla nuvoletta (vedi Revisione con commenti). ducklocal comments è il lato dell'agente: legge i thread e risponde, senza finestra.
ducklocal comments sales.dash [--all]
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" [--resolve]
ducklocal comments sales.dash --resolve c1
ducklocal comments sales.dash --reopen c1
ducklocal comments sales.dash --add revenue_by_channel --text "Is this net of refunds?"- Senza alcuna azione, stampa i thread aperti:
{file, comments_file, open, threads}.--allinclude quelli risolti. - Ogni thread ha
id,plote ciò che l'agente deve trovare nella specifica:plot_title,plot_queryeplot_lines, la prima e l'ultima riga del bloccoplot(nullquando la specifica non viene analizzata).plot_missingètruequando non resta nessun grafico con quel nome. Poiresolvedecomments, ciascuno conauthor(useroagent), su un commento di un agente il suoname(il nome che mostrapresence),texteat(RFC 3339, ora locale). --reply ID --text TEXTaggiunge la risposta dell'agente. Una risposta a un thread risolto lo riapre, a meno che non venga dato anche--resolve.--resolve IDe--reopen IDcambiano lo stato di un thread;--add PLOT --text TEXTavvia un thread, firmato come l'agente.- Il numero di un thread funziona come il suo ID:
--reply 1significac1.--addrifiuta un grafico che la specifica non ha (codice 2), e l'hint elenca i suoi grafici. - Un'azione stampa
{thread}, com'è cambiato.
I thread sono conservati accanto alla specifica, in FILE.comments.json. Una finestra in esecuzione nota una modifica entro un secondo e la mostra sul grafico. Un id di thread sconosciuto è codice 2, con un hint per elencare i thread; un file di specifica che non esiste è codice 1.
Una revisione, dall'inizio alla fine: leggi i thread aperti, modifica la specifica, esegui ducklocal check, poi rispondi a ogni thread con cosa è cambiato e --resolve. Usa --reply senza --resolve per chiedere qualcosa alla persona.
Mostra l'attività dell'agente
check e comments dicono automaticamente a una finestra in esecuzione a quale dashboard sta lavorando l'agente. presence può annunciare una modifica prima che avvenga:
ducklocal presence sales.dash --doing editing --plot revenue_by_channel,daily_revenue
ducklocal presence sales.dash --doing reading --agent "Analyst"
ducklocal presence sales.dash --doing idle--doingaccettareading,editingoidle(doneè un alias diidle).--plotprende nomi di grafici separati da virgole. Conediting, i nomi nuovi sono ammessi e compaiono come segnaposto. Conreadingoidle, un nome sconosciuto è codice 2.- Il nome mostrato viene da
--agent, poi daDUCKLOCAL_AGENT, poi dall'ambiente agente rilevato (Claude, Codex, Cursor o Gemini), e infine daAgent. - L'output è
{delivered}. Senza una finestra in esecuzione produce{"delivered":false}senza errore e senza avviare una finestra.
Il nome resta nell'angolo della dashboard finché i comandi mantengono attiva la sessione. Fai clic su di esso per il registro delle attività. Trenta secondi di silenzio o --doing idle terminano la sessione; i grafici modificati e aggiunti restano contrassegnati finché non vengono visti, e gli avvisi dei grafici rimossi finché non vengono chiusi. Vedi Vedere un agente al lavoro.
Modifica la specifica di una dashboard con LSP
ducklocal lsp è un server Language Server Protocol per i file .dash, su stdio, perché gli editor lo avviino. Dà a qualsiasi editor compatibile con LSP ciò che ha l'editor di specifiche della GUI:
- Diagnostica: quelle che riporta
check, pubblicate a ogni apertura e modifica (sincronizzazione dell'intero documento, tutte con severità Error — sono errori, non stile). - Completamento: tipi di blocco, nomi di attributo, tipi di grafico e i nomi dopo
query.eplot., ciascuno con una modifica di testo che sostituisce la parola in digitazione. - Hover: documentazione per blocchi, attributi e riferimenti.
- Vai alla definizione: da un riferimento
query.nameoplot.nameal nome del suo blocco.
Con --database PATH l'SQL di ogni query viene inoltre validato dal vero parser di DuckDB, come fa check --database.
Punta il supporto LSP generico del tuo editor su ducklocal lsp per i file *.dash — il comando non prende argomenti di documento; l'editor parla con esso su stdio. In Neovim (0.10+):
vim.api.nvim_create_autocmd("FileType", {
pattern = "dash",
callback = function(event)
vim.lsp.start({
name = "ducklocal",
cmd = { "ducklocal", "lsp" },
root_dir = vim.fs.dirname(vim.api.nvim_buf_get_name(event.buf)),
})
end,
})In VS Code, qualsiasi estensione LSP generica fa lo stesso con il comando ducklocal, argomenti ["lsp"], selettore di documento dash. Codici di uscita: 0 dopo uno shutdown/exit pulito, 1 quando il client sparisce senza farlo, 2 per una riga di comando errata o un handshake di protocollo fallito.
Contratto JSON
Le query riuscite scrivono esattamente un oggetto JSON su stdout, seguito da un newline:
{"columns":[{"name":"n","type":"Int32"}],"rows":[[1]],"row_count":1,"truncated":false,"total_rows":1,"total_rows_exact":true,"elapsed_ms":1}columns e ogni riga preservano l'ordine delle colonne e i nomi duplicati. type è la rappresentazione di debug di Arrow, non il nome del tipo SQL originale di DuckDB (per esempio HUGEINT e DECIMAL possono condividere un carrier Arrow). row_count conta le righe restituite. total_rows conta le righe prodotte, comprese quelle contate dopo il limite di output; total_rows_exact: false significa che il conteggio si è fermato dopo fino a 100.000 righe aggiuntive, quindi quel totale è un limite inferiore. Nessuno dei due conteggi è un conteggio di righe interessate. elapsed_ms misura preparazione, esecuzione e codifica delle righe, non il caricamento dei file o la creazione della connessione. I risultati con zero righe conservano i metadati. DDL/DML espongono il risultato reale di DuckDB, comprese le colonne Count: INSERT/COPY di solito restituiscono [[N]]; CREATE TABLE di solito non restituisce righe. Non vengono classificati dalla prima parola chiave SQL.
Codifica delle celle:
| Valore SQL | Codifica JSON |
|---|---|
| NULL | null (mai la stringa "NULL") |
| Booleano, float finito | booleano/numero JSON |
| Intero entro ±9.007.199.254.740.991 | numero JSON |
| Intero più grande, compresi HUGEINT/UHUGEINT | {"encoding":"integer","value":"9007199254740992"} |
| Decimale | {"encoding":"decimal","value":"123.450"} con il testo decimale esatto |
| Testo, enum | stringa JSON |
| Blob, geometry | {"encoding":"hex","value":"00ff"}; byte in minuscolo, geometry usa WKB |
| Date | {"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"}; giorni dal 1970-01-01 |
| Timestamp | {"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"}; conteggio con segno dall'epoca Unix; l'unità può anche essere Second/Millisecond/Microsecond |
| Time | {"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}; conteggio dalla mezzanotte |
| Interval | {"encoding":"interval","months":1,"days":2,"nanos":"3000"} |
| NaN, infinito positivo/negativo | {"encoding":"float","value":"NaN"} / "inf" / "-inf" |
| List, array | array JSON, codificato ricorsivamente (compresi i null annidati) |
| Struct | {"encoding":"struct","fields":[["name",VALUE],...]} |
| Map | {"encoding":"map","entries":[[KEY,VALUE],...]}; non è un oggetto JSON, quindi le chiavi conservano i loro tipi |
| Union | {"encoding":"union-value","value":VALUE}; solo il valore attivo, il tag del membro non viene conservato |
I value temporali sono conteggi esatti, quindi non si perde precisione frazionaria; i sentinella di infinito di date e timestamp restano conteggi grezzi. Accanto a ciascuno, iso è lo stesso valore come testo ISO 8601 per la lettura, con tante cifre di frazione quante ne contiene l'unità. Un timestamp di una colonna con fuso orario (metadati Arrow) è un istante UTC, e il suo iso termina con Z. Anche --format md rende date e timestamp in modo leggibile. Poiché il wrapper Arrow di DuckDB fissato non riesce a distinguere HUGEINT, UHUGEINT e DECIMAL(38,0) annidati, le occorrenze non nulle producono un errore chiaro invece di cambiare silenziosamente segno o precisione. Converti esplicitamente quei campi in VARCHAR nell'SQL. Anche i tipi non supportati sconosciuti producono un errore; non scambiare un errore per un risultato vuoto. La codifica Union è una rappresentazione del valore attivo, non un round trip senza perdite di una union.
Gli errori scrivono un oggetto JSON su stderr, lasciando stdout vuoto:
{"error":{"kind":"argument","message":"Unknown query option: --limt","hint":"Did you mean --limit?"}}hint c'è quando il passo successivo è noto, nei termini propri di questa CLI: il flag che uno sbagliato doveva essere, --read-write per una scrittura rifiutata su un database in sola lettura, ducklocal schema per una tabella che non esiste, TRY_CAST per un valore che non si convertirà, la divisione di uno script che ha più di un'istruzione, o AS per una parola chiave usata come alias di colonna nudo (SELECT count(*) AS minutes, o mettila tra virgolette). Un agente dovrebbe agire su di esso prima di riscrivere l'SQL. È assente quando non c'è nulla da aggiungere al messaggio di DuckDB stesso, come in un errore di sintassi.
Codici di uscita: 0 successo, 2 argomenti/numero di istruzioni non validi, 1 fallimento di SQL, database, I/O o output. I kind di errore sono argument, sql, database, io, output, spec per check, e not_running, not_open, refused, timeout o launch per open. Controlla lo stato di uscita prima di analizzare stdout e ispeziona truncated prima di dichiarare la completezza. Aiuto e versione sono eccezioni in testo semplice. I fallimenti di trasporto come un pipe di stdout chiuso non possono garantire un flusso di output vuoto o completo.
Installa la skill ufficiale
La skill insegna all'agente le abitudini che mantengono oneste le sue risposte: ispezionare lo schema, visualizzare in anteprima un campione limitato, calcolare gli aggregati in SQL, controllare truncated e rispondere dai valori restituiti. Copre l'ispezione degli schemi, le statistiche delle colonne, le conversioni, le query ai database, le dashboard .dash e i loro commenti di revisione, e il consegnare lavoro alla finestra e rileggerlo; non fornisce navigazione S3, comandi specifici per dati spaziali, memoria di sessione né un server MCP.
Dall'app. Apri Riga di comando e IA… (il pulsante del robot nella barra del titolo, o il menu DuckLocal):
- Installa comando mette
ducklocalnel tuoPATH, così la shell di un agente può eseguirlo. - Aggiungi a Claude Code scrive la skill in
~/.claude/skills/ducklocal, dove Claude Code la trova in ogni progetto. Vengono scritti solo i due file propri della skill; qualsiasi altra cosa in quella cartella viene conservata. Quando un aggiornamento di DuckLocal porta una skill più recente, il dialogo offre Aggiorna skill. - Copia il brief copia una breve spiegazione per qualsiasi altro agente — Codex, Cursor, una finestra di chat — nominando il comando e come usarlo.
A mano. La skill è skills/ducklocal. Per aggiungerla a un solo progetto invece (esempio per Claude Code):
# Run from the DuckLocal checkout; replace the destination with your project.
mkdir -p /path/to/your-project/.claude/skills
cp -R skills/ducklocal /path/to/your-project/.claude/skills/Ispeziona prima una destinazione esistente invece di sovrascrivere modifiche locali. Altri agenti possono usare lo stesso SKILL.md più references/cli.md nella cartella delle skill che supportano.
