Questa pagina descrive Calíope 1.8, la versione che sto costruendo adesso. La 1.7 è sull'App Store per Mac, iPad, iPhone, Apple Watch, Apple TV e Apple Vision Pro. Il changelog dice in quale versione è arrivata ogni funzione.
Aggiunge a ogni argomento un pulsante «Apri in Calíope». Funziona solo con l'app installata.
Apri e interroga database DuckDB locali su file, senza server.
Dove si trova: Workspace › Strumenti › Editor DuckDB
L'Editor DuckDB è uno strumento autonomo per i file .duckdb locali, con lo stesso impianto dell'Editor SQLite: Struttura, Dati, Esegui SQL, Diagramma ER — solo con un file aperto —, Query Builder e Impostazioni, e funziona senza connessione ad alcun server.
Può anche aprire un database in memoria — senza file — da Interroga file di dati…, per lavorare su un CSV, JSON o Parquet senza creare nulla su disco.
Quello che Calíope non fa con DuckDB. Non scarica estensioni — INSTALL, LOAD, UPDATE EXTENSIONS e i repository di estensioni (CREATE e DROP EXTENSION REPOSITORY) vengono rifiutati prima di toccare il motore —: ci sono solo le quattro incluse nell'app. Per lo stesso motivo, non esistono secret di accesso remoto (CREATE SECRET) e non si può fare ATTACH di un file SQLite o Postgres, che richiedono un'estensione non collegata. La configurazione del motore resta chiusa all'apertura: un SET di un'impostazione del motore viene rifiutato —anche threads e memory_limit, che si cambiano solo dalle Impostazioni; SET VARIABLE no, perché una variabile non è configurazione— e, come ogni errore in esecuzione, annulla le modifiche non salvate. I due SET che propongono i messaggi di DuckDB 2.0 fanno eccezione: Calíope li ferma prima e non annullano nulla. Quello che invece funziona è spostare l'intero database: Database intero e Salva con nome… vengono eseguiti fuori dalla transazione in sospeso.
Parole chiave: duckdb, file, locale, database, analitica
Apri un file .duckdb esistente o creane uno nuovo.
Dove si trova: Workspace › Strumenti › Editor DuckDB
Usa Apri… per scegliere un file .duckdb esistente, o Nuovo database… per crearne uno vuoto. I file recenti compaiono nella schermata iniziale. Un'insegna Sola lettura compare quando un file non può essere modificato.
Se il file è fuori dalla cartella propria di Calíope, la prima volta viene chiesto l'accesso alla sua cartella: DuckDB deve scrivere un file .wal accanto al .duckdb, e il sandbox dell'app lo consente solo dentro una cartella scelta dall'utente. Viene ricordato per la prossima apertura di un file della stessa cartella. Nessun file DuckDB a portata di mano? Nello stato vuoto, Scarica il database di esempio apre la pagina del sito dove si trova l'esempio pubblico — un piccolo negozio con 50.000 ordini, creato con Calíope. L'app non scarica nulla: apre la pagina e decidi tu.
Puoi aprirlo anche dall'esterno di Calíope. Sul Mac, dal Finder con Apri con › Calíope, oppure con un doppio clic se Calíope è l'app predefinita per quel tipo di file. Su iPad e iPhone, condividendolo dall'app File e scegliendo Calíope. Un file Parquet aperto così arriva anche qui, in un database in memoria (vedi Interroga file di dati…). Se la sessione che hai davanti non offre questo strumento, il file si apre in Apri senza connessione.
Il formato del file. Un nuovo database — quello di Nuovo database… e quello che lascia Salva con nome… da un database in memoria — viene creato nel formato di DuckDB 2.0. Questo formato lo aprono DuckDB 2.0 e le versioni successive; non lo aprono Calíope 1.7 né gli strumenti con DuckDB 1.5 o precedente. Un file che esisteva già conserva il suo formato: Calíope lo apre e lo modifica senza convertirlo, quindi lo strumento che lo ha creato continua ad aprirlo. Il formato non si sceglie alla creazione e un file esistente non viene convertito. Per sapere in quale formato è il file aperto, vai in Struttura: sotto la barra, Formato del file indica DuckDB 2.0 o successivo per un nuovo database e, per esempio, DuckDB 1.0 o successivo per uno creato con DuckDB 1.5.
Parole chiave: aprire, creare, nuovo, recenti, file, cartella, wal, formato, versione
La sezione Struttura mostra l'albero dello schema con le colonne e il DDL di ogni oggetto. DuckDB non ha trigger, quindi l'albero mostra tabelle, viste, indici, sequenze, tipi, macro e macro di tabella. Sequenze, tipi e macro si creano da Esegui SQL —CREATE SEQUENCE, CREATE TYPE, CREATE MACRO, CREATE MACRO … AS TABLE—; qui si vedono e si eliminano. Se il file ha più di uno schema, ogni gruppo porta davanti il nome del suo, e il commento di un oggetto (COMMENT ON) appare al passaggio del mouse. Usa Nuovo per creare tabelle, indici o viste, Aggiungi colonna o Rinomina tabella sulla tabella selezionata, e Elimina per rimuovere un oggetto. Sotto la barra, Formato del file indica quali versioni di DuckDB aprono il file: un nuovo database richiede DuckDB 2.0 o successivo, e uno che esisteva già conserva il suo formato.
Le viste create da Interroga file di dati… hanno un'icona diversa — una graffetta — e il loro tooltip mostra il percorso del file di origine.
Allega database… apre un altro database DuckDB accanto a quello aperto; il suo contenuto compare nell'albero preceduto dal nome del database e si interroga come database.schema.tabella. È sempre in sola lettura —scriverci richiederebbe creare il suo file .wal accanto, cosa che la sandbox non permette— e Stacca lo rimuove. Un file SQLite non si può allegare qui: sono due motori diversi, ed è a questo che serve l'Editor SQLite.
iPad e Apple Vision Pro: anche il pannello di dettaglio mostra il file di origine.
Parole chiave: struttura, tabella, indice, vista, creare, ddl, schema
La sezione Dati mostra le righe di una tabella per pagine, con il conteggio e le frecce a destra della barra. Quante righe entrano in una pagina si sceglie in Impostazioni › Editor di testo › Risultati › Righe per pagina — Impostazioni, su iPad. Ordina toccando l'intestazione di una colonna, restringi colonna per colonna con Filtri, oppure scrivi nel campo di ricerca per cercare in tutte insieme.
Modificare una cella
macOS: doppio clic su di essa. iPad: un solo tocco. Invio conferma; Esc annulla.
Aggiungere ed eliminare righe
Aggiungi riga apre un modulo con una riga per colonna. A differenza di SQLite, DuckDB non assegna da sé l'intera chiave primaria: ogni colonna obbligatoria ha bisogno del proprio valore, chiave compresa. Per eliminare, seleziona la riga dal suo numero e usa Elimina riga.
Niente di tutto questo tocca il file finché non premi Salva modifiche: ciò che modifichi resta in una transazione in sospeso che Annulla modifiche disfa per intero.
Parole chiave: dati, righe, modificare, filtrare, ordinare, cercare, cella, inserire, nuova riga, eliminare
Evidenziazione della sintassi e completamento, con limite di righe e pulsante Interrompi.
La sezione Esegui SQL usa lo stesso campo di testo e la stessa griglia di risultati dell'Editor SQL da server, sul file aperto e senza alcuna connessione.
Il testo è evidenziato. Premi Esegui, o ⌘↩, per eseguire l'intero script; viene disegnato il risultato dell'ultima istruzione che ha restituito righe. Un SELECT grande non viene portato per intero: viene tagliato in Impostazioni › Editor di testo › Risultati › Limite di righe — lo stesso limite dell'Editor SQL —, e la griglia dice quante righe su quante ha portato.
Mentre una query è in corso, un pulsante Interrompi la interrompe per davvero: il motore la taglia a metà strada, senza aspettare che finisca.
Se un'istruzione fallisce, lo script si ferma lì e l'errore appare dove andrebbero i risultati. Un errore di sintassi o un nome che non esiste lascia com'era ciò che è in sospeso; uno che avviene in esecuzione annulla le modifiche non salvate, e Calíope lo dice (argomento Salvare e ripristinare le modifiche). Quando un argomento spiega l'errore — l'SQL che DuckDB 2.0 non accetta più è in Cosa cambia con DuckDB 2.0 —, Vedi soluzione lo apre dall'errore stesso.
INSTALL e LOAD vengono rifiutati: Calíope non scarica estensioni DuckDB, quindi una query che ne avesse bisogno non viene eseguita, con il motivo spiegato nel messaggio.
Ciò che scrivi nel file resta in sospeso, come una modifica in Dati: non tocca il file prima di Salva modifiche.
Visual EXPLAIN
Il pulsante Visual EXPLAIN, accanto a Esegui, disegna il piano che seguirebbe DuckDB — EXPLAIN (FORMAT JSON) — senza eseguire nulla, nella stessa scheda dell’Editor SQL, con le righe che stima. Analizza la selezione e, senza selezione, l’ultima istruzione del testo. Una tabella può risultare letta per intero anche con un indice: DuckDB conserva minimi e massimi per blocco e spesso preferisce leggere tutto scartando blocchi.
Schede delle funzioni
Passando il puntatore su una funzione su macOS, o mettendoci il cursore di testo su iPad, appare la sua scheda, quella di DuckDB: sintassi, ritorno, parametri e un esempio. Lo spiega l'argomento Aiuto contestuale delle funzioni SQL.
Apple Vision Pro: come sull'iPad, e la scheda della funzione pende sopra l'intestazione, sotto la finestra.
L'SQL di DuckDB 1.5 che la 2.0 rifiuta o a cui risponde in modo diverso, con la sua forma nuova.
DuckDB 2.0 risponde in modo diverso a un po' di SQL che con DuckDB 1.5 funzionava, e Calíope porta DuckDB 2.0 dalla versione 1.8. Uno script di prima può ora dare un errore o, in un caso, un altro risultato senza avvisare. Quando una query fallisce per uno di questi cambiamenti, Vedi soluzione, accanto all'errore, apre questo argomento.
La soluzione è sempre riscrivere la query. I messaggi del motore propongono un SET per tornare al comportamento di prima; in Calíope non serve: la configurazione di DuckDB è bloccata mentre un file è aperto (argomento Impostazioni e manutenzione). Calíope ferma quel SET prima che arrivi al motore e lo dice: non viene eseguito, e le modifiche non salvate restano dove sono.
Lambda: lambda x: invece di x ->
Una funzione lambda scritta con la freccia non è più accettata.
Prima:
SELECT list_transform([1, 2, 3], x -> x + 1);
Ora:
SELECT list_transform([1, 2, 3], lambda x: x + 1);
Con la forma di prima, il motore risponde:
Binder Error: Deprecated lambda arrow (->) detected. Please transition to the new lambda syntax, i.e.., lambda x, i: x + i, before DuckDB's next release.
// e % per zero danno errore
La divisione intera //, il resto % e le funzioni divide e mod restituivano NULL quando il divisore era zero. Ora la query fallisce e, poiché è un errore in esecuzione, annulla le modifiche non salvate. / non cambia: dà ancora inf.
Prima (restituiva NULL):
SELECT 7 // 0;
Ora, per continuare a ricevere NULL:
SELECT TRY(7 // 0);
SELECT 7 // NULLIF(0, 0);
Il motore risponde:
Invalid Input Error: Division by zero in expression (7 // 0). Use TRY(...) to return NULL for this expression, or SET error_on_division_by_zero=false to return NULL for all divisions by zero.
~ corrisponde a una parte del testo, non al testo intero
Questo cambiamento non dà errore: dà un altro risultato. testo ~ modello era vero solo se l'espressione regolare corrispondeva al testo intero; ora basta che corrisponda a una parte, come in PostgreSQL. !~ cambia allo stesso modo.
In CREATE TABLE … AS, una colonna che nasce da un semplice NULL riceveva il tipo INTEGER. Ora riceve il tipo "NULL" e non accetta nessun altro valore. Le tabelle già create conservano il loro tipo.
Prima:
CREATE TABLE notas AS SELECT 1 AS id, NULL AS nota;
INSERT INTO notas VALUES (2, 5);
Ora, con il tipo scritto:
CREATE TABLE notas AS SELECT 1 AS id, NULL::INTEGER AS nota;
INSERT INTO notas VALUES (2, 5);
Con la forma di prima, l'INSERT fallisce:
Conversion Error: Unimplemented type for cast (INTEGER -> "NULL")
Una tabella rimasta così si sistema cambiando il tipo della colonna:
ALTER TABLE notas ALTER COLUMN nota TYPE INTEGER;
Quali errori annullano le modifiche non salvate
Da solo, DuckDB 2.0 annulla la transazione aperta a ogni errore, anche di sintassi, e l'istruzione successiva risponde:
TransactionContext Error: Current transaction is aborted (please ROLLBACK)
Calíope non usa quel valore predefinito: apre ogni file con la regola di DuckDB 1.5. Un errore di sintassi, o il nome di una tabella, di una colonna o di una funzione che non esiste, non tocca le tue modifiche non salvate. Gli errori che avvengono in esecuzione le annullano, come prima — un vincolo non rispettato, un valore che non si può convertire —, e ora anche la divisione per zero, che prima non era un errore. Calíope lo dice accanto all'errore e fa il ROLLBACK per te. Lo spiega l'argomento Salvare e ripristinare le modifiche.
Cambia anche
EXPLAIN in testo si disegna in un altro modo: riquadri con gli angoli arrotondati e gli operatori con il nome per esteso. Visual EXPLAIN non cambia.
ALTER TABLE … ADD COLUMN ora accetta vincoli, come NOT NULL con un DEFAULT; DuckDB 1.5 li rifiutava.
Un file nuovo viene creato nel formato di DuckDB 2.0, che le versioni precedenti non aprono. Lo spiega l'argomento Aprire o creare un database.
Parole chiave: duckdb 2.0, cambiamenti, lambda, freccia, divisione per zero, resto, modulo, null, tipo, espressione regolare, tilde, transazione, aggiornamento
Le tabelle del file e le loro chiavi esterne, disegnate senza server.
La sezione Diagramma ER disegna le tabelle del file aperto con le loro colonne e le chiavi esterne che dichiarano, senza connessione a nessun server. Compare solo con un file aperto: un database in memoria non la offre, perché non c’è un file dove salvare la disposizione.
Il selettore in alto elenca il database del file — che si chiama come il file — e quelli che hai collegato; se un database ha tabelle in più di uno schema, ogni schema è una voce (tienda.main, tienda.ventas). + DB ne aggiunge un secondo accanto.
Funziona come il Diagramma ER di una connessione: zoom, Disposizione automatica, esportazione in PNG o PDF, stampa sul Mac e il CREATE TABLE di una tabella dal suo menu. Dopo una modifica della struttura, un ATTACH o un DETACH, il diagramma rilegge da solo.
Legge soltanto. Non offre Nuova relazione FK… né il trascinamento con ⌃: DuckDB non aggiunge una chiave esterna a una tabella che esiste già (rifiuta ALTER TABLE … ADD CONSTRAINT … FOREIGN KEY). Per relazionare due tabelle, la chiave esterna si dichiara quando si crea la tabella (REFERENCES in Esegui SQL).
Salva layout salva dove hai lasciato ogni tabella per file e solo su questo dispositivo: non passa da iCloud e non entra nel backup delle impostazioni, perché il percorso del file è diverso su ogni dispositivo. Si conservano le disposizioni dei file usati più di recente, e le più vecchie si cancellano da sole. Se il sistema cambia il percorso del file, la sua disposizione si perde, come la sua voce nei file recenti.
Se il file non si può leggere, un avviso sopra il diagramma dice perché, con il testo del motore.
Su Apple Vision Pro, Apri nello spazio dispone nella stanza il diagramma del file, anch’esso in sola lettura; si chiude quando chiudi il file.
Parole chiave: diagramma, er, relazioni, chiavi esterne, duckdb, file, disposizione, attach
Componi un SELECT con le tabelle del database e portalo in Esegui SQL.
La sezione Query Builder è il Query Builder di una connessione, sul database aperto e senza server; funziona anche con un database in memoria. L’elenco a sinistra ha le tabelle del database, con un filtro per nome; premi una tabella, il suo +, o trascinala sul canvas. Il JOIN viene dalle chiavi esterne che il database dichiara, e dove non ce ne sono indichi in Relazioni quali colonne si relazionano. Le condizioni, il tipo di JOIN, gli alias, Svuota canvas e la copia dell’SQL funzionano come con una connessione.
Con database collegati, il menu in alto sceglie quale; quello del file si chiama come il file. Appena c’è più di un database o di uno schema, ogni tabella si scrive con il suo nome completo ("tienda"."main"."clientes"), perché due possono chiamarsi allo stesso modo. Se un DETACH si porta via il database scelto, il canvas passa a quello principale.
Inserisci nell'editor aggiunge la query alla fine di quello che hai scritto in Esegui SQL, dopo una riga vuota, e passa a quella sezione. Non sostituisce mai quello che c’era.
Il canvas resta lì quando cambi sezione o scheda, e viene scartato quando chiudi il database. Sull’iPhone, e sull’iPad con lo schermo diviso, l’elenco occupa lo schermo e aggiungere una tabella ti porta al canvas.
Le modifiche restano in sospeso finché non le salvi.
Le modifiche vengono raggruppate in una transazione in sospeso, come nell'Editor SQLite. Un punto ambra indica modifiche non salvate. Usa Salva modifiche per confermarle o Ripristina modifiche per scartarle. Chiudere il file, o aprirne o crearne un altro, con modifiche in sospeso chiede prima se salvarle o scartarle.
Se un'istruzione fallisce
Dipende da che cosa fallisce. Un errore di sintassi, o il nome di una tabella, di una colonna o di una funzione che non esiste, non tocca ciò che è in sospeso: correggi la query e prosegui. Nemmeno Visual EXPLAIN su una query scritta male.
Un errore che avviene in esecuzione fa annullare a DuckDB l'intera transazione, e con essa tutte le modifiche non salvate, non solo ciò che tentava l'istruzione fallita: una cella o una nuova riga che viola un vincolo, un valore che non si può convertire, una divisione intera per zero, un SET di un'impostazione del motore — la configurazione è bloccata; i due che propongono i messaggi del motore li ferma prima Calíope e non annullano nulla — o una query che fermi con Interrompi. Calíope lo dice accanto all'errore, il punto ambra sparisce e la griglia torna a mostrare ciò che è salvato. Non c'è nulla da annullare a mano: quello che fai dopo va in una nuova transazione. Prima di provare delle query, salva ciò che non vuoi perdere.
Per uno script vale lo stesso: se fallisce in esecuzione, ciò che le sue istruzioni precedenti hanno scritto se ne va con la transazione; se fallisce per la sintassi o per un nome, ciò che hanno scritto resta in sospeso.
Da solo, DuckDB 2.0 annullerebbe la transazione a ogni errore; Calíope apre ogni file con la regola di DuckDB 1.5, quella descritta sopra. Lo spiega l'argomento Cosa cambia con DuckDB 2.0.
DuckDB scrive prima in un file .wal accanto al .duckdb; il riversamento nel file principale (CHECKPOINT) è asincrono, quindi il .wal può impiegare qualche secondo a sparire dopo il salvataggio e la chiusura — il dato è già al sicuro, anche se quel file accessorio resta lì ancora un momento.
Parole chiave: salvare, ripristinare, confermare, transazione, modifiche, wal, checkpoint
Dai a DuckDB thread e memoria, ed esegui un checkpoint o compatta il file.
La sezione Impostazioni è per l'Editor DuckDB ciò che la sezione Pragmas è per l'Editor SQLite. In Modificabili, Thread e Limite di memoria (MB) si applicano con Applica: la configurazione di DuckDB è bloccata finché un file è aperto —un SET threads o SET memory_limit non la cambia: il motore lo rifiuta e, come ogni errore in esecuzione, questo annulla le modifiche non salvate—, quindi Calíope conserva il valore e riapre il file con esso. Appartengono a questo dispositivo —un Mac e un iPad non hanno gli stessi core né la stessa memoria— e non viaggiano con il resto delle tue preferenze. Con un database in memoria non c'è un file da riaprire, e non si applicano.
Manutenzione esegue Checkpoint —che riversa il .wal nel file—, Forza checkpoint, Vacuum e Analizza, e la risposta del motore compare sotto i pulsanti. Come le impostazioni, i pulsanti restano disattivati finché ci sono modifiche non salvate: salva o ripristina prima. Le altre impostazioni del motore sono elencate in Sola lettura con il loro valore attuale.
Parole chiave: impostazioni, thread, memoria, limite di memoria, manutenzione, checkpoint, vacuum, analizza, wal
Da Importa / Esporta puoi importare un file CSV in una nuova tabella di colonne testo, esportare una tabella in CSV o JSON, o esportare l'intero database come dump SQL (schema e dati).
Questo è diverso da Interroga file di dati…: qui il CSV viene copiato dentro il file .duckdb come nuova tabella; lì il file resta dov'è e viene solo interrogato tramite una vista.
Con DuckDB il CSV lo legge il motore stesso (COPY … AUTO_DETECT), così ogni colonna entra con il suo tipo e non come testo. E Database intero riversa tutto il database in una cartella scelta da te —in CSV o in Parquet, con lo schema accanto— oppure legge nel database aperto ciò che ha lasciato un'altra esportazione. Se il database è in memoria, Salva con nome… lo scrive per intero in un file .duckdb e prosegue su quello.
Esportare e importare l'intero database richiedono che non ci siano modifiche non salvate: Calíope le esegue fuori dalla transazione in sospeso, perché un errore a metà —una tabella che esiste già, una cartella senza permesso— la annullerebbe con tutto ciò che non avevi salvato. Salva con nome… non lo richiede: conferma prima ciò che è in sospeso, e con un database in memoria questo non tocca alcun file.
Parole chiave: importare, esportare, csv, json, sql, dump
Interroga un CSV, JSON o Parquet come se fosse una tabella, senza copiarlo.
Il pulsante Interroga file di dati… crea, per ogni file scelto, una vista su di esso — read_csv_auto, read_json_auto o read_parquet a seconda dell'estensione: il file resta dov'è e viene letto al volo ogni volta che si interroga la vista, senza copiarne i dati dentro il database.
Il nome della vista viene dal nome del file, senza estensione; se due file darebbero lo stesso nome, al secondo si aggiunge _2, al terzo _3, e così via. In Struttura, queste viste hanno un'icona diversa — una graffetta — e il loro tooltip mostra il percorso del file di origine.
Se non c'è nessun database aperto, il pulsante apre prima un database in memoria: non esiste alcun file .duckdb su disco, quindi Salva con nome… è il modo per non perdere il lavoro alla chiusura: lo scrive per intero in un file .duckdb e l'editor prosegue su quel file.
Un file Parquet aperto dall'esterno di Calíope — dal Finder con Apri con › Calíope, o condiviso dall'app File — arriva anche qui: apre un database in memoria con la vista su quel file e lascia SELECT * FROM read_parquet(…) LIMIT 100; scritto in Esegui SQL, senza eseguirlo.
iPad e Apple Vision Pro: anche il pannello di dettaglio mostra il file di origine.
Parole chiave: csv, json, parquet, interrogare, vista, collegare, in memoria
Il pulsante Riepilogo di Dati scrive SUMMARIZE sulla tabella aperta e lo esegue: una riga per colonna con tipo, intervallo, valori distinti, nulli e quartili.
Dove si trova: Workspace › Strumenti › Editor DuckDB
In Dati, con una tabella scelta, il pulsante Riepilogo scrive SUMMARIZE <schema>.<tabella>; nell’editor, passa a Esegui SQL e lo esegue. Il risultato ha una riga per colonna, con tipo, minimo, massimo, numero approssimativo di valori distinti, percentuale di nulli, media e quartili.
È una funzione di DuckDB: l’Editor SQLite non disegna il pulsante.
Parole chiave: summarize, riepilogo, statistiche, colonne, DuckDB