# Browser dello schema e cronologia

> Esplora database, tabelle e colonne nella barra laterale dello schema di DuckLocal, genera query SELECT, gestisci le estensioni DuckDB e riusa le query passate.

Source: https://ducklocal.app/docs/it/schema-and-history

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_2` da `sales.csv`).
  - La cartella compare quando due file condividono il nome di una vista.
  - Passa il mouse su una riga per il percorso completo.
- **Dashboard** — le dashboard `.dash` che 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:\Proj` e `E:\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](metrics.md#sidebar). Successivo
  alla 0.4.1.
- **S3** — presente una volta che [S3 è configurato](s3.md). 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](data-sources.md#attached-databases) vengono dopo,
  contrassegnati `read-only` quando 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 {#databases}

Il database aperto viene per primo, poi ogni
[database collegato](data-sources.md#attached-databases) 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](#right-click-menu).

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 {#right-click-menu}

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:

```md
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](results-and-charts.md#overview).

**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](data-sources.md#attached-databases).

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

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

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`, `community` o 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 {#duckdb-ui}

La [DuckDB UI](https://duckdb.org/2025/03/12/duckdb-ui) — il notebook nel browser
di DuckDB, creato da MotherDuck — è un'estensione come le altre, quindi funziona
anche dentro DuckLocal:

1. Nella scheda **Estensioni**, fai clic su **Installa** sulla riga `ui`, poi su
   **Carica**.
2. In una scheda query, esegui:

   ```sql
   CALL start_ui();
   ```

   Il tuo browser apre la UI su `http://localhost:4213`. Per avviare il server
   senza aprire un browser, esegui invece `CALL start_ui_server();`.

![La scheda Estensioni con l'estensione ui caricata](../assets/duckdb-ui.png)

La UI gira sull'istanza DuckDB da cui è stata avviata, che qui è quella di
DuckLocal. Qualche cosa da sapere:

- **Ha bisogno della rete.** Installare `ui` la scarica, come qualsiasi
  estensione. E ogni volta che si avvia, il server locale dell'estensione scarica
  i file propri della UI da `https://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](https://ducklocal.app/it/blog/duckdb-ui-vs-ducklocal/)
confronta i due e spiega quando usare l'uno o l'altro.

## Cronologia delle query {#query-history}

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](settings-and-data.md)
per dove si trova.
