# Editor SQL

> L'editor SQL DuckDB di DuckLocal: schede delle query, formattazione, errori inline, completamento automatico basato sullo schema, piani Explain, profilazione per operatore e scorciatoie.

Source: https://ducklocal.app/docs/it/sql-editor

Ogni scheda delle query ha il proprio buffer dell'editor. L'editor evidenzia
l'SQL reale tramite tree-sitter, indenta con 2 spazi e mostra i numeri di riga.

## Schede

| Controllo | Cosa fa |
| --- | --- |
| `+` o **⌘T** | Aggiunge una nuova scheda query e le dà il fuoco |
| Fai clic su una scheda | Passa a quella scheda |
| **Ctrl+Tab** / **Ctrl+Shift+Tab** | La scheda successiva / precedente |
| **⌘1** … **⌘8**, **⌘9** | Dalla prima all'ottava scheda; ⌘9 è l'ultima scheda |
| Trascina una scheda | La sposta lungo la barra |
| `×`, **⌘W** o un clic con il tasto centrale | Chiude una scheda. L'ultima scheda non si può chiudere: la sua `×` è nascosta e ⌘W non fa nulla. Una dashboard con modifiche non salvate chiede prima |
| Fai clic destro su una scheda | **Chiudi scheda**, **Chiudi le altre schede**, **Chiudi le schede a destra**. Le dashboard con modifiche non salvate restano aperte, e un avviso dice quante |
| Fai doppio clic su una scheda | Modifica il suo titolo sul posto. Invio o un clic altrove mantiene il nuovo titolo, Esc mantiene quello vecchio; un titolo vuoto torna a `Query N` |

Le schede aperte tornano al prossimo avvio, nel loro ordine: le schede delle
query con i loro titoli e l'SQL nei loro editor, che sia stato eseguito o no, e
le schede delle dashboard. I risultati no: riesegui la query. Una scheda query
aperta da zero parte con `SELECT 'Hello, DuckLocal' AS greeting;`.

## La barra degli strumenti

Sopra l'editor, da sinistra:

| Pulsante | Cosa fa |
| --- | --- |
| **Esegui** | Esegue l'SQL dell'editor — vedi [Esecuzione dell'SQL](#running-sql) |
| **Interrompi** | Compare quando un'esecuzione è in corso da un momento; la interrompe |
| **Formatta** | Riformatta l'SQL — vedi [Formattazione](#format) |
| **Explain** | Mostra il piano che DuckDB userebbe, senza eseguire l'istruzione |
| **Profile** | Esegue la query e mostra quanto è costato ogni operatore |

**Explain** e **Profile** sono descritti in
[Explain e Profile](#explain-and-profile).

## Esecuzione dell'SQL {#running-sql}

Premi **⌘↵** (Cmd+Invio) con l'editor attivo, oppure usa il pulsante **Esegui**.

Mentre una query è in esecuzione, premere di nuovo **Esegui** non fa nulla (e
neanche Explain e Profile), e accanto a Esegui compare un pulsante **Interrompi**
quando la query va avanti da un momento. Interrompi, o **⌘.**, interrompe la
query; termina con l'errore `Interrupted` di DuckDB, registrato nella cronologia
come qualsiasi fallimento. Non c'è nessun timeout: senza Interrompi, una query va
avanti quanto serve a DuckDB, e il resto del lavoro sul database si accoda dietro.

I risultati arrivano in streaming da DuckDB, quindi una scansione si ferma quando
viene raggiunto il [limite di righe](results-and-charts.md#row-limits) della
griglia invece di leggere il resto del file. Una query che deve vedere ogni riga
prima della prima — `ORDER BY`, `GROUP BY`, un'aggregazione, una funzione window
— viene comunque calcolata per intero.

Ogni scheda ha i propri risultati. Un risultato che arriva dopo che hai cambiato
scheda finisce nella scheda che l'ha eseguito.

Come viene trattata un'istruzione dipende dalla sua parola chiave iniziale.
`SELECT`, `WITH`, `SHOW`, `DESCRIBE`, `EXPLAIN`, `PRAGMA`, `SUMMARIZE`, `VALUES`,
`FROM`, `TABLE`, `PIVOT` e `CALL` producono un set di risultati. Tutto il resto —
istruzioni DDL (definizione dei dati) e DML (modifica dei dati) — riporta
`Done: N rows affected, took …` invece di una griglia. I commenti `--` iniziali
vengono saltati quando si decide; i commenti a blocco no.

### Script

L'editor può contenere più istruzioni. **Esegui** le esegue tutte, in ordine, come
la shell di DuckDB legge un file, e **si ferma al primo errore** — eseguire un
`SELECT` dopo un `ATTACH` fallito aggiungerebbe solo un secondo errore
fuorviante. Una striscia sopra i risultati elenca le istruzioni, ciascuna
contrassegnata con il suo numero di righe, *eseguita*, *fallita* o *non eseguita*;
fai clic su una per vederne il risultato. Un errore sottolinea l'istruzione
fallita, non l'intero script.

Alcuni comandi con il punto della shell funzionano anch'essi, ciascuno su una
riga propria:

| Comando | Mostra |
| --- | --- |
| `.tables ?PATTERN?` | Tabelle e viste, facoltativamente filtrate con un pattern `ILIKE` come `stat%` |
| `.schema ?PATTERN?` | Le istruzioni `CREATE` di tabelle e viste, facoltativamente filtrate |
| `.databases` | I database collegati |
| `.help` | Questo elenco |

Qualsiasi altro comando con il punto (`.mode`, `.read`, …) è un errore che nomina
quelli che funzionano.

## Errori

Un'istruzione fallita mostra un avviso intitolato *Query non riuscita* con il
messaggio di DuckDB alla lettera. Il messaggio viene dal motore ed è sempre in
inglese, qualunque sia la lingua dell'interfaccia. Nulla viene scritto nella
griglia, e il tentativo viene comunque registrato nella
[cronologia](schema-and-history.md) con un indicatore di errore.

Quando il messaggio punta a una posizione — gli errori di parser e binder lo
fanno, con una riga `LINE n:` e un apice — l'editor sottolinea quel punto con una
linea ondulata rossa: il token che l'apice indica, o l'intervallo coperto da una
serie di apici. Il segno segue le tue modifiche e si cancella all'esecuzione
successiva. Gli errori di runtime non hanno posizione e non ricevono alcun segno.

## Formattazione {#format}

**Formatta** passa il buffer in `sqlformat` con un'indentazione di 2 spazi e le
parole chiave in maiuscolo, poi sostituisce l'intero buffer. Su un buffer vuoto
non fa nulla.

## Explain e Profile {#explain-and-profile}

Entrambi i pulsanti lavorano su tutto il testo dell'editor, ed entrambi
richiedono **esattamente un'istruzione**. Con due o più — o con un comando con il
punto — rifiutano con *Explain e Profile accettano una sola istruzione: metti
quella da esaminare in una scheda a parte.* Un `;` finale e i commenti finali
vanno bene.

Mentre uno tra Esegui, Explain o Profile è occupato, gli altri due non fanno
nulla. Né Explain né Profile vengono registrati nella
[cronologia](schema-and-history.md#query-history). Il loro output sostituisce la
griglia nella scheda **Risultati**, passando a essa se era aperta un'altra scheda;
un fallimento mostra l'avviso *Query non riuscita*, come un'esecuzione fallita.

### Explain

**Explain** esegue `EXPLAIN <la tua istruzione>` e mostra il piano di DuckDB come
testo monospaziato, con il tempo impiegato. Pianifica soltanto: l'istruzione non
viene eseguita, quindi spiegare un `INSERT`, `UPDATE` o `DELETE` è sicuro.

### Profile

**Profile** esegue l'istruzione con `EXPLAIN (ANALYZE, FORMAT JSON)` e mostra il
piano eseguito come albero: il tempo di ogni operatore e la sua quota del totale,
le righe prodotte rispetto alla stima dell'ottimizzatore (segnalate quando
sbagliano di più di 10×), e cosa ha filtrato, su cosa ha fatto join o cosa ha
proiettato. L'operatore più costoso è indicato in cima e disegnato in rosso. Come
leggerlo: [Output di Explain e Profile](results-and-charts.md#explain-and-profile).

**La profilazione esegue davvero l'istruzione** — è così che i suoi operatori
vengono cronometrati. Quindi accetta solo una singola query in sola lettura:

- **Accettate:** `SELECT`, `WITH … SELECT`, `FROM …`, `VALUES`, `TABLE`, `SHOW`,
  `DESCRIBE`, `SUMMARIZE`.
- **Rifiutate:** tutto ciò che scrive (`INSERT`, `UPDATE`, `DELETE`,
  `CREATE`, …), `CALL`, `PRAGMA`, `COPY`, `EXPLAIN` stesso, una scrittura nascosta
  dietro un `WITH` (`WITH s AS (…) INSERT …`) e un `PIVOT` senza un elenco
  esplicito `IN (…)`.

Un'istruzione rifiutata riceve *Si possono profilare solo le istruzioni che
leggono (SELECT, WITH, FROM…): la profilazione esegue l'istruzione.* È il parser
di DuckDB a deciderlo prima che qualcosa venga eseguito, non la prima parola
chiave.

Una profilazione dura quanto la query, più il costo di misurarla. **Interrompi**
(o **⌘.**) la interrompe come un'esecuzione.

## Completamento automatico

Il menu di completamento è consapevole del catalogo. I candidati sono ordinati:

1. Tabelle e colonne dello schema (fino a 35 voci)
2. Nomi di funzioni DuckDB
3. Parole chiave SQL

Vengono offerti al massimo 50 elementi. La corrispondenza è sul **prefisso**,
senza distinzione tra maiuscole e minuscole, dell'identificatore immediatamente a
sinistra del cursore, quindi `sel` completa in `SELECT` ma `elect` non completa
nulla. Una funzione inserisce il suo nome e una parentesi aperta; gli
identificatori che contengono spazi o caratteri speciali vengono inseriti tra
virgolette doppie.

Gli elenchi di parole chiave e funzioni sono un sottoinsieme curato — non tutte
le funzioni DuckDB compariranno.

## Scorciatoie da tastiera

Su Windows e Linux, leggi **Ctrl** al posto di **⌘** ovunque.

Le scorciatoie di DuckLocal, tutte elencate nella barra dei menu:

| Scorciatoia | Azione |
| --- | --- |
| ⌘↵ | Esegue la query |
| ⌘. | Interrompe la query in esecuzione |
| ⌘T | Nuova scheda query |
| ⌘W | Chiude la scheda |
| Ctrl+Tab / Ctrl+Shift+Tab | Scheda successiva / precedente (Ctrl anche su Mac) |
| ⌘1 … ⌘9 | Vai alla scheda in quella posizione; ⌘9 è l'ultima |
| ⌘O | Apre dati |
| ⌘S | Salva il sorgente di una dashboard, nella sua vista sorgente |
| ⌘B | Nasconde o mostra la barra laterale |
| ⌘+ / ⌘− / ⌘0 | Ingrandisce / riduce / riporta alla dimensione predefinita l'interfaccia — vedi [Dimensione dell'interfaccia](settings-and-data.md#interface-size) |
| ⌘Q | Esce |

Quelle dell'editor, che si comportano come in qualsiasi campo di testo:

| Scorciatoia | Azione |
| --- | --- |
| ⌘F / ⇧⌘F | Trova / sostituisci nell'editor |
| ⌘Z / ⇧⌘Z | Annulla / ripristina |
| ⌘A | Seleziona tutto |
| ⌘C / ⌘X / ⌘V | Copia / taglia / incolla |
| ⌥⌘↑ / ⌥⌘↓ | Aggiunge un cursore sopra / sotto |
| ⌘← / ⌘→ / ⌥← / ⌥→ | Sposta per riga / per parola |
| ⌘↑ / ⌘↓ | Va all'inizio / alla fine del documento |
| ⌘⌫ / ⌥⌫ | Cancella fino all'inizio della riga / la parola precedente |

## Menu

La barra dei menu contiene ogni comando della finestra con la sua scorciatoia:

| Menu | Comandi |
| --- | --- |
| DuckLocal | Riga di comando e AI, Verifica aggiornamenti…, Verifica aggiornamenti all'avvio, Mostra la guida, Apri la cartella dei log, Esci da DuckLocal |
| File | Nuova query, Apri dati, Salva, Chiudi scheda, Scheda successiva, Scheda precedente |
| Modifica | Annulla, Ripristina, Taglia, Copia, Incolla, Seleziona tutto |
| Query | Esegui, Interrompi |
| Visualizza | Mostra o nascondi la barra laterale, Interfaccia più grande, Interfaccia più piccola, Dimensione predefinita, Mappa di base online (OpenStreetMap) |

Su Windows e Linux non c'è la barra dei menu; lì **Mostra la guida** e **Apri la
cartella dei log** sono nel menu contestuale della versione all'estremità destra
della barra di stato.

**Mappa di base online (OpenStreetMap)** è una voce di spunta; vedi
[Grafici](results-and-charts.md#charts). Anche le righe della barra laterale
dello schema hanno un menu contestuale; vedi [Schema e
cronologia](schema-and-history.md#right-click-menu). Non c'è una palette dei
comandi.
