Vai al contenuto

Dashboard (.dash) ​

Un file .dash descrive una dashboard come dati: i blocchi source nominano i file di dati, i blocchi query contengono SQL, i blocchi plot disegnano i risultati, e i blocchi filter lasciano che un clic su un grafico restringa gli altri. Non c'è codice da scrivere. Sia le persone sia gli agenti AI possono creare il file, rivederlo in un diff e validarlo prima che qualcuno lo apra.

Un file .dash disegna grafici, tabelle, numeri e mappe standard da query salvate. Il suo formato in testo semplice lo rende anche utile per lavorare con un agente AI: l'agente scrive o modifica il file, ducklocal check verifica che funzioni, e tu commenti i grafici per chiedere modifiche.

Un esempio completo ​

Questa dashboard interroga il file di esempio del tutorial. Scarica sales.dash nella stessa directory di sales.csv, poi aprilo.

hcl
source "sales" {
  path = "sales.csv"
}

query "totals" {
  sql = <<SQL
    SELECT round(sum(revenue), 2) AS revenue, sum(orders) AS orders,
           count(DISTINCT region) AS regions
    FROM sales
    WHERE $channel
  SQL
}

query "by_channel" {
  sql = <<SQL
    SELECT channel, round(sum(revenue), 2) AS revenue
    FROM sales
    GROUP BY channel
    ORDER BY revenue DESC
  SQL
}

query "daily" {
  sql = <<SQL
    SELECT date, region, round(sum(revenue), 2) AS revenue
    FROM sales
    WHERE $channel
    GROUP BY date, region
    ORDER BY date
  SQL
}

plot "revenue" {
  type  = "card"
  query = query.totals
  value = revenue
  title = "Revenue"
  width = 4
}

plot "orders" {
  type  = "card"
  query = query.totals
  value = orders
  title = "Orders"
  width = 4
}

plot "regions" {
  type  = "card"
  query = query.totals
  value = regions
  title = "Regions"
  width = 4
}

plot "revenue_by_channel" {
  type  = "bar"
  query = query.by_channel
  x     = channel
  y     = revenue
  title = "Revenue by channel"
  width = 5
}

plot "daily_revenue" {
  type   = "line"
  query  = query.daily
  x      = date
  y      = revenue
  series = region
  title  = "Daily revenue, per region"
  width  = 7
}

plot "daily_table" {
  type  = "table"
  query = query.daily
  title = "The numbers behind it"
}

filter "channel" {
  plot = plot.revenue_by_channel
}

Si apre come tre numeri in alto, il grafico a barre e quello a linee affiancati, e la tabella sotto. Ogni query viene eseguita una volta, per quanti grafici la usino: totals alimenta tutte e tre le card, e daily alimenta sia il grafico a linee sia la tabella. Fai clic su una barra in Revenue by channel e le card, il grafico a linee e la tabella si restringono a quel canale; il grafico a barre resta intero, così puoi cliccarne un'altra.

Aprire una dashboard ​

Ognuno di questi modi apre un file .dash come scheda dashboard, accanto alle tue query:

  • il + in fondo alla barra delle schede, poi Apri dashboard;
  • trascinando il file sulla finestra;
  • indicandolo sulla riga di comando: ducklocal sales.dash;
  • da uno script o da un agente, nella finestra già in esecuzione: ducklocal open sales.dash (vedi la guida alla CLI).

I grafici sono disposti su una griglia di 12 colonne: ognuno occupa la sua width, i grafici riempiono una riga da sinistra a destra, e un grafico che non entra più inizia la riga successiva. Trascina i divisori tra le righe per ridimensionarle; una dashboard più alta della scheda scorre. Un grafico che non riesce a disegnare — la sua query è fallita, o manca una colonna — mostra il motivo nel proprio pannello, e il resto della dashboard viene comunque disegnato. Le dashboard aperte tornano al prossimo avvio, e quelle aperte di recente sono elencate sotto Dashboard nella barra laterale.

Passa il mouse su un grafico per rivelarne i controlli nell'angolo in alto a destra:

  • SQL mostra il grafico come l'SQL eseguito l'ultima volta dalla sua query — con le sue sorgenti e le selezioni dei filtri correnti inserite, così gira così com'è — con Copia e Apri in una scheda query. Grafico lo riporta indietro.
  • La nuvoletta apre i commenti del grafico.
  • Ingrandisci questo grafico lo espande fino a riempire la scheda della dashboard. Usa Torna alla dashboard (Esc) o premi Esc per tornare alla griglia.

La vista SQL evidenzia la sintassi. Fai clic destro su una cella di una tabella della dashboard per copiare la cella, la sua riga separata da tabulazioni, o la sua colonna nell'ordine visualizzato.

Fai clic sull'intestazione di colonna di un grafico table per ordinarlo: decrescente, crescente, poi di nuovo nell'ordine della query. I numeri si ordinano come numeri e NULL finisce per ultimo; una riga scelta per un filtro resta scelta attraverso un ordinamento.

Mostra spec nella barra degli strumenti passa la scheda a un editor per il file, con evidenziazione della sintassi (l'SQL dentro gli heredoc è colorato come nell'editor SQL), completamento e diagnostica inline. Salva o ⌘S lo riscrive e ridisegna. Se il file salvato non supera la validazione, la scheda mantiene l'ultima dashboard funzionante e mostra l'errore sopra. Lo stesso accade quando un altro programma cambia il file. Torna alla dashboard riporta ai grafici. Ricarica rilegge il file ed esegue di nuovo ogni query.

Rivedere con i commenti ​

I commenti ti permettono di rivedere una dashboard come faresti con un documento, e di affidare le modifiche a un agente AI. Le idee di prodotto dietro questo flusso di lavoro sono raccontate in Cosa mi hanno insegnato le dashboard di Claude su DuckLocal.

Nella finestra, passa il mouse su un grafico e fai clic sulla nuvoletta. Una card si apre sopra la dashboard, citando il titolo del grafico, con i thread già presenti e un riquadro in cui scrivere. Scrivi cosa dovrebbe cambiare — "ordinali, canale più grande per primo" — e premi Commenta (o ⌘/Ctrl+Invio). Ogni thread ha Rispondi e Risolvi; un thread risolto resta, attenuato, finché qualcuno non gli risponde. Un grafico con thread aperti mantiene in vista una nuvoletta con il loro numero, così vedi a colpo d'occhio cosa è in attesa.

L'agente legge e risponde ai thread con ducklocal comments, senza bisogno di una finestra:

bash
ducklocal comments sales.dash
json
{
  "file": "sales.dash",
  "comments_file": "sales.dash.comments.json",
  "open": 1,
  "threads": [
    {
      "id": "c1",
      "plot": "revenue_by_channel",
      "plot_title": "Revenue by channel",
      "plot_query": "by_channel",
      "plot_lines": [68, 75],
      "plot_missing": false,
      "resolved": false,
      "comments": [
        { "author": "user", "text": "Rank these, biggest channel first", "at": "2026-10-10T14:03:00+08:00" }
      ]
    }
  ]
}

Ogni thread indica il suo grafico, la query del grafico e le righe del suo blocco plot nel file, così l'agente sa cosa modificare. Cambia lo spec, esegue ducklocal check e risponde:

bash
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" --resolve

La finestra osserva entrambi i file. Entro un secondo il grafico viene ridisegnato dallo spec modificato, e la risposta dell'agente compare nel suo thread, contrassegnata Agente.

I thread sono conservati accanto alla dashboard, in NAME.dash.comments.json, così viaggiano con essa come i suoi file source. Sono note di lavoro, non parte della dashboard: lasciale fuori dal controllo di versione, o elimina il file quando la revisione è finita.

La skill ufficiale per agenti insegna questo ciclo, quindi a un agente che ce l'ha basta dire "risolvi i commenti su sales.dash".

Novità nella 0.4.0

Un agente può proporre una modifica invece di modificare il file. La scheda quindi offre Rivedi, con il diff e i controlli, e solo tu puoi applicarla.

Guardare un agente al lavoro ​

Mentre un agente esegue check, comments o presence per questa dashboard aperta, il suo nome compare nell'angolo, con il marchio del suo produttore — Claude, OpenAI, Gemini, Cursor, DeepSeek — o la sua iniziale. Fai clic sul nome per vedere il log della sessione. Quando modifica il file, i grafici cambiati e aggiunti restano contrassegnati (Claude ha modificato questo, Claude ha aggiunto questo) finché non li hai avuti in vista per un momento; un grafico rimosso lascia un avviso che puoi chiudere.

Un agente può annunciare la sua prossima modifica con ducklocal presence sales.dash --doing editing --plot revenue_by_channel. Quel grafico riceve un anello; un nome di grafico che non esiste ancora riceve un segnaposto sotto la dashboard. La sessione termina dopo 30 secondi di inattività, o con un esplicito --doing idle. Un agente che ha finito resta nell'angolo finché un thread a cui ha risposto aspetta la tua risposta, con il conteggio sul suo avatar. I commenti registrano quale agente li ha scritti e mostrano il suo marchio. Il riferimento della CLI illustra le opzioni. Questi indicatori mostrano attività locale; non inviano lavoro a un agente.

Blocchi ​

Un file è una sequenza di blocchi, ciascuno con un tipo, un nome tra virgolette e un corpo:

hcl
source "name" { ... }
view "name" { ... }
query "name" { ... }
plot "name" { ... }
filter "name" { ... }
dashboard "name" { ... }

I nomi devono essere unici all'interno del loro tipo: due query non possono condividere un nome, e nemmeno due grafici — ma una query e un grafico possono.

Novità nella 0.4.1

Un blocco view contiene la trasformazione che più query condividono, un filter può raccogliere più valori (multiple = true), un grafico timeline colloca gli eventi in base alla loro reale distanza nel tempo, e un blocco dashboard imposta il fuso in cui viene mostrato ogni TIMESTAMPTZ.

source ​

AttributoObbligatorioValore
pathsìUn file .csv, .tsv, .txt, .parquet, .json, .jsonl o .ndjson (anche compresso con gzip, come .csv.gz), oppure un glob di tali file (exports/orders-*.csv) letto come un'unica relazione

Una sorgente dà un nome ai file di dati che le query leggono: con source "sales", una query dice FROM sales. Il percorso è relativo al file .dash, non a dove è stato avviato DuckLocal, quindi una dashboard e i suoi dati possono spostarsi insieme; anche ~ e i percorsi assoluti funzionano.

Una sorgente non tocca mai la connessione: diventa un WITH sales AS (…) davanti a ogni query che la nomina, quindi nulla compare nella barra laterale, nulla sopravvive alla scheda, e una sorgente oscura una tabella con lo stesso nome solo per le query di questa dashboard. Il nome deve essere un identificatore semplice (lettere, cifre e _). Una cartella di lavoro non può essere una sorgente; aprila in DuckLocal e interroga la tabella in cui diventa.

view ​

Una vista contiene la trasformazione che più query condividono, scritta una volta. Ha un solo attributo sql, con le stesse regole di quello di una query, e ogni query che la nomina la legge come una tabella:

hcl
view "events" {
  sql = <<SQL
    SELECT r.eventName AS event_name, r.eventTime AS event_time
    FROM (SELECT unnest(Records) AS r FROM trail)
  SQL
}

query "totals" {
  sql = "SELECT count(*) AS events, count(DISTINCT event_name) AS kinds FROM events"
}

Una vista legge le sorgenti e le viste definite sopra di essa, condivide i nomi con le sorgenti, e non accetta $filter — leggi il filtro nelle query che leggono la vista. Come una sorgente, viene messa davanti a ogni query che la nomina e non crea nulla sulla connessione. Ricorri a una vista quando le query altrimenti ripeterebbero lo stesso CTE, per esempio per appiattire JSON annidato.

query ​

AttributoObbligatorioValore
sqlsìUna sola istruzione SQL in sola lettura, come heredoc o come stringa

Un blocco query contiene sql e nient'altro. Può leggere $name per un filtro.

plot ​

AttributoPerValore
typetutti, obbligatorio"line", "bar", "stacked_bar", "area", "scatter", "pie", "heatmap", "histogram", "map", "timeline", "table", "card" o "text" — una stringa tra virgolette
querytutti tranne text, obbligatorioUn riferimento a un blocco query: query.by_channel
xgrafici, obbligatorioLa colonna sull'asse orizzontale; le fette di un pie; il numero che un histogram suddivide in intervalli; il tempo di un timeline
ygrafici, obbligatorioLa colonna da tracciare; deve essere numerica. La dimensione delle fette di un pie. Un histogram e un timeline non ne prendono
seriesline, bar, stacked_bar, area, scatter, heatmap, timelineUna colonna i cui valori dividono le righe in una serie ciascuno; le righe di un heatmap; le corsie di un timeline
titletuttiUn titolo per il grafico, come stringa tra virgolette; l'etichetta di una card
widthtuttiQuante delle 12 colonne della griglia occupa il grafico, 1–12. Predefinito 12, o 3 per una card
valuecardLa colonna da mostrare, dalla prima riga. Predefinito: la prima colonna
notecardTesto sotto il valore: una stringa tra virgolette, o un nome di colonna nudo da leggere dalla prima riga
tonecard"accent", "good", "warning" o "critical"; colora la riga superiore e il valore
formatgrafici e cardChe cosa sono i numeri: vedi Formati numerici e variazione. Un map o un table non ne prendono
deltacardUna colonna numerica che contiene la variazione, mostrata sotto il valore
delta_formatcardUn formato per la variazione. Predefinito: quello della card
down_is_goodcardtrue rende verde una caduta e rossa una salita, per costi, latenza o abbandoni
descriptiontutti, 0.4.0+Cosa mostra il grafico e come leggerlo; compare passando il mouse su un ⓘ accanto al titolo
texttextTesto del corpo come stringa o heredoc; fornisci title, text o entrambi, senza query
captiontimelineLa colonna che dice cos'è stato ogni evento, scritta sotto il suo punto dove ci sta e al passaggio del mouse
lat, lngmapColonne di latitudine e longitudine, in gradi. Una delle due si può omettere quando il nome della colonna numerica indica la coordinata — lat, latitude, geo_lat; lng, lon, longitude
colormapUna colonna per colorare i punti; se omessa, se ne sceglie una quando una colonna di testo ha pochi valori
sizemapUna colonna numerica per dimensionare i punti
size_scalemap"sqrt" (il predefinito) o "log", per come scala size
tooltipmapUn elenco delle colonne mostrate nel tooltip di un punto: [name, passengers]

Gli attributi di colonna nominano colonne del risultato della query, confrontate senza badare alle maiuscole. Scrivi un nome semplice nudo (x = date); metti tra virgolette uno che non è un identificatore semplice (y = "revenue (EUR)"). Un attributo che il tipo del grafico non usa — lat su un grafico a linee, x su una mappa, series su un pie — è un errore, non qualcosa che viene ignorato in silenzio.

filter ​

AttributoObbligatorioValore
plotsìIl grafico su cui un clic sceglie un valore: plot.revenue_by_channel. Un bar, uno stacked_bar o un table
columnper un tableLa colonna il cui valore viene scelto. Per un bar o uno stacked_bar, la sua x se omessa
multiplebar, stacked_bartrue fa sì che ogni clic aggiunga il suo valore e un secondo clic lo tolga; $name diventa IN (…). Una tabella seleziona una riga, quindi multiple su una tabella è un errore di check

Vedi Filtri per cosa fa un filtro.

dashboard ​

Un blocco dashboard facoltativo contiene impostazioni per l'intero file:

hcl
dashboard "Ops" {
  timezone = "+08:00"     # or "UTC", or "local"
}

timezone è il fuso in cui viene mostrato ogni TIMESTAMPTZ della dashboard; il fuso è indicato sopra i grafici. Sono accettati un offset ("+08:00"), "UTC" e "local"; i nomi IANA come Asia/Shanghai no. Un TIMESTAMP semplice non ha fuso e viene mostrato come è scritto, e una colonna scelta da un filtro conserva il suo valore memorizzato così le scelte continuano a corrispondere. Un file contiene al massimo un blocco dashboard.

Tipi di grafico ​

TipoDisegna
lineUna linea per serie, non riempita
areaUn'area riempita per serie
barUna barra per riga, un colore per serie. Con series, le barre delle serie affiancate in ogni gruppo. Una serie singola etichetta ogni barra con il suo valore
stacked_barUna barra per ogni x, con le sue series impilate: le parti positive verso l'alto da zero, quelle negative verso il basso, con il totale in cima e nel tooltip
heatmapx in orizzontale e series in verticale, ogni cella colorata da y su un unico blu, più scuro per valori maggiori (più chiaro in modalità scura). Una coppia che la query non restituisce resta vuota
histogramLe righe contate in ogni intervallo di un x numerico, in intervalli di ampiezza tonda. Fai in modo che la sua query restituisca le righe stesse, non un raggruppamento
scatterUn punto per punto, non collegati, un colore per serie
pieUna fetta per ogni valore di x, dimensionata da y, dalla più grande; oltre le 8 fette, le più piccole si fondono in "altro". Disegnato come un anello con il totale al centro; fai clic su una voce della legenda per isolare una fetta, e di nuovo per ripristinarla
textUn titolo, un testo esplicativo, o entrambi; nessuna query viene eseguita
mapUn punto per riga, alla sua lat e lng; vedi Mappe
timelineUn evento per riga al tempo indicato da x, collocato in base alla sua reale distanza dagli altri, così i vuoti si vedono. series dà a ogni attore una corsia, caption dice cos'è successo, e tooltip elenca le colonne mostrate al passaggio del mouse. Non prende y; disegna al massimo 12 corsie e 1.000 eventi (diradati in modo uniforme oltre quel limite, e lo dice), e conta le righe il cui tempo non si può leggere invece di disegnarle
tableIl risultato della query come griglia, con le colonne dimensionate sul loro contenuto; fai clic su un'intestazione per ordinare
cardUn numero, grande, con il title come etichetta. Raggruppato per migliaia, una frazione lunga viene arrotondata (11439704.020000005 → 11,439,704.02) e rimpicciolita per entrare nella card invece di essere tagliata

Passa il mouse su un grafico per i suoi valori, formattati come li mostra l'asse (4.4M, non 4400000).

Un grafico a barre etichetta ogni categoria. Quando le etichette non entrano sotto le loro barre, il grafico si corica su un fianco, con le etichette in una colonna a sinistra. Solo un asse temporale dirada le sue etichette, tenendone quante ci stanno — sempre la prima e l'ultima — e una barra su una colonna DATE riempie i giorni per cui la query non ha restituito nulla come bande vuote, così un periodo tranquillo si legge come un vuoto invece di sparire. Gli assi di linee, aree e dispersione diradano le etichette allo stesso modo.

L'asse x è categorico per ogni tipo di grafico: i valori sono distanziati in modo uniforme nell'ordine in cui la query li restituisce, non in base alla loro distanza reciproca. Uno scatter di due colonne numeriche non è quindi un vero grafico x–y.

Le righe sono tracciate nell'ordine in cui la query le restituisce, quindi chiudi con ORDER BY una query che alimenta un grafico.

Novità nella 0.4.0

Una line o uno scatter di dashboard su tempi viene collocato in base al tempo, quindi i vuoti irregolari appaiono irregolari, e viene disegnato in ordine temporale qualunque sia l'ORDER BY. Una riga con un tempo NULL viene omessa, con una nota. Un valore NULL restituito dalla query interrompe la linea. Un'area resta a spaziatura uniforme e lo dice. Una serie mantiene il suo colore per nome, e ogni grafico dice quando la sua query è stata interrotta.

Una card mostra la prima riga della sua query. Quando la query restituisce più di una riga, la card lo dice sotto il numero; quando non ne restituisce nessuna, mostra —.

Card e pannelli di testo ​

Le card possono spiegare un numero con note e dargli un colore di stato con tone. Le card nella stessa riga condividono una dimensione del carattere del valore. I pannelli di testo aggiungono titoli o contesto senza eseguire SQL:

hcl
plot "revenue_summary" {
  type  = "card"
  query = query.totals
  value = revenue
  title = "Revenue"
  note  = "Current channel selection"
  tone  = "accent"
  width = 4
}

plot "reading_guide" {
  type  = "text"
  title = "How to read this dashboard"
  text  = "Click a channel to filter the daily chart and revenue cards."
  width = 8
}

Un pannello di testo accetta solo type, title, text e width. Usa text = <<TEXT con una riga TEXT di chiusura per una spiegazione più lunga. Grafici, pie e mappe usano otto tonalità distinte, con sfumature adattate al tema corrente e una legenda per le serie multiple.

Formati numerici e variazione ​

format dà forma al valore di una card, all'asse dei valori, alle etichette delle barre e ai tooltip:

ValoreLegge
"num0", "num1", "num2"Un numero con quel numero di decimali
"pct" (lo stesso di "pct1"), "pct0", "pct2"Una quota: 0.421 legge 42,1%, quindi restituisci la frazione, non ×100
"usd", "eur", "gbp", "cny"Valuta, con due decimali
"usd0", "eur0", "gbp0", "cny0", "jpy"Valuta, in unità intere

Una card mostra una variazione con delta, sotto il valore come ▲ 12,3% o ▼ $125. È verde quando va bene e rossa quando no, e la note la segue per dire rispetto a cosa. Calcola la variazione nella query della card:

hcl
plot "revenue_total" {
  type         = "card"
  query        = query.totals
  value        = revenue
  format       = "usd0"
  delta        = growth
  delta_format = "pct1"
  note         = "vs last week"
}

Layout ​

width è quante delle dodici colonne della dashboard occupa un grafico. I grafici riempiono una riga da sinistra nell'ordine in cui sono scritti e vanno a capo quando il successivo non entra, quindi quattro card (3 ciascuna) formano una riga di numeri, e due grafici width = 6 stanno affiancati sotto di esse. Una riga che non arriva a dodici lascia il resto vuoto. Una riga di sole card parte da un'altezza ridotta, una riga di sole tabelle parte alta quanto le righe della sua tabella più lunga, fino all'altezza di un grafico. Una riga di pannelli di testo si adatta al suo testo; le altre righe partono all'altezza di un grafico. Le maniglie di ridimensionamento delle righe compaiono al passaggio del mouse.

Mappe ​

hcl
plot "stations" {
  type       = "map"
  query      = query.stations
  lat        = geo_lat
  lng        = geo_lng
  color      = line
  size       = passengers
  size_scale = "log"
  tooltip    = [name, passengers]
}

Una mappa traccia ogni riga come un punto, su una proiezione Web Mercator adattata ai punti, sopra una griglia di latitudine/longitudine etichettata in gradi.

  • color: fino a cinque valori ricevono ciascuno un colore; con più valori, lo fanno i quattro più comuni e gli altri condividono un colore "Altro". Una legenda li riporta. Se omesso, i punti sono colorati da una colonna di testo con pochi valori distinti, quando il risultato ne ha una.
  • size: l'area di un punto segue il valore, quindi il doppio del valore è il doppio dell'inchiostro. size_scale = "log" si adatta a valori che coprono ordini di grandezza. Una legenda nell'angolo riporta le dimensioni.
  • tooltip: senza di esso, il tooltip di un punto elenca la colonna della dimensione e gli altri numeri, poi le coordinate.

Sotto i punti, una mappa può disegnare una mappa di base OpenStreetMap. È disattivata finché non la attivi — Visualizza → Mappa di base online (OpenStreetMap) — perché caricare le tessere richiede la rete. Quello che invia è quali tessere della mappa vuole, il che rivela all'incirca l'area che stai guardando, mai una riga dei tuoi dati. Le tessere sono memorizzate su disco per una settimana (vedi Impostazioni e dati dell'app); offline o disattivata, la mappa viene disegnata solo sulla sua griglia di latitudine/longitudine. Lo stesso interruttore vale per la mappa nella scheda Grafico dei risultati delle query.

Filtri ​

Un filtro rende un grafico cliccabile, e lascia che il valore scelto lì restringa le altre query:

hcl
filter "channel" {
  plot = plot.revenue_by_channel     # a click on a bar picks its channel
}

filter "day" {
  plot   = plot.days                 # a table: a selected row picks …
  column = day                       # … the value of this column
}

filter "channel" {
  plot     = plot.revenue_by_channel
  multiple = true                    # clicks collect channels
}

query "daily" {
  sql = "SELECT date, sum(orders) AS orders FROM sales WHERE $channel AND $day GROUP BY 1"
}

Una query legge un filtro come $name, una condizione: scrivilo dove va una condizione. Finché non è scelto nulla vale TRUE, quindi la dashboard si apre esattamente come farebbe senza il filtro. Una volta scelto un valore diventa ("channel" = 'Web') — la colonna indicata come column del filtro, confrontata con il valore scelto; una cella mostrata come NULL corrisponde a SQL NULL o al testo letterale NULL. Con multiple = true su una barra o una barra impilata, ogni clic aggiunge il suo valore e un secondo clic lo toglie, e $name diventa ("channel" IN ('Web', 'App')), con OR "channel" IS NULL quando NULL è tra questi. Più filtri si combinano come li combina la query.

  • Su un grafico a barre, fai clic su una barra per sceglierla: mantiene il suo colore mentre le altre sbiadiscono. Fai clic di nuovo per annullare la scelta. Con multiple = true, ogni clic aggiunge un valore e un secondo clic lo rimuove.
  • Su una tabella, seleziona una riga, con un clic o con i tasti freccia.
  • Le scelte attive compaiono come chip sopra i grafici; la ✕ di ogni chip cancella il suo filtro, e Cancella tutto cancella ogni scelta. Un filtro a selezione multipla mostra un chip per ogni valore scelto.
  • Il grafico che sceglie non viene mai ristretto dal proprio filtro. La sua query legge $channel come TRUE anche mentre un canale è scelto — altrimenti un clic ridurrebbe il grafico a barre alla sola barra cliccata, senza nulla da cliccare dopo. Questo è il cross-filtering, come in Mosaic o crossfilter.
  • Viene rieseguito solo ciò che è cambiato. Una scelta riesegue le query il cui SQL cambia; una query che non legge alcun filtro mantiene il suo risultato.

Un filtro contiene un valore alla volta, o più con multiple = true. I grafici selezionabili includono un suggerimento "clicca per filtrare" sotto il titolo. Le serie mantengono i loro colori al variare dei gruppi che restano. Una query che usa $channel deve esporre la colonna del filtro dove quella condizione è usata; ducklocal check ora verifica anche una variante con un valore scelto, così una colonna mancante viene intercettata prima del primo clic.

Novità nella 0.4.0

Scegliere una cella mostrata come NULL seleziona solo SQL NULL, e il testo 'NULL' seleziona solo se stesso. I grafici selezionabili non mostrano più un suggerimento "clicca per filtrare" sotto il titolo.

Il valore scelto finisce nell'SQL come letterale tra virgolette, e DuckDB lo converte al tipo della colonna al confronto, quindi date e numeri funzionano come il testo. Le scelte durano finché la scheda è aperta e sopravvivono a una ricarica, finché il filtro è ancora nel file; non vengono ricordate tra un avvio e l'altro.

Valori ​

FormaEsempioUsata per
Stringa"Revenue by channel"type, title, path, size_scale, tone, note letterale, text, nomi di colonna tra virgolette, sql brevi
Heredoc<<SQL … SQLsql, text
Riferimentoquery.daily, plot.revenue_by_channella query di un grafico, il plot di un filtro
Nome nudochannelattributi di colonna
Numero6width
Elenco[name, "Unique IPs"]tooltip

Una stringa termina alla sua riga e comprende \n, \t, \" e \\.

# e // iniziano un commento che arriva a fine riga. Gli attributi non hanno bisogno di separatori; gli a capo sono solo spazi bianchi.

Questo è tutto il linguaggio: niente variabili, niente funzioni, niente condizionali, e nessuna interpolazione oltre al $name di un filtro.

Heredoc ​

Un heredoc contiene testo su più righe — in pratica, SQL:

hcl
  sql = <<SQL
    SELECT 1
  SQL
  • Il delimitatore dopo << è una parola qualsiasi (SQL per convenzione), e nulla può seguirlo sulla sua riga.
  • L'heredoc termina alla prima riga che è esattamente il delimitatore, più o meno gli spazi intorno.
  • L'indentazione della riga di chiusura viene rimossa da ogni riga del testo, così l'SQL può stare all'indentazione del blocco senza portarsela dietro.

Regole SQL ​

Una dashboard esegue le sue query ogni volta che viene aperta, ricaricata o salvata, e quando DuckLocal parte con la scheda ripristinata — quindi una query può solo leggere:

  • Consentite: SELECT, WITH …, query che iniziano con FROM, VALUES, SHOW, DESCRIBE, SUMMARIZE, PIVOT e UNPIVOT.
  • Rifiutate: tutto ciò che potrebbe cambiare dati o file — CREATE, INSERT, UPDATE, DELETE, DROP, COPY, ATTACH, INSTALL, LOAD e così via. Aprire un file .dash che qualcuno ti ha inviato non può cambiare i tuoi dati.
  • Un'istruzione per query.
  • Un PIVOT dentro un'altra query indica i suoi valori. Una query che inizia con PIVOT può lasciare che sia DuckDB a trovare i valori (PIVOT orders ON channel USING sum(amount)). Uno annidato dentro un SELECT o un WITH ha bisogno di un elenco esplicito: ON channel IN ('Web', 'Store').
  • $name deve nominare un blocco filter. Il controllo di sola lettura giudica l'SQL con ogni $name come TRUE. Un $ dentro una stringa, un identificatore tra virgolette, un commento o una stringa $$ … $$ viene lasciato stare.

Le query girano sulla connessione propria della finestra, quindi vedono tutto ciò che vede l'editor SQL: file aperti, database collegati e stato a livello di connessione come le tabelle TEMP.

Percorsi nell'SQL ​

Dalla v0.2.2, i percorsi di file relativi nell'SQL di una dashboard vengono cercati anche nella cartella del file .dash. Per esempio, FROM 'sales.csv' può leggere il CSV accanto alla dashboard quando viene aperta da un'altra directory. Questo vale nella finestra e in ducklocal check.

DuckDB controlla comunque prima la directory di lavoro per un singolo file nominato direttamente nell'SQL: un file con lo stesso nome lì può avere la precedenza. Un blocco source risolve il suo percorso esplicitamente rispetto alla cartella della dashboard ed evita quell'ambiguità. I percorsi assoluti e le viste registrate restano disponibili.

Limiti ​

LimiteCosa succede
12 serie per graficoLe serie ulteriori vengono omesse, e un avviso dice quante erano
1.500 punti per serieI punti vengono mediati a blocchi per rientrare
200 barreLe barre ulteriori vengono omesse
8 fette di pieLe più piccole si fondono in un'unica fetta "altro"
200 colonne e 12 righe per heatmapLe colonne e le righe ulteriori vengono omesse
Da 5 a 40 intervalli di histogramCirca √righe, ciascuno largo 1, 2, 2,5 o 5 × una potenza di dieci
20.000 punti per mappaI punti ulteriori vengono omessi, e un avviso lo dice
12 corsie e 1.000 eventi per timelineGli eventi ulteriori vengono diradati in modo uniforme e un avviso lo dice; le righe il cui tempo non si può leggere vengono contate, non disegnate

Validare una dashboard ​

ducklocal check valida un file senza aprire una finestra — il passo da fare prima di affidare una dashboard a qualcuno:

bash
ducklocal check sales.dash
ducklocal check sales.dash --database warehouse.duckdb
ducklocal check sales.dash --summary

Prima i controlli statici: la sintassi, i nomi e i riferimenti, gli attributi obbligatori, ogni $name rispetto ai blocchi filter, e l'SQL di ogni query attraverso il parser di DuckDB. Poi ogni query viene eseguita, in sola lettura, con le sue sorgenti e senza nulla scelto, e le colonne di ogni grafico vengono confrontate con le colonne che la sua query restituisce davvero — compreso che y, le coordinate di una mappa e la sua size siano numeriche, e che la column di ogni filtro sia una che la query del suo grafico restituisce. Eseguire conta: un cast che fallisce o un glob che non corrisponde a nulla si vede solo quando le righe vengono lette.

  • Senza --database le query girano in memoria, che è tutto ciò di cui ha bisogno una dashboard sui propri file source. Una query che legge una tabella che nessuna sorgente definisce viene elencata sotto unresolved invece che fallita, e le colonne dei suoi grafici non vengono controllate — probabilmente è pensata per un database.
  • Con --database PATH girano contro quel database, aperto in sola lettura. Passalo ogni volta che le query leggono tabelle di un database.

Ogni query che usa un filtro viene anche verificata con un valore scelto, senza eseguire quella variante. Questo intercetta condizioni che si riferiscono a una colonna non disponibile in quella query. I blocchi con errori non impediscono di controllare i blocchi validi: la diagnostica include sia gli errori dello spec sia i fallimenti delle query della stessa esecuzione.

Il successo stampa un riepilogo JSON delle sorgenti, delle query (con le loro colonne di risultato e quante rows ciascuna ha restituito), dei filtri e dei grafici, più empty: le query che sono girate e non hanno restituito righe. Non è un errore, ma di solito è una regex, un filtro o un join che non ha trovato nulla, quindi controllale prima di affidare la dashboard. --summary stampa una riga JSON di conteggi e i nomi delle query non risolte e vuote. Un errore esce con stato 2 per la diagnostica dello spec ed elenca ogni problema in una volta, uno file:line: message ciascuno. I fallimenti solo SQL, di database o di file escono con 1. La guida alla CLI ha i dettagli.

Novità nella 0.4.0

ducklocal check FILE --restricted --allow-read PATH controlla con dei limiti una dashboard che non hai scritto tu. Vedi Limita l'SQL che non hai scritto.

Messaggi comuni ​

MessaggioSoluzione
type is a string in quotesScrivi type = "line", non type = line
Unknown plot type: "donut"; one of line, bar, area, scatter, pie, map, table, card, textUsa uno dei tipi elencati
plot block "p" requires yOgni tipo di grafico ha bisogno di una y; table, map, card e text no
plot "p" draws query "q", which the file does not defineAggiungi il blocco query, o correggi il nome in query = query.…
query names a query block: query = query.some_nameL'attributo query accetta un riferimento, non una stringa
plot "p" draws y = "channel" (VARCHAR), which is not numericPunta y su una colonna numerica, oppure usa type = "table"
A map plot places points by lat and lng; it takes no xUna mappa non ha assi: fornisci lat e lng, o lasciali ai nomi delle colonne
width is how many of the dashboard's 12 columns the plot spansScrivi un numero intero da 1 a 12
query "q" reads $chanel, but no filter block is named "chanel"Correggi il nome, o aggiungi il blocco filter
filter "f" picks on plot "p", a line; a value is picked on a bar or table plotPunta il filtro su un grafico a barre o su una tabella
a dashboard query must be a single read-only statementSposta le scritture nell'editor SQL, oppure indica i valori di un PIVOT annidato con IN; vedi Regole SQL
Unknown block: "card"; a card is a plot: plot "x" { type = "card" … }Ogni pannello è un blocco plot, anche le card e i pannelli di testo
"minutes" is a SQL keyword, so as a column alias it needs ASScrivi count(*) AS minutes, oppure metti l'alias tra virgolette
Unterminated heredoc: no line is exactly SQLAggiungi il delimitatore di chiusura su una riga propria

Modificare nel tuo editor ​

ducklocal lsp è un language server per i file .dash: diagnostica mentre scrivi, completamento per tipi di blocco, attributi, tipi di grafico e i nomi dopo query. e plot., documentazione al passaggio del mouse e vai-alla-definizione da un riferimento query.name o plot.name al suo blocco. La configurazione per Neovim e VS Code è nella guida alla CLI.

Pubblicato con licenza Apache-2.0.