Questa pagina descrive Calíope 1.7, la versione che sto costruendo adesso. La 1.6 è 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.
Una query salvata con il suo output definito e i suoi parametri dichiarati.
Dove si trova: Workspace › Strumenti › Report
Un report non è uno snippet. Uno snippet è testo che si incolla nell’editor; un report è un artefatto che si esegue: memorizza le colonne che si aspetta, come si presentano, quali parametri chiede e da quale fonte proviene.
Per questo eseguirlo due volte dà la stessa cosa, e per questo quando ciò che arriva non coincide con quanto dichiarato te lo si dice in alto invece di disegnare una tabella diversa in silenzio.
Funziona con database relazionali, con MongoDB e con Redis.
Un report può essere composto da più istruzioni, purché l’ultima sia il SELECT che produce la tabella.
Dove si trova: Workspace › Strumenti › Report
Non tutti i report nascono da una sola query. Puoi impostare una variabile di sessione, costruire una tabella temporanea in più passaggi, indicizzarla e leggerla alla fine. L’intero script gira su una sola connessione, quindi la tabella temporanea creata nella prima istruzione esiste ancora nell’ultima.
Cosa puoi usare prima del SELECT finale: SET e USE per la sessione, CREATE TEMPORARY TABLE e la scrittura nelle tabelle create da questo stesso report — INSERT, UPDATE, DELETE, indici, ALTER. Anche le letture intermedie sono ammesse.
Cosa non puoi: scrivere in una tabella reale, CREATE TABLE senza TEMPORARY, SET GLOBAL, PREPARE, EXECUTE e CALL. È un elenco chiuso, e ciò che ne resta fuori viene rifiutato, indicando il numero dell’istruzione, prima di eseguire qualsiasi cosa.
Anche SELECT … INTO una tabella reale resta fuori: in vari motori crea quella tabella.
SQL Server
In SQL Server una tabella temporanea è quella il cui nome inizia con # (CREATE TABLE #t, SELECT … INTO #t, DROP TABLE #t), senza TEMPORARY. Creala senza parametri e riempila dopo con un INSERT: i valori associati viaggiano tramite sp_executesql, e una tabella temporanea creata lì dentro scompare quando quell'istruzione termina. Calíope lo dice prima di eseguire qualsiasi cosa.
ClickHouse
In ClickHouse la tabella temporanea si crea con CREATE TEMPORARY TABLE e vive nella memoria del server. Via HTTP ogni istruzione è una richiesta indipendente, quindi Calíope apre per ogni esecuzione del report una sessione del server tutta sua, e alla fine elimina la tabella temporanea. La tabella temporanea della prima istruzione esiste nell’ultima, e nessun altro la vede. L’account ha bisogno del privilegio CREATE TEMPORARY TABLE; con uno di sola lettura il report fallisce alla prima istruzione, e il messaggio lo dice.
Oracle
In Oracle ogni istruzione del report viene confermata quando finisce, e questo decide come si scrive la tabella temporanea. Una GLOBAL TEMPORARY TABLE ha bisogno di ON COMMIT PRESERVE ROWS: con l’ON COMMIT DELETE ROWS predefinito arriva vuota al SELECT finale. Una privata (CREATE PRIVATE TEMPORARY TABLE ora$ptt_…) ha bisogno di ON COMMIT PRESERVE DEFINITION: con quella predefinita sparisce alla seconda istruzione. Alla fine, Calíope svuota ed elimina la tabella temporanea sulla stessa connessione, anche se il report fallisce, quindi quella globale non resta nel tuo schema. Oracle non ha né SET né USE: il report gira nello schema dell’account, e una tabella di un altro schema si scrive con quello davanti (demo.pedidos).
Il motivo è una promessa: un report non tocca mai i tuoi dati. È ciò che rende sicuro programmarne uno alle tre del mattino.
Su una connessione con un’etichetta di ambiente di sola lettura, un report può creare le sue tabelle temporanee; nient’altro.
Parole chiave: batch, tabella temporanea, più istruzioni, script, preparazione
Dichiarati con tipo e valore predefinito, viaggiano separati dalla query.
Dove si trova: Report › Dichiara i parametri
Si dichiarano in «Dichiara i parametri», nella barra dello strumento: ognuno con il suo nome, il suo tipo, se è obbligatorio e con quale valore arriva. Nel testo si scrivono come «:nome» in SQL e come "$$nome" nel JSON di MongoDB.
Scriverli nel testo non li dichiara. Non è quella la strada: un segnaposto non dichiarato fa fallire la validazione del report. Quello che il foglio fa, invece, è proporti quelli che la query usa già, per dichiararli con il nome esatto.
Un parametro è un valore, non un pezzo di query. Non viene mai incollato nel testo: viaggia legato separatamente, quindi niente di ciò che scrivi lì può rompere la query o cambiare quello che fa.
Il contrappasso è che non si può parametrizzare il nome di una tabella, né una lista IN(…) di lunghezza variabile con un solo segnaposto. Per la lista c’è il tipo «lista», che espande tanti segnaposto quanti sono i valori; per il nome di tabella non c’è supporto, ed è voluto.
Parole chiave: parametro, binding, iniezione, lista
Quali colonne si vedono, in che ordine, con quale titolo e quale formato.
Dove si trova: Report › Output
È ciò che trasforma una query salvata in un report. Puoi nascondere colonne, riordinarle, dar loro un titolo tuo, scegliere il formato (migliaia, due decimali, percentuale, valuta, data, byte) e il loro allineamento.
A piè di pagina puoi aggiungere aggregati per colonna: somma, media, minimo, massimo e conteggio. I nulli non contano: una media divide per i valori presenti, non per le righe.
L’ordine che scegli qui è di presentazione e non riscrive la tua query.
Parole chiave: colonne, formato, aggregato, grafico
CSV, TSV, JSON, Markdown, HTML, XML, testo, Excel e un PDF impaginato.
Dove si trova: Report › Esporta
Si esporta ciò che dichiara l’output: le colonne visibili, nel loro ordine, con i loro titoli e formati. Un PDF che dice «Importo» e un CSV che dicesse «total_eur» non sarebbero lo stesso report.
Una colonna senza formato dichiarato si esporta in CSV, TSV, JSON, XML ed Excel con il suo valore esatto —tutti i decimali, senza separatore delle migliaia, e la data come 2020-01-01—, perché la leggerà un altro programma; nel PDF, nell'HTML, nel Markdown e nel Testo esce come si vede sullo schermo. Un formato che dichiari si esporta sempre.
Il PDF è impaginato, con l’intestazione ripetuta su ogni pagina e la sua numerazione; aggregati e avvisi vanno sull’ultima.
Tutto passa dal pannello di salvataggio del sistema: Calíope non scrive mai in una cartella che non hai scelto tu.
Parole chiave: esportare, pdf, excel, csv, condividere
Giornaliero, settimanale, feriali, mensile o ogni N ore — con un limite che conviene sapere.
Dove si trova: Report › Pianifica
Le esecuzioni pianificate avvengono solo con Calíope aperta. Non c’è un servizio in background, né un demone, né un agente di avvio: sul Mac gira con l’app aperta, e sull’iPad, solo in primo piano — a un report non viene concessa alcuna finestra in background.
Se l’app è chiusa all’ora prevista, l’esecuzione viene annotata nella cronologia come saltata, con il suo motivo, e ritentata alla successiva. Le esecuzioni perse non vengono mai lanciate tutte insieme.
Senza nessuno davanti si usa il valore predefinito di ogni parametro. Un parametro obbligatorio senza valore non viene mai inventato: l’esecuzione viene annotata come saltata.
Si programmano soltanto i report di un server relazionale: in una sessione MongoDB o Redis il pulsante non c’è.
Apple Vision Pro: come sull'iPad, solo in primo piano.
Cosa è stato eseguito, quando, con quali valori e su quale macchina.
Dove si trova: Report › Cronologia
Ogni esecuzione lascia la sua riga: qualunque cosa accada, comprese quelle annullate e saltate. Si conserva con quali parametri è stata eseguita, quante righe ha restituito, quanto ha impiegato, quale macchina l’ha eseguita e — quando ci sono due indirizzi possibili — attraverso quale si è connessa.
Report e backup condividono la stessa cronologia con due ambiti stagni: da Report non vedi nemmeno una riga di backup, e viceversa.
Le righe più vecchie di 180 giorni vengono eliminate da sole. La cronologia resta su questo dispositivo: non va su iCloud.
Se la cronologia stessa non si è potuta scrivere —per esempio con il disco pieno—, il piè di pagina te lo dice: allora mancano righe, e quello che vedi non è tutto ciò che è stato eseguito.
Parole chiave: cronologia, esecuzioni, conservazione, audit
Nel foglio di output si attiva un grafico a barre, a linee o a torta: una colonna dà le etichette e le colonne numeriche i valori.
Dove si trova: Workspace › Strumenti › Report
Nel foglio di output di un report, la sezione Grafico attiva un grafico con «Disegna un grafico». Scegli il suo Tipo —barre, linee o torta—, la Colonna etichetta che dà le etichette, e una o più colonne numeriche per i valori. Se nessuna colonna del risultato è numerica, il foglio lo dice.
Il grafico viene disegnato sopra la tabella. Se deve lasciare fuori delle serie, lo segnala, e VoiceOver lo legge come un riepilogo.
Parole chiave: grafico, diagramma, barre, linee, torta, report