Browser dello schema e cronologia
La barra laterale ha tre schede: Schema, Cronologia ed Estensioni (表结构, 查询历史 e 扩展 in cinese). Il pulsante a sinistra della barra del titolo, o ⌘B, nasconde la barra laterale e la riporta; il pulsante resta nello stesso posto in entrambi i casi. Viene ricordato se la barra laterale è nascosta.
L'albero dello schema
Dall'alto in basso, l'albero mostra File locali, Dashboard, Metriche e S3 come piccole intestazioni grigie, seguiti dai tuoi database in righe in grassetto:
- File locali — i file di dati che hai registrato, ciascuno chiamato con il nome della sua vista, con il suo numero di righe. I suoi figli sono le colonne della vista.
- Il nome del file compare accanto al nome della vista solo quando i due differiscono (
sales_2dasales.csv). - La cartella compare quando due file condividono il nome di una vista.
- Passa il mouse su una riga per il percorso completo.
- Il nome del file compare accanto al nome della vista solo quando i due differiscono (
- Dashboard — le dashboard
.dashche hai aperto di recente, ordinate per nome, così una riga resta ferma quando ci fai clic.- Fai clic su una per riaprirla come scheda, come faresti con un file.
- Due dashboard con lo stesso nome mostrano la loro cartella accanto. Un file raggiunto da due grafie del suo percorso (
E:\ProjeE:\proj, o un percorso relativo e uno assoluto) è una sola voce, e apre una sola scheda. - La × al passaggio del mouse la toglie dall'elenco, lasciando intatti i suoi file e qualsiasi scheda aperta.
- Una voce il cui percorso non esiste più viene eliminata dall'elenco.
- Metriche — presente quando accanto a una di queste dashboard c'è un
model.ossie.yaml. Una riga per metrica; un clic la compila nell'editor di query e la esegue. Vedi Metriche semantiche. Successivo alla 0.4.1. - S3 — presente una volta che S3 è configurato. Si carica in modo differito.
- Ogni database, poi i suoi schemi, poi tabelle e viste, poi le colonne. Il database con cui la finestra è stata aperta viene per primo; i database collegati accanto vengono dopo, contrassegnati
read-onlyquando sono collegati così.
Le tabelle mostrano conteggi di righe stimati; le viste no. Le voci delle colonne mostrano i tipi di dati DuckDB. Il database di sistema e gli schemi information_schema, pg_catalog e system sono nascosti.
Il campo di ricerca sopra l'albero (Cerca tabelle e colonne) tiene solo le righe i cui nomi contengono quello che scrivi, ignorando maiuscole e minuscole, e le righe sopra di esse. Una tabella il cui nome corrisponde mantiene tutte le sue colonne; una tabella tenuta per una colonna corrispondente si apre per mostrarla. Svuota il campo per riavere l'albero completo.
Database
Il database aperto viene per primo, poi ogni database collegato come gruppo a sé, con il numero di tabelle accanto al nome.
- Un database collegato compare anche quando è vuoto. Il database aperto viene omesso finché non ha tabelle, che è come parte una sessione in memoria appena creata.
- Un suggerimento attenuato accanto al nome dice sola lettura, e il tipo di file quando non è DuckDB (sqlite).
- Passa il mouse sul nome per il percorso del file del database.
Fai clic destro su un database per renderlo predefinito o per scollegarlo — vedi Menu contestuale.
Il pulsante di aggiornamento accanto alle schede (Aggiorna schema) ricarica il catalogo e l'elenco dei file registrati.
Generare un SELECT
Tutti i clic qui sotto sostituiscono l'intero buffer della scheda attiva — non inseriscono nella posizione del cursore. Lo stesso vale per il clic su una voce della cronologia. Salva quello a cui tieni prima di fare clic in giro.
Questi riempiono l'editor attivo quando ci fai clic:
| Clic | SQL generato |
|---|---|
| Il pulsante di riproduzione di una tabella | SELECT * FROM db.schema.table LIMIT 100; |
| La casella di una colonna, o il suo nome | SELECT col FROM db.schema.table LIMIT 100; |
| Più colonne della stessa tabella | SELECT a, b FROM db.schema.table LIMIT 100; |
| Un oggetto S3 che è un file di dati | SELECT * FROM 's3://bucket/key' LIMIT 100; |
Ogni colonna, di una tabella, di una vista o di un file locale, ha una casella di controllo. Spuntando colonne, o facendo clic sui loro nomi, che le spunta, si costruisce il SELECT da quelle spuntate, nell'ordine delle colonne della tabella e non nell'ordine in cui le hai spuntate. Togliendo la spunta all'ultima si ottiene SELECT *. Le spunte appartengono a una sola tabella: spuntando una colonna di un'altra tabella si ricomincia da lì.
L'SQL generato occupa tre righe (SELECT …, FROM …, LIMIT 100;). I nomi delle tabelle sono scritti nel modo più breve che il database e lo schema predefiniti correnti consentono: orders per una tabella nello schema predefinito, main.orders per un altro schema dello stesso database, e database.schema.table altrimenti. Dopo Usa come database predefinito su snap, l'anteprima di una delle sue tabelle legge FROM orders. Finché non è stata eseguita la prima query, i nomi sono completamente qualificati.
Un nome viene messo tra virgolette doppie solo quando contiene caratteri diversi da lettere, cifre e underscore.
Menu contestuale
Ogni comando offerto dai pulsanti al passaggio del mouse su una riga è anche nel suo menu contestuale, quindi puoi trovare il comando senza passare il mouse:
| Riga | Menu |
|---|---|
| Tabella o vista | Genera query SELECT, Panoramica delle colonne, Copia nome, Copia info tabella |
| Colonna | Genera query SELECT, Copia nome, Cambia tipo di dato… (solo colonne di tabelle) |
| Database collegato | Usa come database predefinito, Scollega database |
| Elenco dei bucket S3 | Aggiorna bucket |
| Dashboard recente | Rimuovi dall'elenco |
| File locale | Genera query SELECT, Panoramica delle colonne, Copia nome, Copia info tabella, Rimuovi dai file locali |
Copia nome copia il nome nudo — solo il nome della tabella, della colonna o della vista, non qualificato con database e schema, e senza virgolette.
Copia info tabella copia l'intera tabella come Markdown, pronto da incollare in una chat, in una issue o nel prompt di un agente AI — il nome che usa una query, cos'è, la sua dimensione e ogni colonna con il suo tipo:
memory.main.orders (table, ~224 rows, 3 columns)
| column | type |
|---|---|
| date | DATE |
| channel | VARCHAR |
| revenue | DOUBLE |Panoramica delle colonne sostituisce il testo dell'editor attivo con FROM <table>;, lo esegue e apre il pannello dei risultati sulla sua scheda Panoramica, che riassume ogni colonna dell'intera tabella: valori null, valori distinti, intervallo e un piccolo grafico dei suoi valori. Vedi Panoramica delle colonne.
Usa come database predefinito esegue USE su quel database, così i nomi di tabella senza database si risolvono lì, e le query generate diventano più corte (vedi sopra). Non è offerto sul database che è già quello predefinito.
Scollega database scollega un database collegato e lo dimentica, così non viene collegato di nuovo la prossima volta. Se era quello predefinito, la sessione passa prima a un altro database. Il file non viene toccato. Il database aperto non si può scollegare, quindi il suo menu non ha questa voce. Altro in Database collegati.
Cambiare il tipo di una colonna
Una riga di colonna offre un'azione sul tipo (non disponibile sulle colonne delle viste, quindi le colonne di CSV e Parquet collegate non si possono ritipizzare). Apre una finestra di testo libero precompilata con il tipo corrente ed esegue:
ALTER TABLE db.schema.table ALTER COLUMN col SET DATA TYPE <what you typed>Il nome della tabella qui è sempre completamente qualificato, e il nome della colonna viene messo tra virgolette solo quando serve.
Non c'è un selettore né un elenco di validazione — qualsiasi stringa di tipo DuckDB va bene, comprese quelle parametrizzate come DECIMAL(10,2). Un tipo non valido torna come notifica di errore. Il successo ricarica il catalogo.
Rinominare ed eliminare colonne, e modificare i commenti delle colonne, non sono disponibili.
Rimuovere un file registrato
La × su una riga di file chiede conferma, poi elimina la vista e dimentica la registrazione. Il file su disco non viene toccato.
Per rimuovere più registrazioni insieme, seleziona le loro righe sotto File locali:
- ⌘-clic su macOS o Ctrl-clic su Windows/Linux aggiunge o toglie un file dalla selezione.
- Shift-clic seleziona un intervallo consecutivo.
- Fai clic sulla × di un file selezionato, o usa la sua azione di rimozione nel menu contestuale, per confermare la rimozione delle registrazioni selezionate. Il menu mostra quanti file verranno rimossi.
Questo rimuove le viste e le registrazioni, lasciando i file originali su disco. Selezionare i file in questo modo non seleziona tabelle di database né filtri delle dashboard.
Estensioni
La scheda Estensioni elenca ogni estensione DuckDB che il motore conosce: prima quelle caricate, poi quelle installate, poi le altre, ciascun gruppo in ordine alfabetico.
Ogni riga mostra:
- il nome dell'estensione e un tag di stato: Caricata, Installata o Non installata;
- la descrizione di una riga di DuckDB;
- la sua versione e da dove viene: integrata, oppure il repository da cui è stata installata (
core,communityo un URL).
Cosa significano gli stati:
| Stato | Significato |
|---|---|
| Caricata | Attiva nella connessione corrente: le sue funzioni, i suoi reader e i suoi tipi funzionano nelle query adesso |
| Installata | Scaricata su questa macchina, ma non caricata in questa connessione |
| Non installata | Conosciuta da DuckDB, ma non ancora su questa macchina |
Le estensioni integrate sono compilate in DuckLocal — tra queste parquet e json, entrambe caricate dall'inizio. Non vengono mai installate né aggiornate.
Le estensioni della comunità si installano allo stesso modo. Dalla 0.4.1 la scheda raggiunge sia il repository della comunità di DuckDB sia quello core, quindi un'estensione come mssql (SQL Server) può essere installata e caricata senza uscire dall'app; il tag del repository della riga dice community.
Una riga offre le azioni che le si applicano:
| Pulsante | Compare quando | Esegue |
|---|---|---|
| Installa | Non installata | INSTALL name |
| Carica | Installata, non caricata | LOAD name |
| Aggiorna | Installata da un repository | UPDATE EXTENSIONS (name) |
- Installa e Aggiorna scaricano dal repository delle estensioni di DuckDB, quindi hanno bisogno della rete. Carica legge il file installato e non ne ha bisogno.
- Installare non carica. Fai clic su Carica dopo, oppure esegui
LOAD name. - Un'estensione installata resta installata: è un file su disco, nella cartella delle estensioni di DuckDB. Il caricamento dura solo per la connessione corrente.
- Quella cartella è per release di DuckDB (
~/.duckdb/extensions/v2.0.0/…). Quando un aggiornamento porta DuckLocal a una nuova release di DuckDB, come ha fatto la 0.3.0 con DuckDB 2.0, le estensioni che avevi compaiono come Non installata finché non le installi di nuovo. - Un'azione alla volta; nel frattempo gli altri pulsanti sono disabilitati. Una notifica dice Installata …, Caricata … o Aggiornata …, oppure perché è fallito.
- Dopo un caricamento o un aggiornamento, l'albero dello schema viene ricaricato, dato che un'estensione può portare con sé tabelle e funzioni.
L'elenco viene letto da duckdb_extensions() ogni volta che la scheda si apre, dopo ogni azione, quando la connessione cambia mentre la scheda è aperta, e quando fai clic sul pulsante di aggiornamento accanto alle schede (Aggiorna estensioni). Così mostra anche un'estensione caricata in un altro modo — da un LOAD scritto in una scheda query, o da DuckDB per conto suo.
Dalla v0.2.1, né la finestra né la CLI scaricano automaticamente un'estensione mancante quando una query la richiede. Installala esplicitamente in Estensioni o con INSTALL name. Le estensioni già installate su questa macchina possono comunque caricarsi automaticamente.
Aprire la UI di DuckDB
La DuckDB UI — il notebook nel browser di DuckDB, creato da MotherDuck — è un'estensione come le altre, quindi funziona anche dentro DuckLocal:
Nella scheda Estensioni, fai clic su Installa sulla riga
ui, poi su Carica.In una scheda query, esegui:
sqlCALL start_ui();Il tuo browser apre la UI su
http://localhost:4213. Per avviare il server senza aprire un browser, esegui inveceCALL start_ui_server();.

La UI gira sull'istanza DuckDB da cui è stata avviata, che qui è quella di DuckLocal. Qualche cosa da sapere:
- Ha bisogno della rete. Installare
uila scarica, come qualsiasi estensione. E ogni volta che si avvia, il server locale dell'estensione scarica i file propri della UI dahttps://ui.duckdb.org. Le tue query e i tuoi dati restano comunque in locale. - Vive quanto DuckLocal. Uscire da DuckLocal chiude la sua istanza DuckDB, e con essa il server.
CALL stop_ui_server();lo ferma prima. - I notebook sono salvati dall'estensione, non da DuckLocal, in
~/.duckdb/extension_data/ui/. La cronologia delle query di DuckLocal non include quello che esegui nella UI. - Non può funzionare direttamente su un database in sola lettura. Collega quel database da un notebook con
ATTACH '…' (READ_ONLY).
DuckDB UI vs DuckLocal confronta i due e spiega quando usare l'uno o l'altro.
Cronologia delle query
Ogni esecuzione viene registrata — successi e fallimenti — con un timestamp dell'ora locale, la durata in millisecondi, il numero di righe (o il numero di righe modificate per il DML) e il testo dell'errore se è fallita. Le voci fallite sono mostrate in rosso con un tag Fallita.
L'elenco mostra le 200 voci più recenti. Facendo clic su una riga l'editor attivo viene riempito con quell'SQL e riceve il fuoco, sostituendo quello che c'era.
Non c'è una politica di conservazione né una pulizia: la tabella della cronologia cresce senza limiti, e l'interfaccia mostra semplicemente le 200 più recenti. Non c'è nemmeno ricerca, filtro, esportazione, né un modo per eliminare una voce dall'interfaccia.
La cronologia è memorizzata nel file di database proprio di DuckLocal, non nel database che hai aperto, quindi sopravvive al cambio di database e alla perdita dello spazio di lavoro. Vedi Impostazioni e dati dell'app per dove si trova.
