# I tuoi primi 10 minuti

> Un tutorial di dieci minuti su DuckLocal con un CSV di esempio: interrogalo con SQL, crea un grafico dei risultati, esportali e poni la stessa domanda dalla CLI.

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

Un percorso guidato: apri un piccolo file di vendite, esegui qualche query, crea
grafici delle risposte ed esporta i risultati. Dà per scontato che DuckLocal sia
installato — se non lo è, inizia da [Per iniziare](getting-started.md).

## 1. Scarica il file di esempio {#sample-file}

Scarica [sales.csv](https://ducklocal.app/docs/samples/sales.csv), che contiene due settimane di dati di
ordini fittizi su 224 righe. Puoi anche scaricarlo dal terminale:

```bash
curl -LO https://ducklocal.app/docs/samples/sales.csv
```

Ha cinque colonne:

| Colonna | Tipo | Esempio |
| --- | --- | --- |
| `date` | DATE | `2026-09-01` |
| `channel` | VARCHAR | `Web`, `Mobile app`, `Store`, `Phone` |
| `region` | VARCHAR | `North`, `South`, `East`, `West` |
| `orders` | BIGINT | `72` |
| `revenue` | DOUBLE | `4181.04` |

Non hai dovuto dire nulla di tutto questo a DuckLocal: DuckDB legge
l'intestazione e deduce i tipi da solo.

## 2. Aprilo

Trascina `sales.csv` sulla finestra di DuckLocal. (Oppure fai clic su **Apri
file…**, o esegui `ducklocal sales.csv` se hai [aggiunto il
comando](getting-started.md#add-command).)

Una notifica conferma **Vista sales creata.** Nella barra laterale, **File
locali** ora elenca `sales` con le sue 224 righe; espandilo per vedere le colonne
e i loro tipi.

## 3. Guarda le righe

Nella barra laterale, fai clic sul pulsante di riproduzione accanto a `sales`.
L'editor si riempie con un `SELECT * … LIMIT 100` per quella tabella — premi
**⌘↵** per eseguirlo.

La griglia sotto l'editor mostra le righe. Prova il campo filtro sopra di essa:
digita `Store` e premi Invio per tenere solo le righe che lo menzionano. Il
filtro lavora sulle righe già caricate e non riesegue mai la query.

## 4. Poni una domanda

Sostituisci l'SQL con questo e premi **⌘↵**:

```sql
SELECT channel, round(sum(revenue), 2) AS revenue
FROM sales
GROUP BY channel
ORDER BY revenue DESC;
```

| channel | revenue |
| --- | --- |
| Mobile app | 290549.76 |
| Web | 289544.8 |
| Store | 240067.6 |
| Phone | 82511.2 |

Ora passa il pannello dei risultati da **Risultati** a **Grafico**. Poiché la
prima colonna è testo, ottieni una barra per canale, dimensionata in base alla
prima colonna numerica.

::: tip Completamento automatico
Mentre scrivi, l'editor propone prima i nomi di tabelle e colonne della barra
laterale, poi le funzioni DuckDB e le parole chiave SQL — digita `rev` e
`revenue` è il primo suggerimento.
:::

## 5. Metti un andamento in un grafico

I grafici sono disegnati dalle righe esattamente come la query le restituisce,
quindi dai al risultato la forma con cui vuoi che venga tracciato. Una colonna
per canale dà una linea per canale:

```sql
SELECT
  date,
  round(sum(revenue) FILTER (WHERE channel = 'Web'), 2)        AS web,
  round(sum(revenue) FILTER (WHERE channel = 'Mobile app'), 2) AS mobile,
  round(sum(revenue) FILTER (WHERE channel = 'Store'), 2)      AS store
FROM sales
GROUP BY date
ORDER BY date;
```

`FILTER (WHERE …)` aggrega solo le righe che corrispondono (sintassi DuckDB).

Con una data nella prima colonna, **Grafico** disegna un grafico ad area nel
tempo, una serie per colonna numerica. [Risultati e
grafici](results-and-charts.md) illustra regole e limiti.

## 6. Esporta la risposta

**L'esportazione sovrascrive un file esistente senza chiedere.** Con l'andamento
ancora nel pannello dei risultati, fai clic su **Esporta CSV**. La finestra di
dialogo propone `~/Desktop/export.csv`; cambia il percorso se vuoi e conferma.

L'esportazione riesegue la query, quindi il file contiene il risultato completo —
non solo ciò che è visibile nella griglia.

## 7. Ritrovalo domani

Apri la scheda **Cronologia** nella barra laterale: ogni query che hai eseguito è
lì, comprese quelle fallite. Fai clic su una voce per rimettere quella query
nell'editor, sostituendo quello che l'editor contiene in quel momento.

Esci da DuckLocal e avvialo di nuovo. `sales` è ancora in **File locali**: i file
aperti vengono ricordati per percorso e riletti a ogni avvio, quindi una modifica
al CSV si vede la prossima volta che lo interroghi.

## 8. Bonus: la stessa domanda da un terminale

Se hai aggiunto il comando `ducklocal`, la CLI risponde senza aprire una finestra
— comodo per gli script e per gli agenti AI:

```bash
ducklocal query --format md --sql "
  SELECT channel, round(sum(revenue), 2) AS revenue
  FROM 'sales.csv' GROUP BY channel ORDER BY revenue DESC"
```

Ometti `--format md` per avere JSON strutturato. La [guida alla CLI](cli.md) e la
skill ufficiale per agenti — un pacchetto di skill che gli assistenti AI di
programmazione possono chiamare — sono il punto da cui partire.

## Avanti

- Provalo su dati reali: 3,5 milioni di corse in taxi, interrogate via HTTPS — vedi [Esempio: corse in taxi a New York](example-nyc-taxi.md)
- Punta DuckLocal sui tuoi file o sulle tue cartelle — vedi [Sorgenti di dati](data-sources.md)
- Interroga file in uno storage compatibile con S3 — vedi [S3 e httpfs](s3.md)
- Costruisci una dashboard di query salvate — vedi [Dashboard (.dash)](dashboards.md)
