# Sorgenti di dati

> Interroga file CSV, Parquet, JSON ed Excel in locale con SQL di DuckDB. Apri cartelle e glob, collega database e tieni i dati sul tuo computer.

Source: https://ducklocal.app/docs/it/data-sources

DuckLocal trasforma i file in viste in una connessione DuckDB in memoria, oppure
in un file di database se ne hai aperto uno. Altri database possono stare
accanto. Non c'è nulla da configurare. Vedi il [flusso di lavoro per l'analisi
dei dati locali](https://ducklocal.app/it/use-cases/local-data-analysis/) per un
percorso sintetico dai file all'SQL, ai grafici e all'esportazione.

## Modi per aprire i dati

Tutti passano dalle stesse regole di risoluzione:

1. Percorsi sulla riga di comando — `ducklocal ./logs/ billing.parquet`
2. Il menu **Apri** nella barra del titolo: **Apri file**, **Apri cartella**, o
   **Inserisci un percorso o un glob**, che apre la finestra di dialogo **Apri dati** per un
   percorso digitato o scelto dal selettore nativo
3. Trascinare file o cartelle ovunque nella finestra
4. Su un Mac, i file che il Finder passa a DuckLocal — vedi
   [Aprire dal Finder](#open-from-finder)

Per aggiungere un database accanto a quello aperto invece di sostituirlo, usa
**Apri → Collega database…** — vedi [Database collegati](#attached-databases).

Su macOS, puoi fare doppio clic sui file Parquet e DuckDB nel Finder per aprirli,
oppure premere la barra spaziatrice per visualizzare in anteprima le righe
iniziali dei file Parquet, DuckDB, CSV, TSV e JSON Lines con Quick Look senza
avviare DuckLocal.

## Formati di file supportati {#supported-file-formats}

Le estensioni vengono riconosciute senza distinzione tra maiuscole e minuscole.

| Estensione | Come viene letto |
| --- | --- |
| `.csv`, `.tsv`, `.txt` | vista `read_csv_auto` |
| `.parquet` | vista `read_parquet` |
| `.json`, `.ndjson`, `.jsonl` | vista `read_json_auto` |
| `.xlsx`, `.xls`, `.xlsb`, `.ods` | importato come tabella, una per foglio |

Anche il testo compresso con gzip come `.json.gz` e `.csv.gz` conta come file di
dati, in `schema`, nei blocchi `source` e quando colleghi un file; `logs.json.gz`
diventa una vista chiamata `logs`. Prima della 0.4.0, `ducklocal schema` provava
un file così come database; su una copia più vecchia, leggilo in SQL con
`read_json` o `read_csv`.

Qualsiasi altra cosa non è un file di dati — vedi [File di
database](#database-files).

Una cartella di lavoro è l'unico formato che diventa **tabelle**, non viste, e
importa **tutti i fogli**: il primo foglio prende il nome del file senza la sua
estensione, gli altri si chiamano `{stem}_{sheet name}`. Un foglio
vuoto viene saltato. I tipi delle colonne vengono dedotti dalle celle — gli
interi diventano `BIGINT`, una miscela di interi e decimali `DOUBLE`, le date
`TIMESTAMP`, e qualsiasi valore misto o non riconosciuto `VARCHAR`; le celle
vuote vengono importate come `NULL`.

## Cartelle e pattern {#folders-and-patterns}

Una **directory** viene percorsa in modo ricorsivo, e ogni file di dati al suo
interno diventa una vista. Alla scansione si applicano due regole:

- Le voci nascoste (nomi che iniziano con `.`) vengono saltate, e non si scende
  nei loro sottoalberi.
- I symlink non vengono seguiti. Seguire un link che risale l'albero non
  terminerebbe mai, e la directory collegata di solito viene percorsa dove si
  trova davvero.

I file vengono collegati in ordine, quindi la stessa cartella produce sempre lo
stesso spazio di lavoro.

Un **pattern** può contenere `*` (qualsiasi sequenza di caratteri) e `?`
(esattamente un carattere). La corrispondenza avviene per componente del
percorso, sul filesystem, quindi un pattern può attraversare più directory:

```bash
ducklocal './data/2026-0*/*.parquet'
```

Non c'è un carattere di escape. `**` non è speciale — si comporta come un singolo
`*` e non ricorre. Un pattern che corrisponde a una directory la salta; vengono
collegati solo i file. Anche qui le voci nascoste vengono saltate.

I pattern senza virgolette vengono espansi dalla shell prima che DuckLocal li
veda. Va bene così. Metti un pattern tra virgolette solo quando vuoi che sia
DuckLocal a espanderlo — per esempio, quando la shell non trova corrispondenze e
altrimenti darebbe errore.

## Molti file CSV insieme {#many-csv-files-at-once}

Ogni file che DuckLocal collega diventa una vista con il proprio schema dedotto,
quindi due CSV in disaccordo non si rovinano mai a vicenda. Le insidie emergono
quando un'unica lettura SQL attraversa molti file:

```sql
SELECT * FROM read_csv('data/*.csv', union_by_name = true)
```

- **Il rilevamento dei tipi può essere incoerente tra i file.** Il lettore deduce
  il tipo di una colonna da un campione; una colonna che è numerica ovunque ma
  contiene una stringa `'NULL'` sparsa in un file fa fallire tutta la lettura con
  un errore di conversione, e un cast nella lista del `SELECT` arriva troppo
  tardi — è la lettura stessa a dare errore. Leggi ogni colonna come testo e
  converti in SQL:

  ```sql
  SELECT try_cast(amount AS DOUBLE) AS amount
  FROM read_csv('data/*.csv', union_by_name = true, all_varchar = true)
  ```

  `union_by_name = true` tollera anche file con insiemi di colonne diversi.
- **La stringa `'NULL'` non è `NULL`.** Un `'NULL'` letterale (o `'N/A'`,
  `'null'`) in un CSV è testo normale, quindi `WHERE amount IS NOT NULL` non lo
  filtra. Usa `NULLIF(amount, 'NULL')`, oppure `WHERE amount <> 'NULL'`.

Le due correzioni si combinano: `try_cast(NULLIF(amount, 'NULL') AS DOUBLE)`.

## File di database {#database-files}

DuckLocal ha un solo **database principale** alla volta: in memoria, oppure un
file DuckDB che hai aperto. I file di dati diventano viste nel database
principale. Puoi anche [collegare altri database accanto a
esso](#attached-databases).

Qualsiasi percorso che **esiste** e non è un file di dati viene aperto come
database principale invece di essere collegato come vista. L'estensione non
conta: un percorso `.db`, `.duckdb` o persino `.md` viene trattato come
database, ed è DuckDB a decidere se può essere aperto davvero.

Vale la pena conoscere alcune conseguenze:

- **Un nuovo database nasce solo dalla finestra Apri dati.** Digita un percorso
  che termina in `.duckdb` e non esiste ancora, e DuckLocal crea il database,
  insieme a tutte le cartelle superiori mancanti. In ogni altro posto — la riga
  di comando, i selettori, un trascinamento, il Finder — un percorso che non
  esiste viene segnalato come `File not found`.
- **Aprire un database sostituisce quello principale.** I tuoi file registrati e
  i database collegati vengono collegati di nuovo nella nuova connessione. Le
  credenziali S3 no: configura di nuovo S3.
- **Se il file non si può aprire**, DuckLocal ti dice perché
  ([sotto](#when-a-database-will-not-open)). All'avvio ricade su uno spazio di
  lavoro in memoria invece di non partire. Mentre è in esecuzione, lo spazio di
  lavoro che avevi resta com'era.
- **Un file già collegato** accanto al database principale viene prima
  scollegato, poi aperto come database principale. Se quell'apertura fallisce,
  il collegamento torna. Aprire il file che è già il database principale lo
  riutilizza.

Collegare file di dati mentre è aperto un file di database **scrive quelle viste
in quel file di database** — restano lì in modo persistente, non solo nella
sessione.

### Quando un database non si apre {#when-a-database-will-not-open}

Quando DuckDB rifiuta un file, DuckLocal legge da sé i primi byte del file e,
dove questi spiegano il fallimento, mette un motivo e una via d'uscita sopra il
messaggio di DuckDB. Il messaggio di DuckDB resta sotto per l'errore esatto. La
spiegazione è nella lingua dell'interfaccia.

| Che cos'è il file | Cosa ti dice DuckLocal |
| --- | --- |
| Un file DuckDB scritto da un **DuckDB più recente** di quello integrato in DuckLocal | Entrambe le versioni, e l'SQL da eseguire nel DuckDB più recente che copia il file in un formato che DuckLocal legge (sotto) |
| Un file DuckDB della **v0.9 o precedente** | Esegui `EXPORT DATABASE 'dir'` con il DuckDB che l'ha scritto, poi `IMPORT DATABASE 'dir'` in DuckLocal |
| Un database **SQLite** | Non è un file DuckDB; collegalo invece — con [Collega database…](#attached-databases), oppure `INSTALL sqlite; ATTACH '…' (TYPE sqlite);` |
| Qualcos'altro che **non è un file DuckDB** | Apri invece file CSV, Parquet, JSON o Excel come file di dati |

Per un file di un DuckDB più recente, il messaggio riporta il percorso del file e
la versione di DuckDB di DuckLocal. Esegui questo nel DuckDB che ha creato il
file, poi apri `compat.duckdb`:

```sql
ATTACH '/path/to/file.duckdb' AS src (READ_ONLY);
ATTACH 'compat.duckdb' AS dst (STORAGE_VERSION 'v2.0.0');
COPY FROM DATABASE src TO dst;
```

I file scritti prima di DuckDB v1.2 non registrano quale release li ha creati.
Qualsiasi altro fallimento — un file bloccato da un altro programma, uno che non
puoi leggere — mostra solo il messaggio di DuckDB. Vedi [Risoluzione dei
problemi](troubleshooting.md#opening-a-database).

### Quale DuckDB può leggere un database {#storage-version}

Quando è aperto un file di database, la barra di stato mostra il suo percorso.
Passa il mouse sopra per vedere il formato di archiviazione del file — il DuckDB
più vecchio che lo legge, per esempio **Formato di archiviazione: leggibile da
DuckDB v1.0.0+** — e, quando il file lo registra, la release che l'ha creato
(**Creato da DuckDB v1.4.3**). Controllalo prima di passare un file a qualcuno
con un DuckDB più vecchio.

DuckLocal esegue DuckDB 2.0, ma un file di database che crea viene scritto nel
formato che scriveva DuckDB 1.x (**leggibile da DuckDB v1.0.0+**), quindi la CLI
duckdb, Python o DBeaver su DuckDB 1.x lo aprono ancora. Anche un file scritto da
un altro programma nel formato proprio di DuckDB 2.0 (**v2.0.0+**) si apre, e
mantiene quel formato: la 1.x non può leggerlo.

## Database collegati {#attached-databases}

Collega un altro file DuckDB o SQLite accanto al database principale per
interrogare entrambi — una copia istantanea accanto ai dati di oggi, per esempio.

1. Apri il menu **Apri** nella barra del titolo e scegli **Collega database…**.
2. Digita il percorso, oppure fai clic su **Sfoglia** per scegliere il file.
3. Lascia selezionato **Sola lettura** a meno che tu non voglia modificare il
   file. È selezionato per impostazione predefinita.
4. Fai clic su **Collega**.

Il database prende un **alias** dal nome del file, e interroghi le sue tabelle
come `alias.table` (o `alias.schema.table`):

```sql
-- snap-2026-10-01.duckdb attached as snap_2026_10_01
SELECT t.id, t.amount, s.amount AS amount_last_week
FROM orders t
JOIN snap_2026_10_01.orders s USING (id);
```

Come viene creato l'alias:

- Il nome del file senza estensione, con ogni carattere che non è una lettera
  ASCII o una cifra sostituito da `_`.
- `db_` davanti quando non inizia con una lettera: `2026-10 logs.duckdb` diventa
  `db_2026_10_logs`.
- Un contatore quando il nome è già usato: `snap`, poi `snap_2`. `main` non
  viene mai usato.
- Collegando di nuovo lo stesso file più tardi, gli viene restituito l'alias che
  aveva, così l'SQL scritto contro di esso continua a funzionare.

Dettagli:

- **I file SQLite** vengono riconosciuti dal loro contenuto e collegati tramite
  l'estensione `sqlite` di DuckDB.
- **Deselezionando Sola lettura** il file viene collegato in scrittura. Un
  percorso DuckDB che non esiste viene quindi creato come nuovo database vuoto;
  in sola lettura, invece, il collegamento fallisce.
- **Lo stesso file non viene mai collegato due volte.** Collegare un file già
  aperto — come database principale o come collegamento — dice *Questo database
  è già aperto, come …*.

### Nella barra laterale {#in-the-sidebar}

Ogni database compare nell'albero dello schema, quello principale e quelli
collegati allo stesso modo, compresi quelli vuoti. Un database mostra **sola
lettura** o **sqlite** accanto al nome dove vale, e il suo file come tooltip.

Fai clic destro su un database per:

- **Usa come database predefinito** — esegue `USE`, così i nomi di tabella senza
  database si risolvono lì. La barra di stato mostra dove si risolvono adesso.
- **Scollega database** — lo scollega e lo dimentica, così non torna la prossima
  volta. Se era il database predefinito, la sessione torna prima al database
  principale. Il file in sé non viene toccato.

Il resto di quel menu è descritto in [Browser dello schema e
cronologia](schema-and-history.md).

### Conservati tra le connessioni {#kept-across-connections}

I database collegati sono memorizzati nel database di cronologia di DuckLocal,
con il loro alias e l'impostazione di sola lettura, e vengono collegati di nuovo
in ogni nuova connessione: al prossimo avvio, dopo che apri un altro database, e
dopo **Nuovo database in memoria**.

- Un database il cui file **manca** viene saltato in silenzio. La sua
  registrazione resta, così torna quando il file torna — DuckLocal non crea mai
  un database vuoto al suo posto.
- Un database **già aperto**, come database principale o in altro modo, non
  viene collegato una seconda volta.
- Se il nuovo database principale ha già un database con quell'alias, DuckLocal
  dice *Impossibile collegare …: il nome … è già usato nel database aperto.*

## Aprire dal Finder {#open-from-finder}

Su un Mac, il Finder può passare i file direttamente a DuckLocal:

| File | Doppio clic | Apri con, o trascina sull'icona del Dock |
| --- | --- | --- |
| `.parquet` | Si apre in DuckLocal | Sì |
| `.duckdb`, `.ddb` | Si apre in DuckLocal | Sì |
| `.dash` | Si apre in DuckLocal | Sì |
| `.csv`, `.tsv`, `.json`, `.jsonl`, `.ndjson`, `.xlsx`, `.xls` | Restano con l'app che li apre già (Numbers, Excel, un editor di testo) | Sì |

DuckLocal si registra come predefinito solo per i formati che nessun altro su un
Mac rivendica. Se un'altra app ha già preso i file Parquet o DuckDB, scegli
DuckLocal in **Apri con** — oppure usa **Ottieni informazioni → Apri con →
Cambia tutto…** del Finder per renderlo predefinito.

Un file dal Finder viene gestito esattamente come un trascinamento sulla
finestra: un file di dati diventa una vista nello spazio di lavoro corrente, un
file di database viene aperto come database principale, e un file `.dash` si
apre come scheda [dashboard](dashboards.md). Se DuckLocal non è in esecuzione, si
avvia prima e apre il file quando il suo avvio è terminato.

## Anteprime Quick Look {#quick-look}

Su un Mac, seleziona un file di dati nel Finder e premi **Spazio** per vederne le
colonne e le prime righe senza aprire nulla. L'anteprima è inclusa in
DuckLocal.app; non c'è nulla da installare a parte. Richiede macOS 12 o
successivo, come l'app.

| File | Cosa mostra l'anteprima |
| --- | --- |
| `.parquet` | Colonne e tipi, le prime 50 righe e, dal footer del file: numero di righe, row group, compressione e il writer |
| `.duckdb`, `.ddb` | Il numero di tabelle, il formato di archiviazione (**Leggibile da DuckDB …**) e le cinque tabelle più grandi, ciascuna con il numero di righe stimato e le prime 50 righe |
| `.csv`, `.tsv` | Colonne con i tipi dedotti e le prime 50 righe — una tabella invece di testo grezzo |
| `.jsonl`, `.ndjson` | Colonne e le prime 50 righe |

I file `.json` semplici e i file Excel sono lasciati alle anteprime di macOS.

Cosa fa e cosa non fa l'anteprima:

- Non scrive mai. Un database viene collegato in sola lettura.
- Non scansiona mai un file intero: le righe sono un `LIMIT`, e un conteggio di
  righe compare solo dove il formato lo memorizza (il footer di Parquet, la
  stima di un database).
- Non scarica nulla: le estensioni DuckDB non vengono né installate né caricate.
- Le celle più lunghe di 200 caratteri vengono troncate. Il testo della pagina è
  in inglese.
- Un file che non riesce a leggere ottiene una pagina che ne spiega il motivo.

Se premendo Spazio non compare l'anteprima di DuckLocal:

1. Assicurati che DuckLocal sia in **Applicazioni** e avvialo una volta. macOS
   registra l'anteprima quando vede l'app per la prima volta.
2. Reimposta Quick Look nel Terminale: `qlmanage -r`. Poi riprova.
3. Controlla che **Anteprima DuckLocal** sia attiva sotto Quick Look nelle
   impostazioni delle estensioni di Impostazioni di Sistema.

## Denominazione

La vista di un file prende il nome del file senza estensione, ripulito in un
identificatore valido. Quando quel nome è già usato nella connessione, DuckLocal
aggiunge un contatore: `events`, poi `events_2`, `events_3`. Due file con lo
stesso nome in directory diverse ottengono quindi viste distinte.

La rilevazione dei duplicati avviene sul testo del percorso così come è scritto,
quindi `./a.csv` e `a.csv` sono trattati come due file diversi.

## Limiti

- **256 file di dati per richiesta di apertura.** Il limite copre insieme tutti i
  percorsi di una richiesta, non ogni cartella separatamente — esiste perché
  trascinare per sbaglio una home directory non blocchi la connessione per
  minuti. Quando il limite viene raggiunto, DuckLocal lo dice e collega i primi
  256 file.
- I file ricollegati all'avvio dalla sessione precedente non sono soggetti a quel
  limite.

## Gestire le sorgenti registrate

I file registrati compaiono nel gruppo **File locali** della barra laterale,
ciascuno con il nome della vista, il nome del file e il numero di righe.
Selezionando un file viene generata un'istruzione `SELECT` per esso.

La **×** su una riga di file lo rimuove, dopo una finestra di dialogo di conferma. La
rimozione elimina la vista e dimentica la registrazione; **il file sottostante
non viene toccato.**

**Aggiorna schema** ricarica il catalogo e i file registrati.

## Cosa viene ricordato

L'elenco dei file registrati — i loro percorsi, nomi di vista e tipi — è
memorizzato nel database di cronologia di DuckLocal e ricollegato al prossimo
avvio, quindi lo spazio di lavoro che hai lasciato è quello che ritrovi. Lo
stesso vale per i [database collegati](#kept-across-connections). Il file del
database principale *non* viene ricordato: ogni avvio parte in memoria a meno che
tu non indichi un database.

Vedi [Impostazioni e dati dell'app](settings-and-data.md) per le posizioni su
disco.
