Sorgenti di dati
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 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:
- Percorsi sulla riga di comando —
ducklocal ./logs/ billing.parquet - 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
- Trascinare file o cartelle ovunque nella finestra
- Su un Mac, i file che il Finder passa a DuckLocal — vedi Aprire dal Finder
Per aggiungere un database accanto a quello aperto invece di sostituirlo, usa Apri → Collega database… — vedi Database collegati.
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
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.
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
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:
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
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:
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 delSELECTarriva troppo tardi — è la lettura stessa a dare errore. Leggi ogni colonna come testo e converti in SQL:sqlSELECT try_cast(amount AS DOUBLE) AS amount FROM read_csv('data/*.csv', union_by_name = true, all_varchar = true)union_by_name = truetollera anche file con insiemi di colonne diversi.La stringa
'NULL'non èNULL. Un'NULL'letterale (o'N/A','null') in un CSV è testo normale, quindiWHERE amount IS NOT NULLnon lo filtra. UsaNULLIF(amount, 'NULL'), oppureWHERE amount <> 'NULL'.
Le due correzioni si combinano: try_cast(NULLIF(amount, 'NULL') AS DOUBLE).
File di database
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.
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
.duckdbe 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 comeFile 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). 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
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…, 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:
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.
Quale DuckDB può leggere un database
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
Collega un altro file DuckDB o SQLite accanto al database principale per interrogare entrambi — una copia istantanea accanto ai dati di oggi, per esempio.
- Apri il menu Apri nella barra del titolo e scegli Collega database….
- Digita il percorso, oppure fai clic su Sfoglia per scegliere il file.
- Lascia selezionato Sola lettura a meno che tu non voglia modificare il file. È selezionato per impostazione predefinita.
- 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):
-- 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.duckdbdiventadb_2026_10_logs.- Un contatore quando il nome è già usato:
snap, poisnap_2.mainnon 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
sqlitedi 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
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.
Conservati tra le connessioni
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
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. Se DuckLocal non è in esecuzione, si avvia prima e apre il file quando il suo avvio è terminato.
Anteprime 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:
- Assicurati che DuckLocal sia in Applicazioni e avvialo una volta. macOS registra l'anteprima quando vede l'app per la prima volta.
- Reimposta Quick Look nel Terminale:
qlmanage -r. Poi riprova. - 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. 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 per le posizioni su disco.
