Editor SQL
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 |
| Interrompi | Compare quando un'esecuzione è in corso da un momento; la interrompe |
| Formatta | Riformatta l'SQL — vedi Formattazione |
| 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.
Esecuzione dell'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 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 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
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
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. 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.
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,EXPLAINstesso, una scrittura nascosta dietro unWITH(WITH s AS (…) INSERT …) e unPIVOTsenza un elenco esplicitoIN (…).
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:
- Tabelle e colonne dello schema (fino a 35 voci)
- Nomi di funzioni DuckDB
- 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 |
| ⌘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. Anche le righe della barra laterale dello schema hanno un menu contestuale; vedi Schema e cronologia. Non c'è una palette dei comandi.
