# Dashboard (.dash)

> Crea dashboard di DuckLocal come file .dash di SQL DuckDB: grafici, cross-filter, commenti a cui un agente AI può rispondere, e validazione con ducklocal check.

Source: https://ducklocal.app/docs/it/dashboards

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](#review-with-comments) per chiedere modifiche.

## Un esempio completo {#a-complete-example}

Questa dashboard interroga il [file di esempio del tutorial](tutorial.md#sample-file).
Scarica [sales.dash](https://ducklocal.app/docs/samples/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](cli.md#show-work-in-the-running-window)).

I grafici sono disposti su una griglia di 12 colonne: ognuno occupa la sua
[`width`](#layout), 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](#review-with-comments) 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](#filters) 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 {#review-with-comments}

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](https://ducklocal.app/it/blog/claude-dashboards-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`](cli.md#review-comments-on-a-dashboard), 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](cli.md#install-the-official-skill) insegna questo
ciclo, quindi a un agente che ce l'ha basta dire *"risolvi i commenti su
sales.dash"*.

::: info Novità nella 0.4.0
Un agente può [proporre una modifica](agent-workflows.md#propose) 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 {#agent-presence}

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](cli.md#agent-presence) illustra le opzioni. Questi indicatori mostrano
attività locale; non inviano lavoro a un agente.

## Blocchi {#blocks}

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.

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

| Attributo | Obbligatorio | Valore |
| --- | --- | --- |
| `path` | sì | 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

| Attributo | Obbligatorio | Valore |
| --- | --- | --- |
| `sql` | sì | Una sola istruzione SQL in sola lettura, come [heredoc](#heredocs) o come stringa |

Un blocco query contiene `sql` e nient'altro. Può leggere `$name` per un
[filtro](#filters).

### plot

| Attributo | Per | Valore |
| --- | --- | --- |
| `type` | tutti, obbligatorio | `"line"`, `"bar"`, `"stacked_bar"`, `"area"`, `"scatter"`, `"pie"`, `"heatmap"`, `"histogram"`, `"map"`, `"timeline"`, `"table"`, `"card"` o `"text"` — una stringa tra virgolette |
| `query` | tutti tranne `text`, obbligatorio | Un riferimento a un blocco query: `query.by_channel` |
| `x` | grafici, obbligatorio | La colonna sull'asse orizzontale; le fette di un `pie`; il numero che un `histogram` suddivide in intervalli; il tempo di un `timeline` |
| `y` | grafici, obbligatorio | La colonna da tracciare; deve essere numerica. La dimensione delle fette di un `pie`. Un `histogram` e un `timeline` non ne prendono |
| `series` | `line`, `bar`, `stacked_bar`, `area`, `scatter`, `heatmap`, `timeline` | Una colonna i cui valori dividono le righe in una serie ciascuno; le righe di un `heatmap`; le corsie di un `timeline` |
| `title` | tutti | Un titolo per il grafico, come stringa tra virgolette; l'etichetta di una card |
| `width` | tutti | Quante delle 12 colonne della griglia occupa il grafico, `1`–`12`. Predefinito 12, o 3 per una card |
| `value` | `card` | La colonna da mostrare, dalla prima riga. Predefinito: la prima colonna |
| `note` | `card` | Testo sotto il valore: una stringa tra virgolette, o un nome di colonna nudo da leggere dalla prima riga |
| `tone` | `card` | `"accent"`, `"good"`, `"warning"` o `"critical"`; colora la riga superiore e il valore |
| `format` | grafici e `card` | Che cosa sono i numeri: vedi [Formati numerici e variazione](#number-formats-and-change). Un `map` o un `table` non ne prendono |
| `delta` | `card` | Una colonna numerica che contiene la variazione, mostrata sotto il valore |
| `delta_format` | `card` | Un formato per la variazione. Predefinito: quello della card |
| `down_is_good` | `card` | `true` rende verde una caduta e rossa una salita, per costi, latenza o abbandoni |
| `description` | tutti, **0.4.0+** | Cosa mostra il grafico e come leggerlo; compare passando il mouse su un ⓘ accanto al titolo |
| `text` | `text` | Testo del corpo come stringa o heredoc; fornisci `title`, `text` o entrambi, senza `query` |
| `caption` | `timeline` | La colonna che dice cos'è stato ogni evento, scritta sotto il suo punto dove ci sta e al passaggio del mouse |
| `lat`, `lng` | `map` | Colonne 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` |
| `color` | `map` | Una colonna per colorare i punti; se omessa, se ne sceglie una quando una colonna di testo ha pochi valori |
| `size` | `map` | Una colonna numerica per dimensionare i punti |
| `size_scale` | `map` | `"sqrt"` (il predefinito) o `"log"`, per come scala `size` |
| `tooltip` | `map` | Un 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

| Attributo | Obbligatorio | Valore |
| --- | --- | --- |
| `plot` | sì | Il grafico su cui un clic sceglie un valore: `plot.revenue_by_channel`. Un `bar`, uno `stacked_bar` o un `table` |
| `column` | per un `table` | La colonna il cui valore viene scelto. Per un `bar` o uno `stacked_bar`, la sua `x` se omessa |
| `multiple` | `bar`, `stacked_bar` | `true` 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](#filters) 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 {#plot-types}

| Tipo | Disegna |
| --- | --- |
| `line` | Una linea per serie, non riempita |
| `area` | Un'area riempita per serie |
| `bar` | Una 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_bar` | Una 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 |
| `heatmap` | `x` 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 |
| `histogram` | Le 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 |
| `scatter` | Un punto per punto, non collegati, un colore per serie |
| `pie` | Una 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 |
| `text` | Un titolo, un testo esplicativo, o entrambi; nessuna query viene eseguita |
| `map` | Un punto per riga, alla sua `lat` e `lng`; vedi [Mappe](#maps) |
| `timeline` | Un 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 |
| `table` | Il risultato della query come griglia, con le colonne dimensionate sul loro contenuto; fai clic su un'intestazione per ordinare |
| `card` | Un 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.

::: info 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 {#cards-and-text-panels}

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 {#number-formats-and-change}

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

| Valore | Legge |
| --- | --- |
| `"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 {#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 {#maps}

```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](settings-and-data.md#where-things-are-stored));
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 {#filters}

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.

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

| Forma | Esempio | Usata per |
| --- | --- | --- |
| Stringa | `"Revenue by channel"` | `type`, `title`, `path`, `size_scale`, `tone`, `note` letterale, `text`, nomi di colonna tra virgolette, `sql` brevi |
| Heredoc | `<<SQL` … `SQL` | `sql`, `text` |
| Riferimento | `query.daily`, `plot.revenue_by_channel` | la `query` di un grafico, il `plot` di un filtro |
| Nome nudo | `channel` | attributi di colonna |
| Numero | `6` | `width` |
| 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 {#heredocs}

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 {#sql-rules}

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](#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

| Limite | Cosa succede |
| --- | --- |
| 12 serie per grafico | Le serie ulteriori vengono omesse, e un avviso dice quante erano |
| 1.500 punti per serie | I punti vengono mediati a blocchi per rientrare |
| 200 barre | Le barre ulteriori vengono omesse |
| 8 fette di pie | Le più piccole si fondono in un'unica fetta "altro" |
| 200 colonne e 12 righe per heatmap | Le colonne e le righe ulteriori vengono omesse |
| Da 5 a 40 intervalli di histogram | Circa √righe, ciascuno largo 1, 2, 2,5 o 5 × una potenza di dieci |
| 20.000 punti per mappa | I punti ulteriori vengono omessi, e un avviso lo dice |
| 12 corsie e 1.000 eventi per timeline | Gli 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 {#validate-a-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](cli.md#check-a-dashboard-spec) ha i dettagli.

::: info 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](agent-workflows.md#restricted).
:::

### Messaggi comuni

| Messaggio | Soluzione |
| --- | --- |
| `type is a string in quotes` | Scrivi `type = "line"`, non `type = line` |
| `Unknown plot type: "donut"; one of line, bar, area, scatter, pie, map, table, card, text` | Usa uno dei tipi elencati |
| `plot block "p" requires y` | Ogni tipo di grafico ha bisogno di una `y`; `table`, `map`, `card` e `text` no |
| `plot "p" draws query "q", which the file does not define` | Aggiungi il blocco query, o correggi il nome in `query = query.…` |
| `query names a query block: query = query.some_name` | L'attributo `query` accetta un riferimento, non una stringa |
| `plot "p" draws y = "channel" (VARCHAR), which is not numeric` | Punta `y` su una colonna numerica, oppure usa `type = "table"` |
| `A map plot places points by lat and lng; it takes no x` | Una 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 spans` | Scrivi 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 plot` | Punta il filtro su un grafico a barre o su una tabella |
| `a dashboard query must be a single read-only statement` | Sposta le scritture nell'editor SQL, oppure indica i valori di un `PIVOT` annidato con `IN`; vedi [Regole SQL](#sql-rules) |
| `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 AS` | Scrivi `count(*) AS minutes`, oppure metti l'alias tra virgolette |
| `Unterminated heredoc: no line is exactly SQL` | Aggiungi 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](cli.md#edit-a-dashboard-spec-with-lsp).
