PlyxSQL — Manuale
Connettersi ai dati (parte A), usare l’albero e la scheda Tables (parte B), progettare lo schema con il Designer (parte C), configurarne la semantica per l’AI (parte G), leggerlo come modello a stella di fatti e dimensioni (parte H), spostare dati con l’ETL (parte D), misurare le prestazioni (parte E), visualizzare i dati con l’Analisi (parte F), costruire query trascinando tabelle (capitoli 1–14) e rifinirle, eseguirle e analizzarne i risultati (capitoli 15–24) e usare i menu (capitoli 25–37).
Panoramica: le parti di PlyxSQL
PlyxSQL è un’unica finestra con un albero a sinistra, una fila di schede (Tables, Builder, Designer, ETL, Analisys, Performance-Profiler) e l’Editor SQL in basso. Menu e barra degli strumenti cambiano con la scheda attiva. Lo schema mostra come le parti si collegano; ogni riquadro è un link al capitolo.
| Parte | Argomento | Che cosa trovi | |
|---|---|---|---|
| A | Connessioni | Tipi di connessione, rete, file, ODBC, SSH, salvataggio | → |
| B | Albero e Tables | Albero database, ricerca, esportazione, modifica dati e struttura | → |
| C | Designer | Schema visuale, chiavi esterne, ruoli, DDL | → |
| G | Configurazione semantica | Alias, lookup, calcolati, filtri, prompt AI, pacchetto | → |
| H | Star schema | Fatti, dimensioni, grain, query guidate, collegamento all’ETL | → |
| D | ETL | Fasi, regole sui campi, esecuzione, pianificazione | → |
| E | Performance-Profiler | Misure, soglie, piano di esecuzione, storico | → |
| F | Analisi | Grafici e mappe dai risultati di una query | → |
| I | Barre degli strumenti | I pulsanti di ogni scheda, con schermate numerate | → |
| 1–14 | Builder | Diagramma, JOIN, campi, barra comandi, tab, salvataggio | → |
| 15–24 | Editor SQL | Scrivere ed eseguire SQL, risultati, transazioni, cronologia | → |
| 25–37 | Menu | Tutte le voci di menu e le altre modalità | → |
I1. La barra degli strumenti principale
La barra degli strumenti sta sotto i menu ed è condivisa da tutte le schede, ma mostra solo i gruppi della scheda attiva: Builder e Designer hanno ciascuno i propri, l’ETL i suoi, Analisys e Performance-Profiler condividono quelli dell’Analisi. I gruppi 1 e 2 (progetto e connessione) ci sono sempre.
| Scheda | Menu visibili | Gruppi della barra |
|---|---|---|
| Tables / Builder | File, Modifica, Query, Vista, Schema, DDL, Connessione, Tab, Snippet/History, Strumenti, Impostazioni, Extra, ? | 1, 2, esecuzione, transazioni, editor, AI, confronto (I2) |
| Designer | File, Modifica, Schema Design, DDL, Connessione, Tab, Snippet/History, Strumenti, Impostazioni, Extra, ? | 1, 2, schema, vista, genera, importa/salva, tab, AI, confronto (I3) |
| ETL | File, Impostazioni, ETL, ? | 1, 2, fasi, campi, connessioni, progetto, esecuzione (I4) |
| Analisys | File, Impostazioni, Analytics, ? | 1, 2, configurazione, esportazione, aggiorna (I5) |
| Performance-Profiler | File, Impostazioni, Analytics, ? | come Analisys (I6) |
Gruppi comuni a tutte le schede
| # | Pulsante | Che cosa fa | Tasti |
|---|---|---|---|
| 1 | Nuovo progetto | Parte da un progetto vuoto. Se ce n’è uno con modifiche chiede di salvarle. | Ctrl+N |
| 1 | Apri progetto | Apre un file progetto salvato (connessioni, tab, diagrammi). | Ctrl+Shift+O |
| 1 | Salva progetto | Salva il progetto. Il titolo della finestra mostra * finché ci sono modifiche non salvate. | Ctrl+S |
| 1 | Salva con nome | Salva il progetto in un nuovo file. | Ctrl+Shift+S |
| 2 | Connetti | Apre la connessione attiva (quella scelta nell’albero). | — |
| 2 | Disconnetti | Chiude la connessione attiva. | — |
I2. Builder
Sotto la barra principale il Builder ha una seconda barra con i pulsanti del diagramma (Run, Schema, Clear, Save, Load, Print, Undo, Redo, SQL, Fit, ERD, DDL, AI, Perf, Snip, Export, Subq, Expl, ExpG, CmpPlan, Tabs, Save.fdp, Load.fdp): sono descritti nel capitolo 9. Qui i gruppi della barra principale:
| # | Pulsante | Che cosa fa | Tasti |
|---|---|---|---|
| 3 | Esegui | Esegue l’SQL corrente nell’Editor o la parte selezionata. | F5 |
| 3 | Esegui come script | Esegue il testo come script a più istruzioni. | F6 |
| 3 | Esegui query del Builder | Genera ed esegue la query del tab attivo del Builder. | F7 |
| 4 | Inizia transazione | BEGIN TRANSACTION: le istruzioni successive restano in sospeso. | Ctrl+B |
| 4 | Commit | Rende definitive le modifiche della transazione. | Ctrl+M |
| 4 | Rollback | Annulla le modifiche della transazione. | Ctrl+Shift+B |
| 5 | Annulla | Annulla l’ultima operazione. | Ctrl+Z |
| 5 | Ripristina | Ripristina l’operazione annullata. | Ctrl+Y |
| 5 | Formatta SQL | Riformatta il testo SQL corrente. | Ctrl+Shift+F |
| 5 | Copia tutto | Copia l’intero testo SQL negli appunti. | Ctrl+Shift+C |
| 6 | Query con AI | Genera la query da una richiesta in linguaggio naturale. | Ctrl+Shift+A |
| 6 | Costruisci dal SQL dell’Editor | Legge l’SQL dell’Editor e disegna tabelle e JOIN nel Builder. | Ctrl+Shift+Q |
| 7 | Confronta schemi | Confronta lo schema di due connessioni e mostra le differenze. | — |
| 7 | Confronta dati | Confronta i dati di due tabelle. | — |
| 7 | Confronta tag | Confronta i tag (versioni) dello schema. | — |
I pulsanti di esecuzione e transazione richiedono una connessione attiva e SQL nell’Editor. La stessa funzione è nei menu Query e Modifica (cap. 28).
I3. Designer
Nel Designer la barra comprende i pulsanti per costruire, importare, salvare e generare lo schema. Il menu è Schema Design (parte C). Il pulsante Analisi star schema non ha un’icona nella barra: si apre dal menu Schema Design (I7).
| # | Pulsante | Che cosa fa | Tasti |
|---|---|---|---|
| 3 | Genera prompt AI | Genera il JSON-prompt dallo schema semantico configurato (finestra di verifica del prompt AI). | Ctrl+Shift+J |
| 3 | Raffina con AI | Chiede all’AI di modificare lo schema già presente. | — |
| 3 | Genera con AI | Descrivi lo schema a parole e il programma lo propone. | Ctrl+Shift+I |
| 4 | Rinomina tab schema | Rinomina il tab schema attivo. | — |
| 4 | Chiudi tab schema | Chiude il tab schema attivo. | Ctrl+Alt+W |
| 4 | Nuovo tab schema | Aggiunge un nuovo tab schema al Designer. | Ctrl+Alt+N |
| 5 | Esporta PNG | Salva il diagramma come immagine PNG. | — |
| 5 | Esporta SVG | Salva il diagramma come immagine vettoriale SVG. | — |
| 5 | Pulisci schema | Svuota lo schema (chiede conferma). | — |
| 5 | Carica schema | Carica un file schema .sdschema (JSON), con il modello a stella se c’è. | — |
| 5 | Esporta pacchetto semantico | Esporta il Configuratore Semantico in un JSON portabile per un componente server (G18). | — |
| 5 | Salva schema | Salva lo schema in un file (tabelle, colonne, FK, posizioni, modello a stella). | — |
| 5 | Aggiorna dal database | Riallinea lo schema già nel canvas con il database. | — |
| 5 | Importa da database | Legge lo schema dalla connessione attiva, scegliendo le tabelle. | — |
| 5 | Importa da DDL | Costruisce lo schema da uno script DDL. | — |
| 6 | Esporta dialetto | Esporta il DDL nel dialetto scelto. | — |
| 6 | Genera REST | Voce Genera REST del menu Schema Design. | — |
| 6 | Genera ALTER | Genera gli ALTER TABLE delle differenze rispetto a uno snapshot. | — |
| 6 | Genera DDL | Genera lo script DDL dello schema nel tab Schema Designer dell’Editor (C8). | F7 |
| 7 | Riduci | Riduce lo zoom del canvas. | Ctrl+- |
| 7 | Ingrandisci | Aumenta lo zoom del canvas. | Ctrl+= |
| 7 | Adatta | Adatta lo zoom per mostrare tutto lo schema. | Ctrl+Shift+0 |
| 7 | Disposizione automatica | Dispone le tabelle in automatico. | — |
| 8 | Elimina selezione | Elimina le tabelle o le chiavi esterne selezionate. | — |
| 8 | Aggiungi chiave esterna | Crea una chiave esterna fra due tabelle. | — |
| 8 | Aggiungi tabella | Aggiunge una tabella al canvas. | — |
| 9 | Confronta schemi | Confronta lo schema di due connessioni e mostra le differenze. | — |
| 9 | Confronta dati | Confronta i dati di due tabelle. | — |
| 9 | Confronta tag | Confronta i tag (versioni) dello schema. | — |
I4. ETL
Nella scheda ETL restano visibili solo i menu File, Impostazioni, ETL e ?. I pulsanti sulle fasi e sui campi sono grigi finché non selezioni una fase o un campo. Il menu ETL ha in più la voce Collegamento al modello a stella… (H16), che non ha un’icona.
| # | Pulsante | Che cosa fa | Tasti |
|---|---|---|---|
| 3 | Annulla esecuzione | Interrompe l’importazione in corso. | — |
| 3 | Esegui ETL | Esegue le fasi del progetto ETL (D8). | F9 |
| 4 | Salva per il servizio | Salva un file .petl per il servizio Windows delle importazioni pianificate (D9). | — |
| 4 | Carica progetto ETL | Apre un progetto ETL salvato. | — |
| 4 | Salva progetto ETL | Salva il progetto ETL per riaprirlo in questa applicazione. | — |
| 5 | Connessione di destinazione | Imposta come destinazione la connessione scelta nell’albero. | — |
| 5 | Connessione di origine | Imposta come origine la connessione scelta nell’albero. | — |
| 6 | Genera campi | Crea i campi della fase dalle colonne. | — |
| 6 | Elimina campo | Elimina il campo selezionato. | — |
| 6 | Modifica campo | Apre le regole del campo selezionato (D5). | — |
| 6 | Nuovo campo | Aggiunge un campo alla fase. | — |
| 7 | Elimina tutte le fasi | Elimina tutte le fasi (chiede conferma). | — |
| 7 | Elimina fase | Elimina la fase selezionata. | — |
| 7 | Modifica fase | Apre le impostazioni della fase (D4). | — |
| 7 | Genera fasi da tabelle corrispondenti | Crea una fase per ogni coppia di tabelle con lo stesso nome in origine e destinazione. | — |
| 7 | Nuova fase | Aggiunge una fase al progetto. | — |
I5. Analisys
Nella scheda Analisys i menu visibili sono File, Impostazioni, Analytics e ?. Sotto la barra principale c’è la barra propria dell’Analisi (Esporta, Copia immagine, Salva, Carica, Aggiorna, Risoluzione, Titolo), descritta nella F3 e nella F8.
| # | Pulsante | Che cosa fa | Tasti |
|---|---|---|---|
| 3 | Carica configurazione | Carica la configurazione del grafico da un file. | — |
| 3 | Salva configurazione | Salva la configurazione del grafico in un file. | — |
| 4 | Esporta CSV | Esporta i dati del grafico in CSV. | — |
| 4 | Esporta SVG | Esporta il grafico come SVG. | — |
| 4 | Esporta PNG | Esporta il grafico come immagine PNG. | — |
| 5 | Aggiorna | Rilegge i dati della query e ridisegna il grafico. | F5 |
I6. Performance-Profiler
La scheda Performance-Profiler usa la stessa barra e lo stesso menu Analytics di Analisys: i gruppi sono quelli della I5. Il Profiler misura il testo SQL che c’è nell’Editor sulla connessione attiva (E1), quindi per lavorarci servono una connessione e uno SQL nell’Editor; le funzioni del profilo (misura, soglie, piano di esecuzione, storico) sono nei controlli della scheda stessa (E2–E7), non nella barra.
I7. Star schema nell’interfaccia
Dove si trova
| Dove | Che cosa fa |
|---|---|
| Schema Design → Analisi star schema (fatti e dimensioni)… | Apre la finestra del modello a stella. Serve uno schema aperto nel Designer. |
| ETL → Collegamento al modello a stella… | Confronta il progetto ETL con il modello dello schema attivo e propone le correzioni (H16). Serve un progetto ETL e uno Schema Designer aperti. |
| Salva schema / Carica schema | Il modello a stella vive nel file dello schema (H2). |
La finestra: schermate
All’apertura su un modello vuoto l’albero mostra le fact e le dimensioni già lette dallo schema; i riquadri di query sono ancora vuoti.
Le due schermate sono precedenti all’aggiunta del pulsante Esegui, che nella versione attuale sta fra Apri nel Query Builder e Chiudi.
Selezionando una misura e premendo + Misura la query si costruisce: a destra compare l’SQL generato e sotto le segnalazioni. Nella schermata la query somma tre misure di FACT_BUDGET; sotto l’albero ci sono le proprietà della misura (additività, aggregazione, “nel tempo”) con Applica al modello.
Pulsanti
| Pulsante | Che cosa fa |
|---|---|
| Proponi modello dallo schema | Bozza di fact e dimensioni dalle chiavi esterne (H3). |
| Valida modello | Scrive le segnalazioni STARxxx nel riquadro in basso (H14). |
| + Attributo / + Misura / + Filtro | Aggiungono alla query il nodo selezionato nell’albero. |
| Colonne del grain…, Applica al modello, + Derivata… | Modificano il modello (H4, H11). |
| Elimina fact/dimensione | Toglie dall’albero il nodo selezionato. |
| Copia SQL | Copia la query negli appunti. |
| Esegui | Esegue la query generata sulla connessione attiva e mostra il risultato in una finestra con griglia (al massimo 5000 righe). La finestra star resta aperta: puoi cambiare la query e rilanciare. |
| Apri nell’editor | Porta l’SQL nell’Editor; per eseguirlo premi Esegui (una SELECT dà un result set anche nel Designer, v. I3). |
| Apri nel Query Builder | Solo per la forma semplice (H7). |
Eseguire una query nel Designer
Con Apri nell’editor la SELECT va nel tab Schema Designer dell’Editor; premendo Esegui sulla barra dell’Editor il risultato compare nel pannello risultati, sotto il testo, con righe, colonne e millisecondi:
A1. Panoramica delle connessioni
Ogni database, file o servizio web con cui lavori in PlyxSQL è una connessione. Una connessione ha un alias (il nome che vedi nelle tab del Builder e dell’Editor), un tipo e i suoi parametri. Puoi crearla in tre modi diversi, scelti dalle schede del dialogo Nuova Connessione:
| Scheda | Per cosa serve |
|---|---|
| Rete | Server di database: Firebird, InterBase, MySQL / MariaDB, SQL Server, PostgreSQL, Oracle, Informix, IBM DB2, più SQLite e MS Access come file. |
| File / LocalSQL | SQLite, CSV, Excel / ODS, JSON, XML, tracciati a posizione fissa, ClientDataSet, FDMemTable e API REST: i file diventano tabelle su cui scrivere SQL. |
| ODBC | Qualsiasi sorgente con un driver ODBC installato, oppure un DSN già definito in Windows. |
| SSH Tunnel | Non è un tipo di database: instrada la connessione attraverso un server SSH (bastion). Vale per le connessioni di rete. |
La connessione può essere salvata in un file .fdc nella cartella delle connessioni e ricompare nell’albero a ogni avvio.
A2. Schermata iniziale
All’avvio compare la schermata iniziale, con tre colonne e due pulsanti:
| Elemento | Che cosa fa |
|---|---|
| Nuovo progetto… | L’elenco dei tipi di sorgente (Excel/Open Calc, Firebird, InterBase, MySQL, SQL Server, PostgreSQL, Oracle, SQLite, MariaDB, Access, Informix, DB2, file CSV e ClientDataSet…), con la casella di ricerca che filtra mentre scrivi. Scegliendo una voce si apre il dialogo Nuova Connessione già impostato su scheda e driver (nell’esempio, "Native Excel" apre la scheda File / LocalSQL sul tipo Excel/ODS). Sotto ogni voce un link rimanda alla documentazione FireDAC del driver. Le voci per i connettori web (Gmail, Google Calendar…) aprono la gestione del connettore. Alcune voci portano un modello di tracciato (.tracciato, nella cartella templates accanto al programma) per aprire direttamente un file a posizione fissa. |
| Apri recente | I progetti usati di recente, con casella di ricerca. Selezionando una voce il progetto si apre. Una voce recente può essere aggiunta ai Preferiti oppure tolta dall’elenco. |
| Preferiti | I progetti che hai fissato. L’elenco viene salvato nella cartella dell’utente (%APPDATA%\PGSOFT\plyxsql) e ricompare a ogni avvio; anche questo ha la sua ricerca. |
| Video-corsi | Un elenco di video tutorial collegato online. |
| Apri progetto | Apre un file di progetto .mfdproj con la finestra di scelta file. Il progetto si apre e la schermata iniziale lascia il posto all’area di lavoro. |
| Dark / Light | Scelta del tema. |
- Nella schermata iniziale compaiono anche i riquadri delle analisi salvate (vedi F8).
- F10 in qualsiasi momento riporta alla schermata iniziale, nascondendo menu e barra strumenti.
- Quando ci sono modifiche non salvate, alla chiusura del programma ti viene chiesto se salvare il progetto (Sì, No, Annulla).
- Un pannello di aggiornamento in alto segnala se è disponibile una nuova versione del programma.
A3. Aprire il dialogo Nuova Connessione
- Dalla schermata iniziale (vedi sopra).
- Dall’albero: clic destro sulla cartella Connessioni o su un file
.fdc→ Nuova connessione. - Dal menu Connessione → Nuova connessione.
In cima al dialogo c’è l’Alias connessione. Viene proposto automaticamente in base al tipo (FB_Conn, SQLite_Conn, Excel_Conn…) e si aggiorna quando cambi scheda o driver, finché non lo modifichi tu a mano. Non puoi usare un alias già in uso da una connessione aperta: il programma ti avvisa e ne propone uno libero.
A4. Scheda Rete
- Alias connessione
- Schede: Rete, File / LocalSQL, ODBC, SSH Tunnel
- Driver
- Server / host e Porta
- Database / percorso con Browse…
- Nome utente e Password
- Crea database se non esiste
- Parametri aggiuntivi (Chiave=Valore)
- Test connessione
- Parametri avanzati…
- Connetti e aggiungi
Quando scegli il driver, porta e utente vengono impostati ai valori predefiniti:
| Driver | Porta | Utente | Note |
|---|---|---|---|
| FB (Firebird) | 3050 | SYSDBA | Database = nome o percorso sul server, per esempio SB.FDB |
| IB (InterBase) | 3050 | SYSDBA | |
| MySQL | 3306 | root | Vale anche per MariaDB (vedi nota) |
| MSSQL (SQL Server) | 1433 | sa | |
| PG (PostgreSQL) | 5432 | postgres | |
| Ora (Oracle) | 1521 | sys | |
| Infx (Informix) | 9088 | informix | |
| IBM (DB2) | 50000 | db2inst1 | |
| SQLite | — | — | Server e porta spariscono: Database è il percorso del file .db / .sqlite |
| MSAcc (MS Access) | — | — | Database è il file .mdb / .accdb |
Cambiando driver l’utente viene riportato al valore predefinito e la password svuotata. Se la Porta è vuota o 0 si usa quella predefinita del driver.
Crea database se non esiste
La casella compare per Firebird, InterBase, MySQL, SQL Server, PostgreSQL, Oracle, Informix e DB2 (non per SQLite e Access). Con Firebird e InterBase la connessione viene aperta in modalità OpenOrCreate; con gli altri driver viene richiesta la creazione del database.
MySQL. Il dialetto MariaDB si sceglie a mano per quella connessione (Impostazioni → Dialetto) e viene salvato nel progetto.A5. Scheda File / LocalSQL
Il menu Tipo connessione elenca gli 11 formati disponibili. Una riga di aiuto sotto il menu descrive il formato scelto, e per i tipi da cartella compare il campo Cartella file (con Browse…) e le Estensioni da considerare.
| Tipo | Cosa fa |
|---|---|
| SQLite — file | Apre un database SQLite (.db, .sqlite, .s3db). Indichi il percorso del file. |
| SQLite — in-memory | Database :memory:: i dati esistono solo durante la sessione. |
| LocalSQL — ClientDataSet | Cartella con file .cds .cdc .aff .icp; ogni file è una tabella. |
| LocalSQL — FDMemTable | Cartella con file .bin .mem. |
| LocalSQL — CSV | Cartella con .csv / .txt, importati come tabelle in memoria. |
| LocalSQL — SQLite file | Cartella con .db / .sqlite: i database vengono collegati con ATTACH DATABASE. |
| LocalSQL — Tracciato a posizione fissa | File di testo a larghezza fissa descritti da un tracciato. |
| REST — API JSON | Endpoint HTTP che restituiscono JSON. |
| JSON, XML | File .json e .xml trattati come tabelle. |
| Excel / ODS | File .xlsx .xls .ods (estensioni modificabili). Un nodo per foglio, non per file. |
Su tutti i tipi LocalSQL puoi poi scrivere SQL come su un database normale: Builder, JOIN tra file diversi e Editor funzionano allo stesso modo.
Opzioni CSV
Scelto il tipo CSV compare un pannello con file di esempio (…), delimitatore di campo, separatore, carattere di virgolette, la casella prima riga = intestazione, la codifica e un’anteprima con il pulsante Aggiorna. Se i dati non sembrano giusti, cambia i separatori e aggiorna l’anteprima prima di confermare.
Tracciato a posizione fissa
Il pannello contiene tipo di record, codifica, righe da saltare e una griglia del layout (nome, inizio, lunghezza dei campi) con i pulsanti Aggiungi campo, Elimina campo, Incolla specifica (analizza un tracciato incollato da testo), Salva specifica e Carica specifica, più un’anteprima.
REST — API JSON
- Nella griglia degli endpoint ogni riga è una tabella: Nome tabella, URL, Percorso JSON (dove si trova l’array di record nella risposta, per esempio
data.items). Con Aggiungi / Elimina gestisci le righe. - Test endpoint scarica il primo endpoint e ti dice quanti record ha trovato oppure l’errore (JSON non valido, percorso non trovato, nessun endpoint).
- Autenticazione: nessuna, Bearer (token), API Key (nome intestazione e valore) o Basic (utente e password).
- I risultati lunghi sono paginati: dall’Editor il pulsante del blocco successivo scarica la pagina seguente. I dati stanno in un database SQLite in memoria, quindi dopo la riapertura del progetto vengono riscaricati al primo uso.
A6. Scheda ODBC
Elenca i driver ODBC installati sul computer (in ordine alfabetico). Puoi usarla in due modi:
- Con un driver: selezionalo nell’elenco e compila Server, Database / file, Utente e Password.
- Con un DSN: scrivi il nome del DSN nel campo apposito. Se il campo DSN è compilato, ha la precedenza sul driver selezionato.
Per i driver basati su file (Excel, Access…) il pulsante … accanto a Database permette di scegliere il file.
A7. Scheda SSH Tunnel
Serve quando il database non è raggiungibile direttamente ma solo tramite un server SSH. Spunta Abilita tunnel SSH e compila:
| Campo | Significato |
|---|---|
| SSH Host | Indirizzo del server SSH (per esempio bastion.myserver.com). |
| Porta SSH | Predefinita 22. |
| Utente SSH | Utente per l’accesso al server SSH. |
| Password SSH | Opzionale. Non viene salvata nel progetto per sicurezza: va reinserita a ogni sessione. |
| Chiave .ppk/.pem | File della chiave privata, in alternativa alla password. |
C:\Program Files\PuTTY, C:\Program Files (x86)\PuTTY, C:\PuTTY e nel PATH di Windows. Se non lo trova il test fallisce con un messaggio. Installa PuTTY e riprova.La porta locale del tunnel viene scelta automaticamente: il server e la porta indicati nella scheda Rete vengono reindirizzati al tunnel durante la connessione e ripristinati alla chiusura. L’attesa massima per aprire il tunnel è di 15 secondi. Il pulsante Test connessione usa il tunnel se è abilitato. Per una connessione già esistente puoi cambiare queste impostazioni con clic destro sul file .fdc → Configura SSH.
A8. Parametri aggiuntivi e avanzati
In fondo al dialogo c’è il riquadro Parametri aggiuntivi: una riga per parametro nel formato Chiave=Valore; le righe che iniziano con # sono ignorate. Servono per le opzioni di FireDAC che non hanno un campo dedicato, per esempio:
CharacterSet=UTF8 Pooled=True Pool_MaximumItems=10 Pool_CleanupTimeout=30000 ExtendedMetadata=True FetchOptions.RecsMax=1000
Il pulsante Parametri avanzati… apre un editor con tutti i parametri della connessione, già composti dai campi che hai compilato; con Applica al wizard le modifiche tornano nel dialogo.
A9. Test, connessione e salvataggio
| Pulsante | Cosa fa |
|---|---|
| ▶ Test connessione | Prova ad aprire la connessione senza aggiungerla. Il risultato compare sopra i pulsanti: ✓ Connessione riuscita (o "via tunnel SSH") oppure ✗ con il messaggio d’errore del database. |
| Connetti e aggiungi | Apre la connessione, la salva e la aggiunge all’albero, creando in automatico le tab collegate nell’Editor e nel Builder. |
| Cancel | Chiude senza creare nulla. |
Prima di connettere, il programma controlla che l’alias sia compilato e non già usato da una connessione aperta. Se esiste già una connessione salvata con lo stesso nome, ti chiede se sovrascriverla.
Dove viene salvata
- File .fdc: in fondo al dialogo c’è la casella Salva .fdc (attiva per impostazione predefinita) con il percorso, proposto come
cartella-connessioni\alias.fdc, e il pulsante Browse. Il file è un normale testo con una sezione[FireDAC]e una rigaChiave=Valoreper parametro. - Archivio dati dell’applicazione: se il programma è integrato con un database proprio per le connessioni, non si usa il file: nome e parametri vengono scritti nel record corrispondente e la casella non compare.
LoginPrompt=False è sempre impostata e non compare nei file.A10. Gestire le connessioni dall’albero
Il menu contestuale cambia in base al nodo su cui clicchi (i nomi esatti dipendono dalla lingua):
| Nodo | Voci |
|---|---|
| Cartella Connessioni | Nuova connessione, Gestione connettori, Apri cartella connettori, Confronta schemi, Confronta dati, Aggiorna. |
| File .fdc | Connetti; se connesso: Disconnetti, Modifica parametri, Assistente AI. Sempre: Configura SSH, Nuova connessione, Gestione connettori, Apri percorso del file, Elimina file. |
| Radice del database (connesso) | Aggiorna, Capacità del server, Matrice SQL, Disconnetti, Modifica parametri. |
Modifica parametri apre l’editor dei parametri su una connessione già creata, così puoi correggere host, porta o credenziali senza ricrearla.
A11. Gestione connettori
I connettori collegano PlyxSQL ai servizi web (Gmail, Google Calendar, Google Drive, GitHub, FreshBooks, Fitbit…). Ogni connettore è una definizione in un file JSON, una per servizio, che elenca gli endpoint: quelli in lettura (GET) diventano tabelle su cui scrivere SQL, quelli in scrittura (POST) sono azioni.
Si apre dal menu contestuale della cartella Connessioni → Gestione connettori (Apri cartella connettori mostra dove stanno i file). La tabella ha quattro colonne: ID, Nome, Endpoint disponibili e Stato. Il campo di ricerca filtra l’elenco mentre digiti. Lo stato Da configurare significa che mancano ancora dei dati del servizio (per esempio il client ID).
Come si usa un connettore
- Configura… Inserisci i dati richiesti dal servizio (tipicamente
clientId,clientSecret,redirectUri). I campi segreti sono mascherati. Se il connettore è già configurato i campi si riaprono con i valori attuali, così correggi solo ciò che serve. Salva chiude; Indietro o Esc annullano. - Autorizza… Apre il browser per l’accesso al servizio (OAuth2 con PKCE). I token vengono cifrati su disco con Windows (DPAPI) e rinnovati in automatico quando scadono.
- Poi scegli come usare i dati:
- Crea connessione… aggiunge il connettore all’albero come connessione, con le sue tabelle.
- Carica in MemTable… scarica un endpoint in una tabella in memoria.
- Azione POST… invia dati a un endpoint di scrittura (per esempio inserire un evento nel calendario); compili i campi richiesti dal modello.
Se un connettore è ancora Da configurare, Autorizza, Crea connessione, Carica in MemTable e Azione POST sono bloccati con un messaggio chiaro invece di fallire con un errore OAuth. Il riquadro scuro sotto i pulsanti è il registro: mostra l’esito di ogni operazione.
A12. Problemi comuni
| Sintomo | Causa e rimedio |
|---|---|
| "Nome connessione già in uso" | Esiste una connessione aperta con lo stesso alias. Scegli un alias diverso (il programma ne suggerisce uno libero). |
| "Esiste già una connessione salvata…" | Il file .fdc con quel nome c’è già. Rispondi Sì per sovrascriverlo, No per cambiare alias. |
| Test fallito con messaggio su plink | PuTTY non è installato o plink.exe non è nel PATH. Installalo (vedi A7). |
| Il test riesce ma la connessione è offline | Il test non salva né aggiunge nulla: serve premere Connetti e aggiungi. |
| Il database Firebird non esiste | Spunta Crea database se non esiste oppure verifica il percorso sul server (è il percorso del server, non del tuo PC). |
| Tabella REST "no such table" dopo la riapertura | I dati REST stanno in memoria e ripartono vuoti. Rilancia la query: il programma riscarica la tabella al volo. |
| Dati CSV tutti in una colonna | Delimitatore sbagliato: cambialo nel pannello CSV e premi Aggiorna. |
B1. L’albero database
A sinistra dell’area di lavoro l’albero mostra tutto ciò che puoi aprire: le connessioni e, sotto ognuna, la struttura del database. È anche il punto da cui si visualizzano e si modificano le tabelle.
- Gerarchia: Connessioni → file
.fdc→ radice del database → cartelle Tabelle, Viste, Sequenze, Stored Procedure. Una tabella si espande in Fields (campi), Indici, Trigger e Constraints (vincoli e chiavi esterne). I contenuti si caricano alla prima apertura del nodo. - Filtra tabelle…: la casella in alto filtra l’albero mentre scrivi, utile con centinaia di tabelle.
- Doppio clic su una tabella: la aggiunge al Builder (cap. 3). Se è attiva la modalità Sfoglia (Browse) apre invece i dati nella scheda Tables. Il commutatore rapido si trova nel menu contestuale.
- Clic destro: il menu cambia in base al nodo (vedi B6).
Sopra l’area di lavoro le schede Tables · Builder · Designer · ETL · Analisi · Performance-Profiler cambiano la modalità. Tables mostra i dati della tabella selezionata nell’albero.
B2. La scheda Tables
- Titolo: la tabella mostrata
- Barra di navigazione: primo, precedente, successivo, ultimo, aggiorna
- Altre righe: carica il blocco successivo
- Colonna su cui agisce il filtro
- Operatore del filtro
- Valore da cercare
- Applica e X (azzera il filtro)
- Contatore: posizione e totale righe
- Esporta: CSV, JSON, XML, XLSX, MemTable, ClientDS
- Filtro=: filtra sul valore della cella
- Modifica: attiva la modifica diretta
Selezionando una tabella nell’albero la griglia si riempie con i suoi dati (SELECT *). Su database come Access e SQLite le righe vengono lette tutte; sugli altri motori i dati arrivano a blocchi e Altre righe accoda il blocco successivo senza perdere ciò che hai già caricato.
Il contatore (1 di 641 righe) indica la posizione del record corrente sul totale reale della tabella, e non sul numero di righe filtrate.
B3. Cercare e ordinare
- Ordinare: clic sull’intestazione di una colonna.
- Filtrare: scegli la Colonna (si aggiorna anche cliccando una cella della griglia), l’Operatore, scrivi il valore e premi Applica. X toglie il filtro.
- Filtro=: prende il valore della cella selezionata e lo applica subito come filtro "uguale a", senza usare le tendine.
| Operatore | Significato |
|---|---|
| = | Uguale |
| contiene | Testo contenuto nel valore |
| > < | Maggiore, minore |
| <> | Diverso |
| è nullo / non è nullo | Valore assente o presente |
Gli operatori disponibili dipendono dal tipo della colonna scelta (per esempio, quelli numerici su un campo numerico).
B4. Esportare i dati
| Pulsante | Risultato |
|---|---|
| CSV | File .csv |
| JSON | File .json |
| XML | File .xml |
| XLSX | Cartella di lavoro Excel; al termine ti chiede se aprirla in Excel |
| MemTable | File binario .fdmt (FDMemTable) |
| ClientDS | File .cds (ClientDataSet) |
L’esportazione contiene quello che vedi: se hai applicato un filtro o un ordinamento, il file riporta solo quelle righe, in quell’ordine. Il programma ti chiede dove salvare il file.
B5. Modificare i dati nella griglia
Il pulsante Modifica (a scatto) rende la griglia scrivibile. Quando è premuto la barra di navigazione aggiunge i comandi per inserire, eliminare, modificare, confermare (Post) e annullare una riga.
Lo stesso risultato si ottiene con clic destro sulla tabella → Modifica dati. Le modifiche vanno direttamente al database: controlla di essere sulla connessione giusta.
B6. Modificare la struttura dal menu contestuale
Con clic destro sui nodi dell’albero si aprono procedure guidate che generano lo script DDL. Cosa succede dello script dipende dall’opzione AutoExecute:
- AutoExecute attivo (e connessione aperta): lo script viene eseguito subito e l’albero si aggiorna.
- AutoExecute spento: lo script viene portato in un tab DDL dell’Editor, dove puoi controllarlo ed eseguirlo tu.
- Un modello con parti da completare (segnaposto, TODO) non viene mai eseguito in automatico: finisce nell’Editor con un’intestazione che lo segnala come incompleto.
| Nodo | Voci del menu |
|---|---|
| Cartella Tabelle | Crea tabella, Aggiorna |
| Tabella | Apri nel Builder · Seleziona prime N righe · Crea indice · Crea trigger · Aggiungi chiave esterna · Modifica tabella (ALTER) · Elimina tabella (chiede conferma) · Modifica dati · Importa dati · Trova utilizzi · Mostra dipendenze · Vista calendario |
| Cartella Indici / un indice | Crea indice · Ricostruisci · Elimina |
| Cartella Trigger / un trigger | Crea trigger · Abilita / Disabilita · Elimina |
| Cartella Constraints / un vincolo | Aggiungi chiave esterna · Elimina vincolo |
| Cartella Viste / una vista | Crea vista · Apri nel Builder · Crea trigger sulla vista · Trova utilizzi · Mostra dipendenze · Elimina |
| Cartella Sequenze / una sequenza | Crea sequenza · Reimposta valore · Elimina |
| Cartella Stored Procedure / una procedura | Crea procedura · Crea da corpo SQL · Esegui · Mostra dipendenze · Elimina |
| Radice del database | Aggiorna, Capacità del server, Matrice SQL, ERD, Confronta schemi/dati, Backup, Ripristino, Esporta/Importa pacchetto team, Disconnetti |
Cosa chiedono le procedure guidate
- Modifica tabella: legge i campi attuali dal database e genera l’
ALTER TABLEper le differenze. Sulle connessioni LocalSQL il driver non supporta il DDL: il wizard mostra solo un commento. - Crea indice: nome, colonne separate da virgola, UNIQUE, Descending. Se il motore non può esprimere la richiesta (per esempio direzioni miste in Firebird) il programma lo dice e non genera nulla.
- Chiave esterna: tabella figlia, nome del vincolo, colonne, tabella e colonne di destinazione, ON DELETE e ON UPDATE (RESTRICT, CASCADE, SET NULL, NO ACTION).
- Crea vista: nome, OR REPLACE e
SELECT. Su SQL Server si usaCREATE OR ALTERal posto di OR REPLACE. - Crea sequenza: non disponibile sui motori che non le hanno (MySQL, SQLite, MS Access); il programma lo comunica.
C1. Che cos’è il Designer
Il Designer è il progettista dello schema fisico: disegni tabelle, colonne e chiavi esterne su un canvas e il programma genera lo script DDL per il dialetto che scegli. Funziona anche partendo da un database esistente o da uno script SQL.
- Barra strumenti del Designer
- Tab dello schema (nell’esempio
sbt_Schema1) - Trova tabella, Vai e Avvicina
- Barra laterale con filtri e layout
- Tabella: intestazione con nome e ruolo (MST = master), colonne con tipo
- Relazione (chiave esterna)
- Minimap
Sotto il canvas l’Editor mostra il DDL generato nel tab Schema Designer, con un’intestazione di commento: nome dello schema, dialetto, data di generazione, numero di tabelle e di chiavi esterne. Nell’esempio sono 18 tabelle e 4 FK, in dialetto Firebird.
C2. Barra laterale e barra superiore
| Pulsante | Funzione |
|---|---|
| ▦ | Mostra tutto |
| ⊞ | Solo tabelle |
| □ | Solo viste |
| λ | Solo procedure e funzioni |
| ☰ | Viste… (gestione delle viste) |
| ƒ | Stored Proc… (gestione delle procedure) |
| ⤆ | Auto layout: dispone le tabelle in automatico |
| 1:1 | Zoom 100% |
| ⌖ | Centra lo schema |
| ⇄ | Alterna schema fisico e grafico semantico (C7) |
In alto a sinistra del canvas: la casella Trova tabella (editabile) con il pulsante Vai, che centra la vista sulla tabella scelta, e Avvicina, che porta la tabella scelta accanto a quella selezionata, comodo per collegare una chiave esterna tra due tabelle lontane.
C3. Creare lo schema
Da zero
- Aggiungi una tabella: menu Schema Designer → Aggiungi tabella oppure clic destro sul canvas.
- Nella finestra Modifica tabella scrivi Nome tabella, Commento, Nota e, per le tabelle di lookup, il nome del campo label.
- Aggiungi le colonne (clic destro sulla tabella → Aggiungi colonna). Per ogni colonna:
| Campo | Significato |
|---|---|
| Nome colonna, Tipo | Nome e tipo di dato; per un tipo non in elenco usa Tipo custom. |
| Lunghezza, Precisione, Scale | Dimensione del tipo (per esempio VARCHAR(30) o DECIMAL(15,2)). |
| Default, CHECK constraint, Commento | Valore predefinito, vincolo di controllo e commento. |
| Nullable, Primary Key, Auto Inc, Unique | Opzioni a spunta. Auto Inc genera l’identità nel modo giusto per il dialetto (su Firebird sequenza e trigger). |
Da qualcosa che esiste già
- Importa da DDL: incolla o apri uno script con i
CREATE TABLE; il dialetto viene riconosciuto dalle parole chiave. - Importa da database: legge lo schema dalla connessione attiva (puoi scegliere le tabelle da importare). Aggiorna dal database riallinea lo schema già nel canvas.
- Genera con AI (Ctrl+Shift+I) e Raffina con AI: descrivi lo schema a parole e il programma lo propone. Richiede la configurazione AI (File → Configurazione AI).
C4. Relazioni (chiavi esterne)
- Clic destro sulla colonna di partenza → Disegna FK.
- Trascina fino alla colonna di destinazione e rilascia. La FK usa le colonne su cui hai cliccato; se non ne hai indicata una, usa la chiave primaria.
Una FK identica a una già esistente non viene duplicata. Per scegliere ON DELETE e ON UPDATE usa clic destro → Regole FK… (anche per una nuova FK: la guida chiede campo sorgente, tabella e campo di destinazione). Per eliminarla selezionala e premi Canc. Esc annulla il disegno in corso.
C5. Muoversi nel canvas
| Gesto | Effetto |
|---|---|
| Trascina una tabella | La sposta |
| Trascina il bordo della tabella | La ridimensiona |
| Rotella sopra una tabella lunga | Scorre i campi (frecce ▲ ▼ nella riga indicatore) |
| Doppio clic su una colonna | Apre la modifica della colonna |
| Doppio clic sull’intestazione | Apre la modifica della tabella |
| Minimap | Trascina per spostare la vista |
| Ctrl+= / Ctrl+- | Zoom avanti / indietro |
| Ctrl+Shift+0 | Adatta lo schema alla finestra |
| Canc | Elimina la tabella o la FK selezionata |
| Esc | Annulla la FK in corso o esce dalla modalità focus |
Tutte le modifiche (aggiunta, eliminazione, FK…) si annullano con Annulla del menu Modifica. La modalità focus (voci Focus tabella e Focus lookup del menu contestuale) mette in evidenza una tabella con le sue relazioni; Esc o Esci dal focus la chiude.
C6. Ruoli delle tabelle
Dal menu contestuale, Ruolo classifica la tabella. Il ruolo si vede come etichetta e come colore dell’intestazione (nello screenshot MST, master):
| Ruolo | Etichetta |
|---|---|
| Master | (predefinito, MST) |
| Lookup | ◆ Lookup |
| ReadOnly | ■ ReadOnly |
| WriteThrough | ✎ WriteThrough |
| Transaction | ▶ Transaction |
| Operational | ⚙ Operational |
| Audit | ☰ Audit |
| Financial | ¤ Financial |
C7. Grafico semantico
Il capitolo completo sulla configurazione semantica è nella parte G. Il pulsante ⇄ della barra laterale passa dallo schema fisico al grafico semantico: una vista a nodi che descrive i significati delle tabelle (lookup, filtri, campi calcolati) per l’AI e per la generazione di codice, senza alcun effetto sul DDL. Passandoci sopra con il mouse un suggerimento riporta il dettaglio completo del nodo. Nella vista semantica compare il pulsante ⚙ Config. globale per vincoli e chiavi personalizzate non legati a una tabella.
| Voce (menu contestuale) | Funzione |
|---|---|
| Configura semantica… | Configuratore completo della tabella (anche doppio clic su un nodo) |
| Collega Lookup semantico… | Disegna un lookup tra due campi precisi (nessuna FK, nessun DDL) |
| Importa Lookup da FK esistenti… | Converte le FK in lookup semantici |
| Configurazione semantica globale… | Vincoli e chiavi personalizzate dell’intero schema |
| Configura generazione Vue… | Opzioni per la generazione di codice Vue |
Dal menu Schema Designer: Genera REST, Genera prompt AI (menu Query, Ctrl+Shift+J) ed Esporta pacchetto semantico (server)…. Per leggere lo schema come fatti e dimensioni e generare query con le JOIN giuste c’è la voce Analisi star schema (fatti e dimensioni)…, descritta nella parte H.
C8. Generare il DDL
- Premi F7 (o Genera DDL nel menu Schema Designer, o clic destro sul canvas).
- Nella finestra Export DDL scegli il Dialetto, la Versione del server e, se serve, Includi DROP statements.
- Lo script compare nel tab Schema Designer dell’Editor, con l’intestazione di commento. Puoi leggerlo, modificarlo, copiarlo o eseguirlo con Script (F6): i blocchi dei trigger vengono riconosciuti e non spezzati.
Lo script comprende tabelle, chiavi esterne e indici, e ove previsto commenti, trigger, viste e procedure memorizzate. Il tipo di dato e l’auto-incremento si adattano al dialetto scelto. La voce Esporta dialetto del menu Schema Designer serve per l’esportazione nel dialetto scelto.
C9. Salvare, esportare, gestire i tab
| Voce (menu Schema Designer) | Effetto |
|---|---|
| Salva schema / Carica schema | File JSON (UTF-8) con tabelle, colonne, FK e posizioni, più il modello a stella se c’è (H2). Se il file non è valido lo schema corrente resta com’è. |
| Analisi star schema (fatti e dimensioni)… | Apre la finestra del modello a stella: fatti, dimensioni, grain, misure e query con le JOIN generate (parte H) |
| Esporta PNG / Esporta SVG | Immagine del diagramma |
| Svuota schema | Cancella tutto il canvas (si può annullare) |
| Nuovo tab schema (Ctrl+Alt+N), Chiudi (Ctrl+Alt+W), Rinomina | Più schemi aperti insieme, ognuno nel proprio tab |
| Aggiungi tabella / FK, Elimina selezione, Auto layout | Come da barra laterale e menu contestuale |
| Zoom avanti / indietro / adatta | Ctrl+=, Ctrl+-, Ctrl+Shift+0 |
G1. A che cosa serve la configurazione semantica
La configurazione semantica insegna all’intelligenza artificiale il vocabolario del tuo database. Serve per il Text-to-SQL: l’operatore scrive una domanda in italiano ("quante occupazioni permanenti a Riccione nel 2025?") e l’AI la trasforma in una query SQL. Senza contesto l’AI vedrebbe nomi di tabelle e campi spesso criptici (SBEREGISTRO2026, IDUBICAZIONE); con la configurazione sa che cosa significano, come si collegano, quali filtri sono obbligatori e come si chiamano le cose nel linguaggio dell’azienda.
Il flusso completo è questo:
- Domanda in linguaggio naturale.
- Rilevamento delle tabelle: il programma sceglie le tabelle configurate il cui nome o le cui keyword compaiono nella domanda.
- Prompt JSON: schema, alias, lookup, filtri, vincoli e valori dei parametri vengono assemblati in un unico documento strutturato.
- Invio all’AI (Anthropic, OpenAI o Ollama, a seconda del profilo attivo) e ricezione dell’SQL.
- Controllo di sicurezza: ammessa solo una query di lettura (G12).
- Esecuzione di verifica con un limite di righe, e possibilità di salvare la coppia domanda/SQL come esempio verificato.
G2. Dove si apre
- Configurazione di una tabella: clic sull’icona ⚙ nell’intestazione della tabella, oppure voce Configura semantica… del menu contestuale (anche con doppio clic su un nodo del grafico semantico). Il titolo della finestra riporta il nome della tabella: Configurazione semantica — SBEREGISTRO2026.
- Configurazione globale: voce Configurazione semantica globale… del menu contestuale, o il pulsante ⚙ Config. globale nella vista semantica (C7).
Entrambe le finestre hanno Salva e Annulla: finché non premi Salva non cambia nulla.
Le impostazioni si dividono su due livelli. Quelle per tabella (G3–G9) descrivono una singola tabella; quelle globali (G10) valgono per ogni prompt generato.
G3. Scheda Generale
- Schede: Generale, Alias campi, Lookup, Calcolati, Keyword filter, Filtri fissi, Esempi
- Alias tabella
- Descrizione
- Ruoli ammessi [RBAC]
- Keyword identificazione tabella
- Campi attivi
- + Tutti / − Nessuno
- Salva / Annulla
Alias tabella
Il nome con cui l’AI deve chiamare la tabella nelle query. Può contenere segnaposto tra doppie parentesi quadre, come nello screenshot: [[COMUNE]]EREGISTRO[[ANNO]]. È il caso tipico di tabelle che esistono in più copie (una per comune o per anno): il segnaposto viene sostituito con il valore della custom key corrispondente (G10). Il programma non li risolve nel prompt: restano letterali e l’AI li sostituisce seguendo la mappa dei parametri.
Descrizione
Testo libero, facoltativo, su che cosa rappresenta la tabella ("registro dettagliato delle varie occupazioni e insegne permanenti e temporanee di ogni contribuente nell’anno contributivo"). È contesto per l’AI, utile soprattutto quando il nome fisico non dice nulla.
Ruoli ammessi a vedere questa tabella [RBAC]
Ruoli separati da virgola. Vuoto significa nessuna restrizione. Un ruolo che non è nell’elenco ammesso non vede nemmeno l’esistenza della tabella. I ruoli suggeriti vengono dalla configurazione globale.
Keyword identificazione tabella
Una espressione per riga: le parole che, se compaiono nella domanda, fanno includere la tabella nel prompt. Sintassi:
| Simbolo | Significato | Esempio |
|---|---|---|
+ | OR | insegne+insegna: compare "insegne" oppure "insegna" |
& | AND | insegne&insegna: compaiono entrambe |
- | NOT | -occupazione: non compare "occupazione" |
( ) | Raggruppamento | -(a+b+c): nessuna delle tre compare |
spazio, virgola, ; | AND implicito tra due termini | a b equivale a a&b |
La precedenza è: NOT, poi AND, poi OR. Ogni termine vale come parola o frase intera nel testo della domanda: cup non scatta dentro una parola più lunga non correlata. Un’espressione vuota o malformata non fa mai scattare nulla, senza errori.
insegne+oggetti+occupazioni+permanenti,icp: poiché la virgola è un AND, che ha la precedenza sull’OR, si legge insegne OR oggetti OR occupazioni OR (permanenti AND icp). Se volevi "una tra le prime quattro, e icp", scrivi (insegne+oggetti+occupazioni+permanenti)&icp.Oltre alle keyword, la tabella viene riconosciuta anche quando il suo nome reale compare nella domanda.
Campi attivi
L’elenco dei campi della tabella con una casella ciascuno. Solo i campi spuntati sono mostrati all’AI (query_fields). Togli la spunta ai campi tecnici, ai dati sensibili e a tutto ciò che sarebbe rumore: meno campi significa query più precise. + Tutti e − Nessuno selezionano o deselezionano tutto in un colpo.
G4. Alias campi
Una riga per campo, con quattro colonne:
| Colonna | Significato |
|---|---|
| Campo | Il campo fisico. Se ne cambi il nome per errore e non corrisponde più a un campo reale, la riga viene ignorata |
| Alias | Sinonimi di dominio separati da virgola. Esempio: il campo DESCRIZIONE della tabella delle vie può avere alias ubicazione, via, indirizzo. Ogni sinonimo porta all’stesso campo fisico. |
| Identif. | SI marca il campo come "il nome umano" della riga (per esempio RAGIONE_SOCIALE per gli utenti, DESCRIZIONE per i comuni). Serve a rispondere a "mostrami gli utenti" senza dover dire quale campo elencare. |
| Ruoli | Ruoli ammessi a vedere il campo, separati da virgola; vuoto = nessuna restrizione (solo anteprima nel Designer) |
- In ogni tabella può esserci un solo identificatore umano. Se ne marchi più di uno, il programma tiene il primo, deseleziona gli altri e te lo segnala al salvataggio.
- Un alias non è un lookup: l’alias riconduce parole diverse allo stesso campo; il lookup (G5) risolve un codice attraverso un’altra tabella.
G5. Lookup
Un lookup spiega all’AI come passare da un codice alla sua descrizione: per esempio, da IDCOMUNE al nome del comune nella tabella dei comuni. Colonne:
| Colonna | Significato |
|---|---|
| Campo | Il campo di questa tabella (chiave verso l’altra) |
| Tabella rif. | La tabella da collegare. Può contenere segnaposto come [[COMUNE]] |
| Campo rif. | Il campo corrispondente nella tabella collegata |
| Campo visualiz. | Il campo da mostrare (il nome, la descrizione) |
| Cardinalità | 1:1, 1:N, N:1 (facoltativa). Il caso più comune è N:1: molte righe puntano alla stessa riga di riferimento |
| Join | INNER, LEFT, RIGHT (facoltativo) |
Lasciando vuote Cardinalità e Join non dai all’AI nessuna garanzia inventata: restano non specificate. Valori non riconosciuti sono ignorati e il programma te lo comunica dopo il salvataggio.
Il pulsante Importa da FK crea i lookup partendo dalle chiavi esterne già presenti nello schema. A fine importazione ti dice quanti ne ha importati e quanti ha saltato (duplicati e chiavi esterne composte, che non possono diventare un lookup semplice).
G6. Calcolati
Campi che non esistono nella tabella ma che l’AI può usare: ogni riga ha un nome e una espressione SQL valida per il dialetto di destinazione, riferita a campi reali. Esempio:
Nome: TIPO_SOGGETTO Espressione: CASE WHEN NGIURIDICA=0 THEN 'FISICA' ELSE 'DITTA' END
Con un doppio clic sulla cella dell’espressione si apre un editor a più righe con colorazione SQL e il pulsante Formatta. Il programma non verifica l’espressione: se cambi il nome di un campo, aggiornala a mano.
G7. Keyword filter
Un filtro che scatta solo se la domanda contiene una certa parola. Due colonne: la Keyword (stessa sintassi di G3: & + - ( )) e il Testo, cioè la condizione WHERE. Nel testo puoi usare il segnaposto {keyword} con le graffe singole, che viene riempito a runtime con il valore preso dalla domanda. Esempio:
Keyword: inciso
Testo: [[COMUNE]]REGISTRO[[ANNO]].DESCRIZIONE_PUBBLICITA LIKE '%{inciso}%'
{inciso} si risolve al volo dal testo della domanda; [[COMUNE]] si risolve dalla mappa dei parametri della configurazione globale. Sono due meccanismi diversi, tenuti separati di proposito.I filtri scattati compaiono nel prompt come matched_filters. Al salvataggio, se la keyword di un filtro non condivide nessuna parola con le keyword della tabella (scheda Generale), il programma ti avvisa: un keyword filter scatta solo se la tabella è già stata inclusa nel prompt, e questo dipende dalle keyword della tabella, non da quella del filtro. Se nessuna domanda sensata include la tabella, il filtro non scatterà mai.
G8. Filtri fissi
Una condizione WHERE per riga, applicata sempre quando la tabella è nel prompt, qualunque cosa chieda l’operatore. Servono per le regole che non devono mai dipendere dalla domanda:
- cancellazione logica:
DELETED=0; - record attivi:
ATTIVO=1; - isolamento tra clienti o comuni (multi-tenant);
- record di sistema da nascondere.
L’espressione deve essere completa e valida da sola: qui non c’è nessun segnaposto {…} a runtime.
G9. Esempi
Coppie domanda → SQL scritte da te per questa tabella. Sono l’intervento che migliora di più la qualità dell’SQL generato, soprattutto quando un join o un filtro non si deducono dal solo schema (una CASE particolare, un self-join, il modo "canonico" di rispondere a una domanda tipica). Tre colonne:
| Colonna | Contenuto |
|---|---|
| Domanda | La domanda tipica, come la scriverebbe un operatore |
| SQL | La query giusta |
| Test regressione | SI (predefinito): l’esempio entra nella suite di regressione (G13). NO: serve solo da modello per l’AI. Usa NO per esempi "di stile" che un confronto automatico giudicherebbe diversi anche se corretti. |
Il programma non controlla né esegue questi esempi: se cambiano i nomi reali di campi o tabelle vanno aggiornati a mano. Gli esempi scritti qui non entrano nella cache delle risposte, perché nessuno li ha mai fatti girare davvero su un database (G13).
G10. Configurazione semantica globale
- Constraint generali
- Custom key: Parametro, Key, Valore, Default
- Colonna Default
- + Riga aggiunge una riga alla griglia sopra
- Alias di aggregazione
- Precompila standard
- Ruoli configurabili
- Suite di regressione
- Telemetria
- Salva / Annulla
Constraint generali
Regole in linguaggio naturale, una per riga, valide per ogni prompt generato. Sono le istruzioni che dai a un collega che scrive query per te: convenzioni di naming, cose da non fare. L’esempio dello screenshot impone di usare sempre l’alias dato a una tabella in tutti i riferimenti (SELECT, WHERE, JOIN, subquery), alias univoci anche nelle subquery (EP, EP2, EP3) e alias di colonna in maiuscolo, con underscore, di al massimo 30 caratteri.
Custom key
Una tabella che risolve i segnaposto [[PARAMETRO]] usati negli alias e nei filtri. Quattro colonne:
| Colonna | Significato | Esempio |
|---|---|---|
| Parametro | Il nome del segnaposto (senza le parentesi) | COMUNE |
| Key | L’etichetta leggibile che l’operatore usa nella domanda. Accetta la stessa sintassi delle keyword, quindi sinonimi come riccione+rn | riccione |
| Valore | Il testo che prende il posto di [[PARAMETRO]] nelle query | SB |
| Default | SI indica il valore predefinito di quel Parametro | SI |
Nello screenshot: il parametro COMUNE ha due varianti, riccione (valore SB, predefinita) e gatteo (valore H231); il parametro ANNO vale YEAR(TODAY()). Quindi "occupazioni a Riccione" trasforma [[COMUNE]]EREGISTRO[[ANNO]] in una tabella con il prefisso di Riccione e l’anno corrente.
- Se la domanda non nomina nessun comune, vale la variante con Default = SI.
- Se la domanda ne nomina più di uno (per esempio Riccione e Gatteo), il prompt riporta tutti i valori coinvolti e dice esplicitamente all’AI di non scegliere in silenzio solo il predefinito.
Valori dinamici
Nella colonna Valore puoi scrivere un valore fisso oppure un’espressione di data, calcolata nel momento in cui generi il prompt (non quando salvi: il valore non resta "congelato"). Le espressioni riconosciute sono nell’elenco a discesa, e puoi anche digitare liberamente:
| Espressione | Significato |
|---|---|
YEAR(TODAY()) · YEAR(TODAY())-1 · YEAR(TODAY())+1 | Anno corrente, precedente, successivo |
MONTH(TODAY()) · DAY(TODAY()) · QUARTER(TODAY()) · WEEKDAY(TODAY()) | Mese, giorno, trimestre, giorno della settimana |
TODAY() · YESTERDAY() · TOMORROW() | Oggi, ieri, domani (gg/mm/aaaa) |
FIRST_DAY_OF_MONTH() · LAST_DAY_OF_MONTH() | Primo e ultimo giorno del mese |
FIRST_DAY_OF_YEAR() · LAST_DAY_OF_YEAR() | Primo e ultimo giorno dell’anno |
CURRENT_TIME() · CURRENT_TIMESTAMP() | Ora e data-ora correnti |
Un valore non riconosciuto resta letterale (come SB o H231).
Alias di aggregazione
Un piccolo vocabolario che collega i termini del linguaggio naturale alla funzione SQL: la colonna Parola ("totale", "ammontare", "gettito") e la colonna Funzione, scelta da elenco chiuso: SUM, COUNT, AVG, MIN, MAX (o vuoto). Senza di esso l’AI deve indovinare che "qual è il totale degli importi" significa SUM(IMPORTO); con il vocabolario aziendale ("gettito" → SUM) non c’è dubbio. Il pulsante Precompila standard aggiunge in un clic il vocabolario italiano più comune (totale e somma → SUM; conteggio e numero → COUNT; media → AVG; minimo; massimo), saltando le parole già presenti, quindi si può premere più volte senza duplicare. È un punto di partenza: ogni riga resta modificabile e cancellabile. Questo vocabolario è sempre incluso nel prompt, indipendentemente dalla domanda.
Ruoli configurabili
Un ruolo per riga (per esempio amministratore, operatore, pubblico). È l’elenco dei ruoli suggeriti nelle schede Generale e Alias campi: non è un vincolo, un ruolo scritto a mano e non presente qui resta valido.
Suite di regressione e Telemetria
I due pulsanti in basso a sinistra sono azioni a parte: non fanno parte di Salva e Annulla. Suite di regressione lavora sullo schema così com’è in memoria, senza bisogno di salvare prima. Telemetria non dipende dallo schema aperto. Vedi G13.
G11. Provare la configurazione: Genera prompt AI
Dal menu Query → Genera prompt AI (Ctrl+Shift+J; serve uno schema aperto nel Designer) si apre la finestra con cui verifichi se la configurazione funziona davvero: vedi il prompt esatto, lo mandi all’AI, controlli l’SQL che torna e lo trasformi in un esempio.
- Domanda (question)
- Mantieni il contesto della domanda precedente
- Anteprima come ruolo
- Dialetto
- Versione
- AI attiva: profilo, provider e modello
- ⚙: apre la Configurazione AI
- Genera prompt
- Copia
- Invia a AI
- Inserisci nell’editor
- Testa SQL
- ✓ Verifica e salva come esempio
- Passi: registro dell’invio
- Anteprima JSON / risposta AI
- Esito e righe dell’esecuzione di verifica
- Chiudi
Campi in alto
| Campo | Significato |
|---|---|
| Domanda (question) | La domanda come la scriverebbe un operatore ("quante occupazioni permanenti a Riccione nel 2025?"). |
| Mantieni il contesto della domanda precedente | Spuntalo per le domande che continuano la precedente (ora filtrale anche per il 2025): il prompt porta con sé domanda e SQL precedenti. Lascialo spento per una domanda nuova, per non trascinare un contesto che non c’entra. |
| Anteprima come ruolo | Simula che cosa vedrebbe un certo ruolo (tabelle e campi riservati vengono tolti dal prompt). La dicitura sulla finestra lo dice chiaramente: solo verifica, non è un controllo di sicurezza reale. Predefinito: (nessuno — mostra tutto). |
| Dialetto, Versione | Il dialetto SQL della query richiesta (nello screenshot Firebird) e la versione del server (Latest (default) = solo il dialetto). Una versione precisa, per esempio "Firebird 3.0", dà all’AI un’indicazione in più (FIREBIRD 3.0+). |
| AI attiva | Il profilo in uso, con provider e modello (Predefinito (Ollama · gpt-oss:20b)). Il pulsante ⚙ apre la Configurazione AI (G17) e al ritorno l’etichetta si aggiorna da sola, senza dover riaprire la finestra. Senza profilo compare un avviso arancione che rimanda alla configurazione. |
I pulsanti, e quando si attivano
| Pulsante | Che cosa fa | Attivo quando |
|---|---|---|
| Genera prompt | Costruisce il prompt JSON dalla domanda e dalla configurazione e lo mostra in Anteprima JSON / risposta AI. È il modo più veloce per capire perché una query viene sbagliata: guarda quali tabelle, filtri e valori di parametro sono entrati. | Sempre. Un nuovo prompt invalida la risposta precedente: Inserisci e Verifica si spengono |
| Copia | Copia il JSON negli appunti, per incollarlo in un’AI esterna (per esempio in un browser) senza usare un profilo configurato. | Dopo un prompt generato correttamente |
| Invia a AI | Manda il prompt al provider del profilo attivo. Il registro Passi mostra gli eventi ("Connessione a Ollama…", "Invio richiesta…"). Quando la risposta arriva, l’SQL compare nell’anteprima, ripulito dall’eventuale blocco di codice Markdown, ed è controllato e provato (vedi sotto). | Dopo un prompt generato correttamente |
| Inserisci nell’editor | Porta l’SQL in un tab dell’Editor. Resta disponibile anche se la verifica automatica fallisce, così puoi sempre correggere a mano. | Quando nell’anteprima c’è un SQL |
| Testa SQL | Prova l’SQL che c’è nell’anteprima con gli stessi controlli di sicurezza e la stessa esecuzione di verifica, senza chiamare l’AI. Serve quando l’SQL viene da fuori: hai copiato il prompt in un browser, hai chiesto lì la query e hai incollato la risposta nell’anteprima. Non c’è il ciclo di correzione automatica: se fallisce vedi il motivo e decidi tu se correggere e riprovare oppure passare a Invia a AI. | Sempre (con un SQL nell’anteprima; altrimenti avvisa "Nessun SQL da testare") |
| ✓ Verifica e salva come esempio | Salva la coppia domanda/SQL come esempio verificato (vedi sotto). | Solo dopo una verifica riuscita, da Invia a AI o da Testa SQL, o quando la risposta arriva dalla cache |
| Chiudi | Chiude la finestra senza altre azioni. | Sempre |
Che cosa succede dopo "Invia a AI"
- La domanda può essere servita dalla cache (Trovato in cache — verifica in corso…): in quel caso non c’è nessuna chiamata all’AI (G13).
- Altrimenti l’SQL ricevuto passa dal controllo di sicurezza (solo letture, G12). Se è rifiutato, lo stato mostra
✗ Rifiutata dai controlli di sicurezza: motivo. - Se è ammesso, viene eseguito in verifica sulla connessione corrente, con un limite di righe. In caso di errore compare
✗ Esecuzione fallita: messaggioe l’errore viene rimandato all’AI per un nuovo tentativo (correzione automatica). - Se l’esecuzione riesce, nel riquadro in basso compaiono le prime righe restituite: non è un pannello risultati completo, ma una conferma visiva che la query gira davvero e produce dati sensati.
- Se la comunicazione con l’AI non riesce, lo stato dice
✗ Errore di comunicazione con l’AI — vedi soprae i dettagli sono in Passi.
L’SQL nell’anteprima si può correggere a mano prima di inserirlo nell’editor o di rilanciare Testa SQL: ciò che resta nell’anteprima è esattamente ciò che viene provato e, se valido, salvato.
Verifica e salva come esempio
Il pulsante apre una piccola finestra con quattro scelte:
- Tabella: la tabella "proprietaria" dell’esempio. Il programma propone quella riconosciuta dalla domanda; se non è riuscito a riconoscerne nessuna lo dice con un avviso, e devi sceglierla tu (una domanda con un JOIN riguarda più tabelle, ma l’esempio si salva su una sola).
- Domanda e SQL, modificabili prima di salvare.
- La casella Test regressione: se attiva, l’esempio entra nella Suite di regressione (G9, G13).
Con Salva l’esempio finisce nella scheda Esempi della tabella scelta, e un messaggio indica il numero di esempi della tabella. È un esempio verificato: ha girato davvero, quindi può servire anche come risposta in cache.
Cosa contiene il prompt
| Sezione | Origine |
|---|---|
tags, question | Dialetto e versione; la domanda |
constraints | Constraint generali (G10) |
tables | Schema reale delle tabelle incluse (campi, chiavi primarie) più alias e descrizione |
custom_semantic / custom_semantic_matches | Custom key e, per ognuna, se la domanda la nomina |
query_fields | I campi attivi (G3) |
field_aliases | Sinonimi dei campi (G4), identificatore umano |
lookups | Collegamenti tra tabelle (G5) |
calculated_fields | Campi calcolati (G6) |
matched_filters | Keyword filter scattati (G7) |
always_filters | Filtri fissi (G8) |
examples | Esempi (G9) |
aggregate_aliases | Vocabolario di aggregazione (G10) |
previous_turn | Domanda e SQL precedenti, per le conversazioni (vedi sotto) |
- Conversazione a più turni: se la domanda successiva fa riferimento alla precedente ("ora filtrale anche per il 2025"), il prompt porta con sé domanda e SQL precedenti, con l’istruzione di usarli solo se il riferimento è implicito, senza forzare un legame che non c’è.
- Tentativi automatici: se l’SQL viene rifiutato dal controllo di sicurezza o fallisce in verifica, l’errore viene rimandato all’AI per un nuovo tentativo (il motivo dell’ultimo errore è mostrato alla fine).
- Guardrail: se manca qualcosa di essenziale (tabella non configurata, alias vuoto, campo non presente nella tabella reale) il programma non genera in silenzio un prompt parziale: segnala l’errore.
G12. Sicurezza
- Solo letture: l’SQL prodotto dall’AI passa da un filtro rigido. È ammessa una sola
SELECT(anche conWITH/CTE); tutto ciò che potrebbe modificare dati o struttura, o anche solo sembrare più istruzioni, viene respinto prima dell’esecuzione. È ammesso al più un;finale. Il filtro è volutamente prudente: in caso di dubbio rifiuta, anche a costo di qualche falso positivo su una query insolita ma legittima. - Il filtro non verifica che la query sia corretta, solo che sia di sola lettura: la correttezza si vede dall’esecuzione di verifica.
- Ruoli: come detto in G3, l’applicazione vera è nel server. Il Designer mostra solo un’anteprima per il ruolo scelto.
- Pacchetto per il server (G18): Esporta pacchetto semantico (server)… (menu Schema Designer) salva l’intera configurazione (tabelle, vincoli globali, custom key) in un file JSON portabile, con la struttura reale (campi, chiavi primarie) necessaria a costruire il prompt. Un componente server può così rigenerare lo stesso prompt a ogni richiesta, senza il Designer. I valori dinamici (
YEAR(TODAY())) restano espressioni nel pacchetto e vengono calcolati dal server a ogni richiesta.
G13. Verificare nel tempo
Suite di regressione
Riesegue tutti gli esempi con Test regressione = SI: la stessa domanda viene rimandata all’AI (lo stesso profilo e provider di Genera prompt AI), una alla volta, e l’SQL prodotto è confrontato con quello atteso. Il confronto è testuale (spazi e maiuscole normalizzati, ; finale ignorato), non semantico: due query equivalenti scritte in modo diverso (JOIN contro subquery) risultano diverse. Un esito "diverso" non significa necessariamente "sbagliato": è un radar che ti dice dove guardare, non un certificatore. Rilancia la suite dopo aver cambiato modello AI, constraint o configurazione.
Cache delle risposte
Gli esempi creati con Verifica e salva come esempio (già passati da un’esecuzione reale) possono evitare del tutto la chiamata all’AI: se la domanda coincide, il programma risponde con l’SQL verificato ("Trovato in cache — verifica in corso, nessuna chiamata AI").
- Corrispondenza esatta: domanda normalizzata identica.
- Corrispondenza approssimata: solo con somiglianza molto alta (0,90) e solo se i numeri nelle due domande sono identici: "fatture 2024" e "fatture 2023" sono quasi uguali come testo ma diverse come significato, e non vengono confuse.
- Se dopo la verifica cambi la configurazione (un lookup, un filtro…), l’esempio non viene scartato ma è considerato da rivalidare: il programma chiede una risposta nuova all’AI invece di fidarsi di una vecchia.
- Gli esempi scritti a mano nella scheda Esempi non entrano mai in cache.
Telemetria
Il pulsante Telemetria apre un riepilogo aggregato degli eventi registrati in uso reale e l’elenco di quelli più recenti: serve a rispondere a "dove sto perdendo tempo e query?" senza aprire a mano il file di log. Non è un cruscotto di analisi: è la vista minima per orientarsi.
G14. Come cominciare: un percorso consigliato
- Configurazione globale: scrivi i constraint generali, definisci le custom key (comune, anno…), premi Precompila standard per gli alias di aggregazione e aggiungi i termini aziendali.
- Per le tabelle principali (non tutte insieme): alias, descrizione, keyword e campi attivi. Togli i campi inutili.
- Premi Importa da FK nella scheda Lookup e completa cardinalità e join dove sono noti.
- Aggiungi i filtri fissi obbligatori (cancellazione logica, tenant) e i keyword filter ricorrenti.
- Scrivi 2–3 esempi per i pattern difficili.
- Prova con Genera prompt AI su domande vere: guarda l’anteprima JSON e il risultato; con Verifica e salva come esempio le risposte giuste diventano esempi verificati.
- Lancia la Suite di regressione e rifalla a ogni modifica importante.
G15. Problemi comuni
| Sintomo | Causa e rimedio |
|---|---|
| La tabella giusta non entra nel prompt | Nessuna keyword (né il nome reale) compare nella domanda. Aggiungi sinonimi con + e controlla di non aver usato la virgola o & dove volevi un OR (G3). |
| Il keyword filter non scatta | La tabella non è stata inclusa, oppure la keyword del filtro non compare nella domanda. Controlla il messaggio al salvataggio (G7). |
| L’AI usa il comune sbagliato | Manca la riga con Default = SI per quel parametro, oppure la Key non coincide con la parola della domanda (aggiungi sinonimi con +). |
| L’AI inventa o ignora campi | Troppi campi attivi: disattiva i campi inutili; aggiungi alias e un identificatore umano; scrivi un esempio. |
| "Nessun profilo AI attivo" | File → Configurazione AI: crea un profilo e premi Attiva (G11). |
| La query è respinta ("sola lettura") | L’AI ha prodotto più istruzioni o qualcosa che modifica dati. Riprova o rinforza i constraint generali (G12). |
| La suite dice "diverso" ma la query è giusta | Il confronto è testuale: verifica a mano. Se l’esempio è solo di stile, imposta Test regressione = NO (G9). |
| Un ruolo vede ancora una tabella riservata | Nel Designer l’enforcement non c’è, è solo un’anteprima: la restrizione vale nel componente server (G3). |
G16. Il grafico semantico
Il pulsante ⇄ nella barra laterale del Designer alterna lo schema fisico e il grafico semantico: una vista panoramica di come hai configurato l’AI. In questa vista l’Editor sotto il canvas si nasconde, per avere più spazio.
- Tab dello schema (qui
AI_SEMANTIC_Schema1; l’asterisco indica modifiche non salvate) - ⚙ Config. globale (G10)
- ⇄ per tornare allo schema fisico
- Nodo di una tabella configurata (selezionato: bordo arancione)
- Contatori filtri e campi calcolati
- Relazione di lookup con cardinalità e join
- Minimappa
- Nodo senza keyword: la tabella non verrà mai riconosciuta dal testo di una domanda
Come si legge un nodo
| Parte | Contenuto |
|---|---|
| Intestazione | Alias della tabella in grassetto (per esempio [[COMUNE]]EREGISTRO[[ANNO]]); sotto, in piccolo, il nome fisico se è diverso dall’alias (SBEREGISTRO2026). Una tabella senza alias mostra il nome fisico. |
| Prima riga | La prima keyword di identificazione, oppure — nessuna keyword. |
| Chip N filtri | Quanti keyword filter ha la tabella (G7) |
| Chip N calc. | Quanti campi calcolati (G6) |
| Suggerimento (passando il mouse) | Identificatore umano, filtri, keyword, campi calcolati e lookup della tabella |
Compaiono solo le tabelle che hanno una configurazione semantica: per questo, nel grafico, un nodo "mancante" significa una tabella non ancora configurata. Le curve sono i lookup (G5): partono dalla tabella "molti" verso quella "uno", con una freccia all’arrivo e, a metà, l’etichetta cardinalità · join (per esempio 1:N · LEFT). Un doppio clic su un nodo apre la configurazione della tabella; il menu contestuale offre le voci elencate in C7.
L’export SVG nella vista semantica propone il nome grafico_semantico.svg.
G17. Configurazione AI: i profili
Tutte le funzioni AI usano un profilo unico, che si imposta da File → Configurazione AI (icona ⚙). Il profilo attivo vale per Genera prompt AI, Genera schema con AI, Raffina schema, l’assistente nell’albero e il Query Builder, e per la Suite di regressione. Non c’è nessun menu Provider o chiave da risistemare finestra per finestra: cambi AI per tutti con un solo clic su ● Attiva.
- Profili configurati (● = attivo)
- Provider: Anthropic, OpenAI, Ollama
- Modello
- Endpoint
- Parametri Ollama (solo per Ollama)
- Finestra di contesto (num_ctx) e token massimi (num_predict)
- Timeout in ms
- Salva profilo
- ● Attiva
- Chiudi
| Campo | Significato |
|---|---|
| Profili configurati | L’elenco dei profili con nome (per esempio "Ollama locale", "Claude cloud"). + Nuovo ne crea uno chiedendo il nome; Elimina chiede conferma. Il profilo attivo ha il pallino ●. |
| Provider | Anthropic (Claude), OpenAI, Ollama (modello locale, sul tuo computer o su un server tuo) |
| Modello | Il nome del modello (nello screenshot gpt-oss:20b, un modello Ollama; per Claude per esempio claude-sonnet-4-6) |
| Chiave API | Per Anthropic e OpenAI. Non serve per Ollama. |
| Endpoint | Indirizzo del servizio. Per Ollama in locale: http://localhost:11434 |
| Finestra di contesto (num_ctx) | Quanti token il modello può leggere in una richiesta: nello screenshot 16384. Il prompt cresce con il numero di tabelle e di campi attivi: se il modello "perde" parti dello schema, alza questo valore (compatibilmente con la memoria disponibile) |
| Token massimi risposta (num_predict) | Lunghezza massima dell’SQL restituito (nello screenshot 8192) |
| Thread CPU | 0 = automatico |
| Timeout (ms) | Tempo massimo di attesa della risposta (nello screenshot 180000, tre minuti). Vale per Ollama, dove un modello locale può essere lento; per i servizi cloud il programma usa un limite proprio, più breve |
Passi
- Apri File → Configurazione AI.
- Scegli + Nuovo (o modifica "Predefinito"), dai un nome, scegli provider, modello e, se serve, chiave ed endpoint.
- Premi Salva profilo, poi ● Attiva: il programma conferma che quel profilo sarà usato da ogni finestra che chiama l’AI.
- In basso trovi AI attiva: nome del profilo. Con più profili ne attivi uno alla volta.
%APPDATA%\PGSOFT\plyxsql).G18. Esportare il pacchetto semantico
Il pacchetto semantico è un file JSON che contiene tutta la configurazione (tabelle configurate, constraint globali, custom key, ruoli, alias di aggregazione) più la struttura reale dello schema (campi e chiavi primarie). Un componente server lo legge per rigenerare lo stesso prompt del Designer a ogni nuova domanda, senza il Designer in mezzo.
- Dal menu Schema Designer scegli Esporta pacchetto semantico (server)….
- Se nessuna tabella ha una configurazione, un messaggio ti invita a configurarne almeno una (clic destro sulla tabella → ⚙ Configura semantica…) prima di esportare.
- Nella finestra Esporta pacchetto semantico scegli la cartella. Il nome proposto è NomeSchema_semantic_package.json (nell’esempio
DEST_semantic_package.json); il tipo file è JSON. - Alla fine un messaggio riporta quante tabelle configurate sono state esportate.
- Il file è scritto in UTF-8 senza BOM, per evitare problemi con i parser JSON più rigorosi.
- I valori dinamici (
YEAR(TODAY())) restano espressioni: li calcola il server a ogni richiesta (G12). - Il pacchetto non contiene i dati del database, né le chiavi AI.
- Ri-esporta il pacchetto ogni volta che cambi la configurazione: il server lavora su una copia.
H1. A che cosa serve il modello a stella
Un modello a stella divide i dati in due tipi di tabelle. I fatti contengono ciò che si misura (ricavi, quantità, rimborsi, giacenze), con una riga per evento. Le dimensioni descrivono il contesto con cui lo si legge: data, prodotto, cliente, negozio, campagna. Il fatto punta alle dimensioni con chiavi surrogate, e le dimensioni sono denormalizzate: categoria e brand stanno nella stessa riga di DIM_PRODUCT, senza tabelle intermedie.
In PlyxSQL il modello a stella è un livello descrittivo sopra le tabelle del Designer, come la configurazione semantica (parte G): non cambia il DDL né i dati. Serve a tre cose:
- mostra l’albero Fatti / Dimensioni: quali tabelle sono fatti, con il loro grain, le misure e i ruoli delle dimensioni;
- genera l’SQL con le JOIN giuste: scegli attributi e misure dall’albero e il programma scrive la query;
- controlla le aggregazioni: una giacenza non si somma nel tempo, un prezzo non si somma mai, due fatti non si uniscono con una JOIN.
Lo schema di esempio di questa parte
Tutti gli esempi usano lo script plyxsql_star_schema_extended_firebird3_v4.sql: un piccolo negozio di elettronica con 5 dimensioni e 6 fatti, 17 chiavi esterne e 5 viste di controllo.
| Tabella | Ruolo | Righe | Contenuto |
|---|---|---|---|
DIM_DATE | dimensione data | 365 | ogni giorno del 2026; DATE_KEY è la data in forma AAAAMMGG |
DIM_CUSTOMER | dimensione | 20 | clienti con città, regione, paese e segmento |
DIM_PRODUCT | dimensione | 10 | prodotti con categoria (5) e brand |
DIM_STORE | dimensione | 5 | negozi con canale: Retail, E-commerce, B2B |
DIM_CAMPAIGN | dimensione | 5 | campagne con tipo, canale, date di inizio e fine |
FACT_SALES | fact | 1.607 | una riga per riga d’ordine: quantità, prezzo, sconto, ricavi, costi, margine |
FACT_ORDER_HEADER | fact | 786 | una riga per ordine: canale, pagamento, stato (nessuna misura) |
FACT_RETURNS | fact | 137 | una riga per reso: quantità, rimborso, motivo, esito |
FACT_INVENTORY_SNAPSHOT | fact | 600 | giacenze a fine mese per prodotto e negozio (10 × 5 × 12) |
FACT_BUDGET | fact | 300 | budget e consuntivo per mese, categoria e negozio (12 × 5 × 5) |
FACT_CAMPAIGN_PERFORMANCE | fact | 122 | impression, click, conversioni, spesa e ricavi per campagna e giorno |
Le viste dello script (V_SALES_ANALYSIS, V_RETURNS_ANALYSIS, V_LATEST_INVENTORY, V_BUDGET_VS_ACTUAL, V_CAMPAIGN_PERFORMANCE) calcolano a mano alcuni degli stessi totali: servono da riprova.
isql su un database di prova. Poi, nel Designer, importa lo schema con Importa da database (C3): le 17 FK vengono lette insieme alle tabelle, e il modello a stella parte da lì.H2. Aprire l’analisi e salvare il modello
Con un Designer aperto scegli dal menu Schema Designer la voce Analisi star schema (fatti e dimensioni)…. La voce è attiva solo quando c’è uno schema nel Designer. La finestra è modale: lavori nel modello e nella query, poi la chiudi.
| Che cosa | Come funziona |
|---|---|
| Dove vive il modello | Nella sezione "star_model" del file dello schema (Salva schema, C9). Un file salvato prima di questa funzione si apre normalmente, con il modello vuoto. |
| Riferimenti | Il modello cita tabelle e colonne per identificatore, non per nome: rinominare una tabella o una colonna nel Designer non lo rompe. |
| Modifiche | Se cambi il modello, alla chiusura il progetto risulta modificato. Le modifiche al modello non entrano nella cronologia Annulla / Ripeti e non compaiono nel confronto tra schemi. |
| Pacchetto semantico | Il modello a stella è separato dalla configurazione semantica: non è incluso nel pacchetto del G18. |
| Uscita | L’SQL generato si copia negli appunti, si apre nell’Editor o si carica nel Query Builder (H7). |
H3. Costruire il modello
Il punto di partenza è il pulsante Proponi modello dallo schema: legge le chiavi esterne e i nomi delle colonne e compila una prima bozza. Aggiunge soltanto ciò che manca: quello che hai già scritto nel modello non viene toccato.
Come decide
| Elemento | Regola |
|---|---|
| Fact | Tabella con almeno due FK in uscita e una colonna numerica che non è chiave, codice o componente di data. Oppure una tabella con una sola FK, almeno due misure e un nome che inizia per FACT_. Oppure una tabella senza misure con una FK verso la dimensione data (un evento, come l’ordine). |
| Testata | Una tabella referenziata da un’altra fact (la testata d’ordine, con le righe che la puntano) è proposta come dimensione, non come fact: il grain più fine è quello delle righe. |
| Dimensione | Ogni tabella puntata da una FK di una fact. Viene proposta come conformata: stesso significato e stesse chiavi per tutte le fact che la usano, condizione per confrontare più fact (H10). La chiave surrogata è la chiave primaria; la chiave naturale è la colonna UNIQUE (qui CUSTOMER_CODE, PRODUCT_CODE…). |
| Misure | Colonne numeriche non chiave. I nomi con PRICE, PERC, RATE… sono non additivi; quelli con ON_HAND, STOCK, BALANCE… semi-additivi. In una snapshot periodica tutte le quantità sono livelli, quindi semi-additive, salvo i nomi che indicano un flusso (SOLD, RECEIVED…). |
| Degeneri | Numeri di documento e di riga (ORDER_NUMBER, ORDER_LINE), colonne di testo rimaste sulla fact (RETURN_REASON) e componenti di data (BUDGET_YEAR): non sono misure, ma servono per raggruppare. |
| SCD | Una dimensione è storicizzata (SCD Type 2) solo se ha una coppia di colonne di validità dal nome inequivocabile (VALID_FROM / VALID_TO, VALIDO_DAL / VALIDO_AL) oppure un flag di versione corrente. START_DATE e END_DATE da soli non bastano. |
| Calendario | Nella dimensione data la gerarchia Anno › Trimestre › Mese › Giorno viene dalle colonne CAL_YEAR, CAL_QUARTER, CAL_MONTH, CALENDAR_DATE (o ANNO, TRIMESTRE, MESE, DATA). |
Che cosa propone sullo schema di esempio
| Fact | Tipo | Dimensioni | Misure | Degeneri |
|---|---|---|---|---|
FACT_SALES | transazionale | DIM_DATE, DIM_CUSTOMER, DIM_PRODUCT, DIM_STORE | QUANTITY, UNIT_PRICE, DISCOUNT_AMOUNT, REVENUE, COST_AMOUNT, GROSS_MARGIN | ORDER_NUMBER, ORDER_LINE |
FACT_ORDER_HEADER | senza misure | DIM_DATE, DIM_CUSTOMER, DIM_STORE | — | ORDER_NUMBER, ORDER_CHANNEL, PAYMENT_METHOD, ORDER_STATUS |
FACT_RETURNS | transazionale | DIM_DATE, DIM_CUSTOMER, DIM_PRODUCT, DIM_STORE | RETURNED_QUANTITY, REFUND_AMOUNT | ORIGINAL_ORDER_NUMBER, ORIGINAL_ORDER_LINE, RETURN_REASON, RESOLUTION_TYPE |
FACT_INVENTORY_SNAPSHOT | snapshot periodico | DIM_DATE, DIM_PRODUCT, DIM_STORE | QUANTITY_ON_HAND, QUANTITY_RESERVED, QUANTITY_AVAILABLE, QUANTITY_INCOMING, INVENTORY_VALUE | — |
FACT_BUDGET | transazionale | DIM_STORE | REVENUE_TARGET, REVENUE_ACTUAL, REVENUE_VARIANCE | BUDGET_YEAR, BUDGET_MONTH, PRODUCT_CATEGORY |
FACT_CAMPAIGN_PERFORMANCE | transazionale | DIM_CAMPAIGN, DIM_DATE | IMPRESSIONS, CLICKS, CONVERSIONS, MARKETING_SPEND, ATTRIBUTED_REVENUE, NET_CAMPAIGN_RETURN | — |
Le cinque dimensioni vengono proposte come conformate, e DIM_DATE è riconosciuta come dimensione data. DIM_CAMPAIGN resta senza storicizzazione: le sue START_DATE e END_DATE sono le date della campagna, non la validità di una versione.
- Il grain non viene mai proposto: lo scrivi tu (H4). Finché manca, il modello segnala l’errore
STAR002. FACT_ORDER_HEADERè proposta come fact senza misure: va bene per contare gli ordini.FACT_BUDGETnon ha una FK versoDIM_DATE: il tempo è inBUDGET_YEAReBUDGET_MONTH. Conta per i confronti con le vendite (H10).- Le misure derivate (Margine %, ROAS…) non vengono proposte: le aggiungi tu (H11).
Il pulsante Valida modello controlla il modello e scrive le segnalazioni STARxxx nel riquadro in basso a destra (H14). Dopo la proposta, sullo schema di esempio restano 6 errori (un grain mancante per ogni fact) e 6 avvisi (colonne del grain non indicate): scritti i grain e indicate le loro colonne, il modello non ha più segnalazioni.
H4. Il grain: che cosa è una riga
Il grain è la frase che dice che cosa rappresenta una riga della fact. Si scrive prima delle misure e delle dimensioni, perché è il grain a decidere quali misure e quali dimensioni hanno senso. Una fact ha un solo grain: se una tabella mescola righe di due livelli (un totale d’ordine accanto alle sue righe), la somma raddoppia.
Per scriverlo: seleziona la fact nell’albero e compila il campo nel pannello Proprietà, poi premi Applica al modello. Le colonne del grain sono quelle che, insieme, identificano la riga e servono a trovare i duplicati: con la fact selezionata premi Colonne del grain… e spunta le colonne. Finché non le indichi, il modello segnala l’avviso STAR020.
| Fact | Grain (una riga è…) | Colonne del grain |
|---|---|---|
FACT_SALES | Una riga per ogni riga d'ordine venduta (ORDER_NUMBER + ORDER_LINE) | ORDER_NUMBER, ORDER_LINE |
FACT_ORDER_HEADER | Una riga per ordine | ORDER_NUMBER |
FACT_RETURNS | Una riga per ogni reso registrato | RETURN_KEY |
FACT_INVENTORY_SNAPSHOT | Una riga per prodotto, negozio e fine mese | SNAPSHOT_DATE_KEY, PRODUCT_KEY, STORE_KEY |
FACT_BUDGET | Una riga per mese, categoria di prodotto e negozio | BUDGET_YEAR, BUDGET_MONTH, PRODUCT_CATEGORY, STORE_KEY |
FACT_CAMPAIGN_PERFORMANCE | Una riga per campagna e giorno | CAMPAIGN_KEY, DATE_KEY |
Le colonne del grain non sono sempre chiavi esterne. Nel budget compaiono BUDGET_YEAR, BUDGET_MONTH e PRODUCT_CATEGORY, che sono colonne della fact; nella giacenza compare la data dello scatto accanto a prodotto e negozio.
Verificare il grain sui dati
Se il grain è giusto, nessuna combinazione di quelle colonne compare due volte. Per FACT_SALES:
SELECT ORDER_NUMBER, ORDER_LINE, COUNT(*) AS N FROM FACT_SALES GROUP BY ORDER_NUMBER, ORDER_LINE HAVING COUNT(*) > 1
Sullo schema di esempio la query non restituisce righe, e lo stesso vale per le altre cinque fact con le loro colonne di grain.
Il tipo di fact
Accanto al grain, il campo Tipo descrive come cresce la tabella:
| Tipo | Significato | Nello schema di esempio |
|---|---|---|
| transazionale | Una riga per evento, mai modificata | FACT_SALES, FACT_RETURNS, FACT_CAMPAIGN_PERFORMANCE, FACT_BUDGET |
| snapshot periodico | Una riga per soggetto a ogni periodo (la fotografia di fine mese). Richiede il ruolo temporale | FACT_INVENTORY_SNAPSHOT |
| snapshot accumulante | Una riga per processo, aggiornata a ogni tappa (ordinato, spedito, consegnato), con più date | nessuna |
| senza misure | Registra che un evento è avvenuto; si conta con COUNT(*) | FACT_ORDER_HEADER |
H5. Misure e additività
Una misura è un numero della fact che si aggrega. Non tutte si aggregano allo stesso modo: l’additività dice lungo quali dimensioni la somma ha senso.
| Additività | Regola | Esempi nello schema |
|---|---|---|
| additiva | Si somma lungo tutte le dimensioni. | REVENUE, QUANTITY, COST_AMOUNT, REFUND_AMOUNT, MARKETING_SPEND |
| semi-additiva | Si somma fra prodotti, negozi e categorie nello stesso istante, non nel tempo. Nel tempo si prende l’ultimo valore, il primo, la media, il minimo o il massimo. | QUANTITY_ON_HAND, QUANTITY_AVAILABLE, INVENTORY_VALUE |
| non additiva | Non si somma mai: media, minimo, massimo, oppure un rapporto fra due aggregati. | UNIT_PRICE, e le misure derivate |
Selezionando una misura nell’albero, il pannello Proprietà mostra tre campi:
| Campo | Che cosa decide |
|---|---|
| Additività | additiva, semi-additiva (non si somma nel tempo), non additiva |
| Aggregazione | L’aggregazione usata quando non ne scegli una: SUM, COUNT, COUNT DISTINCT, AVG, MIN, MAX, LAST, FIRST |
| Nel tempo | Solo per le semi-additive: come aggregare lungo il tempo (di solito LAST) |
Il programma corregge le aggregazioni sbagliate e lo dice. Chiedere SUM(UNIT_PRICE) produce AVG(f.UNIT_PRICE) con l’avviso QRY008; chiedere SUM su una giacenza lungo il tempo produce LAST (H9).
UNIT_PRICE la media per categoria è una media semplice dei prezzi di riga. Per un prezzo medio ponderato sulle quantità serve una misura derivata: ricavi diviso quantità (H11).H6. Dimensioni, ruoli e dimensioni conformate
| Dimensione | Chiave surrogata | Chiave naturale | Attributi | Fact che la usano |
|---|---|---|---|---|
DIM_DATE | DATE_KEY | CALENDAR_DATE | 9 | 5 |
DIM_CUSTOMER | CUSTOMER_KEY | CUSTOMER_CODE | 7 | 3 |
DIM_PRODUCT | PRODUCT_KEY | PRODUCT_CODE | 5 | 3 |
DIM_STORE | STORE_KEY | STORE_CODE | 5 | 5 |
DIM_CAMPAIGN | CAMPAIGN_KEY | CAMPAIGN_CODE | 6 | 1 |
Una dimensione ha una chiave surrogata (un numero senza significato, generato dal DW: qui la chiave primaria) usata dalla fact, e una chiave naturale (il codice del sistema sorgente: CUSTOMER_CODE, PRODUCT_CODE…) che serve a riconoscere la stessa entità a ogni caricamento. Gli attributi sono le colonne con cui si raggruppa e si filtra.
Dimensioni conformate: la matrice dei fatti
Una dimensione è conformata quando ha lo stesso significato e le stesse chiavi in tutte le fact che la usano. È ciò che permette di mettere accanto misure di fact diverse: i ricavi di FACT_SALES e i rimborsi di FACT_RETURNS si confrontano per categoria perché entrambe puntano alla stessa DIM_PRODUCT (H10). Lo schema di esempio:
| Fact | DIM_DATE | DIM_CUSTOMER | DIM_PRODUCT | DIM_STORE | DIM_CAMPAIGN |
|---|---|---|---|---|---|
FACT_SALES | ● | ● | ● | ● | |
FACT_ORDER_HEADER | ● | ● | ● | ||
FACT_RETURNS | ● | ● | ● | ● | |
FACT_INVENTORY_SNAPSHOT | ● | ● | ● | ||
FACT_BUDGET | ● | ||||
FACT_CAMPAIGN_PERFORMANCE | ● | ● |
Si legge per colonna: DIM_STORE è usata da cinque fact su sei, e FACT_BUDGET è l’unica senza DIM_DATE.
Ruoli: la stessa dimensione più volte
Se una fact punta due volte alla stessa dimensione (una data d’ordine e una data di spedizione, entrambe verso DIM_DATE) si parla di role-playing. Ogni uso è un ruolo con un nome proprio, e il nome è obbligatorio: senza, il modello segnala STAR006 e la query non saprebbe quale data usare. Nell’albero il ruolo appare come Data ordine → DIM_DATE; per rinominarlo selezionalo e cambia il campo nel pannello Proprietà. Per ogni ruolo la query usa un alias distinto della dimensione.
FACT_SALES usa DATE_KEY e FACT_RETURNS usa RETURN_DATE_KEY, una sola data per fact, quindi il nome del ruolo resta vuoto. Se aggiungessi a FACT_SALES una colonna SHIP_DATE_KEY con la sua FK verso DIM_DATE, il programma proporrebbe i ruoli Date e Ship date ricavandoli dai nomi delle colonne.Storicizzazione (SCD)
Ogni attributo di una dimensione ha una regola per i cambiamenti: Type 0 non cambia mai; Type 1 sovrascrive il valore (nessuna storia); Type 2 crea una nuova riga con date di validità, così i fatti passati restano legati alla versione di allora. Una dimensione con attributi Type 2 deve avere tre colonne: inizio validità, fine validità e il flag della versione corrente; se mancano il modello segnala STAR014.
Nello schema di esempio tutti gli attributi sono Type 1: nessuna dimensione ha colonne di validità. Le colonne START_DATE e END_DATE di DIM_CAMPAIGN descrivono il periodo della campagna e sono attributi normali.
Membri speciali
Ogni dimensione riserva due righe per i fatti senza una corrispondenza: Sconosciuto (chiave −1) e Non applicabile (chiave −2). Così nessun fatto resta con una chiave nulla e nessuna query lo perde. Lo schema di esempio non ha queste righe: ogni FK punta a un membro reale. Le due chiavi (−1 e −2) e le loro etichette fanno parte del modello e vengono controllate dal programma (STAR024 se coincidono).
Gerarchie
Una gerarchia è un percorso di drill-down dal più aggregato al più dettagliato. Per DIM_DATE il programma ne propone una, Calendario: Anno (CAL_YEAR) › Trimestre (CAL_QUARTER) › Mese (CAL_MONTH) › Giorno (CALENDAR_DATE). Nell’albero i livelli compaiono sotto il ruolo, e un doppio clic su un livello lo porta in Raggruppa per.
H7. La finestra “Analisi star schema”
┌──────────────────────────────────────────────────────────────────────────┐ │ ★ Analisi star schema — fatti e dimensioni │ ├──────────────────────┬──────────────────────┬────────────────────────────┤ │ [1 Proponi modello] │ 5 Raggruppa per │ 9 SQL generato │ │ [2 Valida modello] │ (righe) │ (forma della query) │ │ │ 6 Misure (colonne) │ │ │ 3 Albero │ │ │ │ Fatti/Dimensioni │ 7 Filtri │ │ │ │ ├────────────────────────────┤ │ 4 Proprietà │ 8 ROLLUP / │ 10 Segnalazioni │ │ del nodo │ INNER JOIN │ │ │ │ │ 11 [Copia][Editor][Builder]│ └──────────────────────┴──────────────────────┴────────────────────────────┘
- Proponi modello dallo schema — bozza di fact e dimensioni (H3)
- Valida modello — segnalazioni STARxxx (H14)
- Albero Fatti / Dimensioni — sotto, una riga di suggerimento sul nodo selezionato
- Proprietà — grain e tipo della fact, additività e aggregazioni della misura, nome del ruolo; Applica al modello, + Derivata…, Elimina derivata, Colonne del grain…
- Raggruppa per (righe) — + Attributo, ↑ Su, Rimuovi
- Misure (colonne) — + Misura, aggregazione della misura selezionata, Rimuovi
- Filtri — operatore, valore, + Filtro, Rimuovi
- Subtotali (ROLLUP) e Escludi i fatti senza riga di dimensione (INNER JOIN)
- SQL generato — aggiornato a ogni modifica; la riga sopra dice la forma della query
- Segnalazioni — codici QRYxxx della query (H14)
- Copia SQL, Apri nell’editor, Apri nel Query Builder, Esegui, Chiudi
Questo è lo schema della finestra (le schermate sono nella I7). L’albero ha questo aspetto sullo schema di esempio (le righe con … sono accorciate):
Fatti [6]
FACT_SALES [transazionale]
Grain: Una riga per ogni riga d'ordine venduta (ORDER_NUMBER + ORDER_LINE)
Misure [7]
REVENUE [additiva · SUM]
UNIT_PRICE [non additiva · AVG]
Margine % [derivata]
Numero di righe [COUNT(*)]
Dimensioni [4]
DIM_DATE [N:1 · tempo]
Calendario [gerarchia]
Anno [CAL_YEAR]
Trimestre [CAL_QUARTER]
CAL_YEAR [SCD1]
…
DIM_PRODUCT [N:1]
CATEGORY [SCD1]
…
Degeneri [2]
ORDER_NUMBER [degenere]
FACT_INVENTORY_SNAPSHOT [snapshot periodico]
…
Dimensioni [5]
DIM_DATE [data · conformata]
Chiave surrogata: DATE_KEY [PK]
Chiave naturale: CALENDAR_DATE
Attributi [9]
Gerarchie [1]
Membri speciali: Sconosciuto = -1, Non applicabile = -2
Usata da: FACT_SALES, FACT_ORDER_HEADER, …
Come si lavora
| Gesto | Effetto |
|---|---|
| Doppio clic su un attributo | Lo aggiunge a Raggruppa per. Vale per gli attributi sotto un ruolo, per i livelli di una gerarchia e per le colonne degeneri. |
| Doppio clic su una misura | La aggiunge a Misure. Numero di righe conta le righe della fact al suo grain, con COUNT(*). |
| Selezionare un attributo e premere + Filtro | Aggiunge un filtro con l’operatore e il valore scritti accanto (H8). |
| Cambiare l’aggregazione nell’elenco Misure | Seleziona la misura nell’elenco e scegli l’aggregazione: l’SQL si aggiorna. “predefinita” usa quella del modello. |
Dove va l’SQL
- Copia SQL — negli appunti.
- Apri nell’editor — in un tab dell’Editor SQL, pronto da eseguire.
- Esegui — esegue la query sulla connessione attiva e mostra il risultato in una finestra con griglia (al massimo 5000 righe). Serve una connessione aperta. Le schermate della finestra sono nella I7.
- Apri nel Query Builder — disponibile solo per la forma semplice (una fact, nessuna misura derivata, nessun calcolo nel tempo, nessun ROLLUP): il Builder la legge e disegna tabelle e JOIN. Serve una connessione attiva, perché il Builder verifica le tabelle sul database; senza connessione l’SQL va nell’Editor. Se il Builder ha già tabelle, chiede conferma prima di sostituirle.
La riga sopra l’SQL indica la forma della query: query semplice, calcolo a due livelli nel tempo (H9) o drill-across (H10). Il dialetto dello schema decide virgolette degli identificatori, sintassi del ROLLUP e valori NULL tipizzati (H12).
H8. La prima query: ricavi e margine per categoria e canale
Domanda: quanto abbiamo venduto e quanto abbiamo guadagnato per ogni categoria di prodotto e canale di vendita?
- Apri FACT_SALES › Dimensioni › DIM_PRODUCT e fai doppio clic su
CATEGORY; poi DIM_STORE e doppio clic suCHANNEL. Compaiono in Raggruppa per, nell’ordine in cui li scegli. - Apri FACT_SALES › Misure e fai doppio clic su
REVENUEe suGROSS_MARGIN.
L’SQL appare subito a destra:
SELECT
d_product.CATEGORY AS CATEGORY,
d_store.CHANNEL AS CHANNEL,
SUM(f.REVENUE) AS REVENUE,
SUM(f.GROSS_MARGIN) AS GROSS_MARGIN
FROM FACT_SALES f
LEFT JOIN DIM_PRODUCT d_product ON d_product.PRODUCT_KEY = f.PRODUCT_KEY
LEFT JOIN DIM_STORE d_store ON d_store.STORE_KEY = f.STORE_KEY
GROUP BY d_product.CATEGORY, d_store.CHANNEL
ORDER BY d_product.CATEGORY, d_store.CHANNEL
| CATEGORY | CHANNEL | REVENUE | GROSS_MARGIN |
|---|---|---|---|
| Audio | B2B | 29.865,65 | 8.448,65 |
| Audio | E-commerce | 23.280,25 | 6.681,25 |
| Audio | Retail | 64.796,70 | 18.271,70 |
| Monitor | B2B | 37.878,60 | 9.983,60 |
| Monitor | E-commerce | 50.092,25 | 13.217,25 |
| Monitor | Retail | 136.592,65 | 35.516,65 |
Prime 6 righe di 15.
- Le JOIN le scrive il programma: dalla fact verso ogni dimensione scelta, con la FK della fact e la chiave surrogata della dimensione. Non unisce mai due dimensioni fra loro.
- Sono LEFT JOIN: se un fatto non trova la riga di dimensione, resta nel risultato (con valore nullo) e i totali coincidono sempre con quelli della fact. Con Escludi i fatti senza riga di dimensione (INNER JOIN) diventano
INNER JOIN: usalo quando il caricamento garantisce i membri Sconosciuto (H6). - Il GROUP BY e l’ORDER BY seguono le colonne di Raggruppa per. Gli alias sono i nomi di colonna e di misura.
- Il totale per canale coincide con la vista
V_SALES_ANALYSISdello script, raggruppata allo stesso modo.
Questa è una query semplice (una fact, aggregazioni elementari): Apri nel Query Builder è disponibile.
Filtri
Domanda: per ogni brand, ricavi, pezzi e righe di vendita di primavera a clienti Business o Enterprise. Seleziona nell’albero l’attributo da filtrare, scegli l’operatore, scrivi il valore e premi + Filtro:
| Attributo | Operatore | Valore |
|---|---|---|
DIM_CUSTOMER › SEGMENT | IN | Business; Enterprise |
DIM_DATE › CALENDAR_DATE | BETWEEN | 01/03/2026; 31/05/2026 |
Con Numero di righe tra le misure l’SQL diventa:
SELECT
d_product.BRAND AS BRAND,
SUM(f.REVENUE) AS REVENUE,
SUM(f.QUANTITY) AS QUANTITY,
COUNT(*) AS ROW_COUNT
FROM FACT_SALES f
LEFT JOIN DIM_PRODUCT d_product ON d_product.PRODUCT_KEY = f.PRODUCT_KEY
LEFT JOIN DIM_CUSTOMER d_customer ON d_customer.CUSTOMER_KEY = f.CUSTOMER_KEY
LEFT JOIN DIM_DATE d_date ON d_date.DATE_KEY = f.DATE_KEY
WHERE d_customer.SEGMENT IN ('Business', 'Enterprise')
AND d_date.CALENDAR_DATE BETWEEN '2026-03-01' AND '2026-05-31'
GROUP BY d_product.BRAND
ORDER BY d_product.BRAND
| BRAND | REVENUE | QUANTITY | ROW_COUNT |
|---|---|---|---|
| DataFlash | 18.994,30 | 124 | 61 |
| KeyLab | 12.896,55 | 149 | 57 |
| SoundCore | 19.486,15 | 134 | 58 |
| TechNova | 143.038,95 | 133 | 53 |
| ViewMax | 47.002,05 | 135 | 58 |
- Più valori (per
IN,NOT IN,BETWEEN) si separano con;. - I valori si scrivono senza apici: il programma li formatta in base al tipo della colonna. I numeri vengono verificati, il testo e le date vanno tra apici (con l’apice doppiato se il testo ne contiene uno), e le date scritte
gg/mm/aaaadiventanoaaaa-mm-gg. - Operatori disponibili:
=,<>,<,<=,>,>=,LIKE,IN,NOT IN,BETWEEN,IS NULL,IS NOT NULL. - I filtri valgono sugli attributi (clausola
WHERE); non esistono ancora filtri sul valore di una misura (HAVING).
H9. Misure semi-additive: la giacenza
FACT_INVENTORY_SNAPSHOT contiene la giacenza di ogni prodotto in ogni negozio a fine mese: 12 fotografie. Sommare QUANTITY_ON_HAND su tutto l’anno somma dodici volte gli stessi pezzi, e il risultato non è una giacenza.
| Categoria | SUM su tutto l’anno (sbagliata) | LAST nel tempo (giusta) |
|---|---|---|
| Audio | 15.308 | 1.542 |
| Monitor | 14.114 | 1.320 |
| Notebook | 15.159 | 1.583 |
| Periferiche | 14.636 | 1.151 |
| Storage | 15.691 | 1.667 |
| Totale | 74.908 | 7.263 |
La somma sbagliata è circa dieci volte il valore vero. Per questo la misura è semi-additiva con Nel tempo = LAST: fra prodotti e negozi si somma, nel tempo si prende l’ultima fotografia.
Domanda: qual è la giacenza e il suo valore, oggi, per categoria? Basta scegliere CATEGORY e le due misure: il programma capisce che il tempo non è nel raggruppamento e scrive un calcolo a due livelli.
WITH base AS (
SELECT
d_product.CATEGORY AS g1,
f.SNAPSHOT_DATE_KEY AS t_key,
SUM(f.QUANTITY_ON_HAND) AS b1,
SUM(f.INVENTORY_VALUE) AS b2
FROM FACT_INVENTORY_SNAPSHOT f
LEFT JOIN DIM_PRODUCT d_product ON d_product.PRODUCT_KEY = f.PRODUCT_KEY
GROUP BY d_product.CATEGORY, f.SNAPSHOT_DATE_KEY
),
bounds AS (
SELECT g1, MAX(t_key) AS t_last, MIN(t_key) AS t_first
FROM base
GROUP BY g1
)
SELECT
b.g1 AS CATEGORY,
SUM(CASE WHEN b.t_key = l.t_last THEN b.b1 END) AS QUANTITY_ON_HAND,
SUM(CASE WHEN b.t_key = l.t_last THEN b.b2 END) AS INVENTORY_VALUE
FROM base b
INNER JOIN bounds l ON (b.g1 = l.g1 OR (b.g1 IS NULL AND l.g1 IS NULL))
GROUP BY b.g1
ORDER BY b.g1
| CATEGORY | QUANTITY_ON_HAND | INVENTORY_VALUE |
|---|---|---|
| Audio | 1.542 | 120.707,00 |
| Monitor | 1.320 | 325.117,00 |
| Notebook | 1.583 | 1.113.301,00 |
| Periferiche | 1.151 | 64.264,00 |
| Storage | 1.667 | 173.284,00 |
- base: somma le misure per categoria e per istante (una riga per categoria e fine mese).
- bounds: trova per ogni categoria il primo e l’ultimo istante.
- La query finale tiene, per ogni categoria, solo la riga dell’ultimo istante.
Il totale (7.263) coincide con la somma di V_LATEST_INVENTORY, la vista dello script che prende l’ultima fotografia di ogni prodotto e negozio.
Il tempo nel raggruppamento
Se raggruppi per CAL_QUARTER il calcolo diventa “l’ultima fotografia di ciascun trimestre”:
| CAL_QUARTER | QUANTITY_ON_HAND |
|---|---|
| 1 | 6.021 |
| 2 | 6.272 |
| 3 | 6.245 |
| 4 | 7.263 |
Se raggruppi per giorno (il grain), non serve alcun calcolo e la query torna semplice. Lo stesso vale con un filtro su un singolo giorno.
Altre aggregazioni nel tempo
Scegliendo AVG per la misura, la giacenza diventa la media delle fotografie (prima somma per istante, poi media nel tempo):
| CATEGORY | QUANTITY_ON_HAND |
|---|---|
| Audio | 1.275,67 |
| Monitor | 1.176,17 |
| Notebook | 1.263,25 |
| Periferiche | 1.219,67 |
| Storage | 1.307,58 |
Se chiedi SUM su una misura semi-additiva con il tempo fuori dal raggruppamento, il programma non la esegue: usa LAST e lo segnala.
W QRY008: "QUANTITY_ON_HAND" ? semi-additiva: si somma per istante, ma lungo il tempo va aggregata con LAST. Sommarla su pi? periodi moltiplica il valore per il numero di periodi. Usata LAST.
- “Ultimo” significa la chiave temporale più alta: la chiave della dimensione data deve crescere con il tempo.
DATE_KEYin formaAAAAMMGGva bene; una chiave surrogata assegnata a caso no. COUNT DISTINCTnon si può calcolare in due livelli: il programma lo rifiuta (QRY011).- Una snapshot senza ruolo temporale non può usare
LASToFIRST(QRY009). Il ruolo temporale è la FK verso la dimensione data, scelta dal programma: se la fact non ne ha, il modello segnalaSTAR011.
H10. Più fatti insieme: drill-across
Domanda: per ogni categoria, quanto abbiamo venduto e quanto abbiamo rimborsato? I ricavi sono in FACT_SALES, i rimborsi in FACT_RETURNS. Scegli la misura REVENUE di una fact, REFUND_AMOUNT dell’altra e l’attributo CATEGORY di DIM_PRODUCT, che le due fact hanno in comune.
Unire due fact con una JOIN moltiplica le righe (ogni vendita si ripete per ogni reso della stessa riga) e i totali risultano gonfiati: è il fan trap. Il programma non unisce mai due fact. Aggrega ciascuna per conto suo sulla dimensione comune e poi affianca i risultati:
WITH q1 AS (
SELECT
d_product.CATEGORY AS g1,
SUM(f.REVENUE) AS m1_1
FROM FACT_SALES f
LEFT JOIN DIM_PRODUCT d_product ON d_product.PRODUCT_KEY = f.PRODUCT_KEY
GROUP BY d_product.CATEGORY
),
q2 AS (
SELECT
d_product.CATEGORY AS g1,
SUM(f.REFUND_AMOUNT) AS m2_1
FROM FACT_RETURNS f
LEFT JOIN DIM_PRODUCT d_product ON d_product.PRODUCT_KEY = f.PRODUCT_KEY
GROUP BY d_product.CATEGORY
)
SELECT
u.g1 AS CATEGORY,
MAX(u.m1_1) AS "REVENUE (FACT_SALES)",
MAX(u.m2_1) AS "REFUND_AMOUNT (FACT_RETURNS)"
FROM (
SELECT g1, m1_1, CAST(NULL AS DOUBLE PRECISION) AS m2_1 FROM q1
UNION ALL
SELECT g1, CAST(NULL AS DOUBLE PRECISION) AS m1_1, m2_1 FROM q2
) u
GROUP BY u.g1
ORDER BY u.g1
| CATEGORY | REVENUE (FACT_SALES) | REFUND_AMOUNT (FACT_RETURNS) |
|---|---|---|
| Audio | 117.942,60 | 6.809,20 |
| Monitor | 224.563,50 | 8.743,55 |
| Notebook | 784.707,15 | 47.179,95 |
| Periferiche | 72.743,60 | 3.849,60 |
| Storage | 109.530,25 | 5.918,40 |
- Una CTE per fact (
q1,q2), ognuna con le sue JOIN verso le dimensioni. - Le CTE si impilano con
UNION ALLe si compattano conMAXper riga: non c’è nessuna JOIN fra fact. - I
NULLsegnaposto sonoCAST(NULL AS DOUBLE PRECISION), perché Firebird non sa dedurre il tipo di unNULLnudo (H12). - Le intestazioni portano il nome della fact:
REVENUE (FACT_SALES). - Una categoria presente in una sola fact avrebbe l’altra colonna vuota, non zero.
Il tempo nel confronto
Raggruppando per CAL_QUARTER, ciascuna fact usa il proprio collegamento alla data: i ricavi per data di vendita (DATE_KEY), i rimborsi per data del reso (RETURN_DATE_KEY). Un rimborso di gennaio per una vendita di dicembre cade nel trimestre del reso.
| CAL_QUARTER | REVENUE (FACT_SALES) | REFUND_AMOUNT (FACT_RETURNS) |
|---|---|---|
| 1 | 271.409,85 | 17.457,75 |
| 2 | 370.535,45 | 24.967,30 |
| 3 | 354.635,85 | 15.333,20 |
| 4 | 312.905,95 | 14.742,45 |
Quando il confronto non è possibile: il budget
Le vendite e il budget si confrontano per canale, perché entrambe le fact puntano a DIM_STORE:
| CHANNEL | REVENUE (FACT_SALES) | REVENUE_TARGET (FACT_BUDGET) |
|---|---|---|
| B2B | 262.133,55 | 1.568.118,00 |
| E-commerce | 327.485,85 | 1.540.501,00 |
| Retail | 719.867,70 | 4.750.247,00 |
FACT_BUDGET (circa 7,5 milioni) sono molto più alti dei ricavi di FACT_SALES (1,31 milioni): sono dati di prova non riconciliati. In un DW reale il consuntivo non si copia nella fact del budget, si legge dalle vendite, proprio con un confronto come questo.Per mese di calendario invece il confronto non si può fare. FACT_BUDGET non ha una FK verso DIM_DATE: il tempo è in BUDGET_YEAR e BUDGET_MONTH. Se scegli CAL_MONTH di DIM_DATE insieme alle misure delle due fact, il programma risponde:
E QRY005: La dimensione "DIM_DATE" non ? collegata alla fact "FACT_BUDGET": i suoi attributi non possono essere usati per analizzarne le misure.
La soluzione è nello schema, non nella query: dare al budget una FK verso DIM_DATE (per esempio BUDGET_DATE_KEY, il primo giorno del mese) e dichiararla come ruolo della fact. Da quel momento la dimensione data è comune e il confronto mensile funziona. Il budget da solo, per mese, si legge già oggi con le colonne BUDGET_MONTH (H11).
| Regola del confronto fra fact |
|---|
Ogni attributo di Raggruppa per deve appartenere a una dimensione collegata a tutte le fact scelte (QRY005 altrimenti). |
| Le colonne degeneri non valgono: appartengono a una sola fact. |
Se una dimensione ha più ruoli in una fact, devi indicare quale (QRY006); con un solo ruolo il nome è ignorato, così lo stesso attributo vale per fact diverse. |
| Una misura derivata usa solo le misure della propria fact, ma può stare accanto a quelle di altre fact: ciascuna è calcolata nella CTE della sua fact. |
H11. Misure derivate: rapporti fra aggregati
Un margine percentuale, un tasso di click o un ritorno sulla spesa sono rapporti: non esistono come colonna e non si sommano. Si definiscono come misure derivate, con una formula sulle misure della stessa fact. Il programma non le propone: le aggiungi tu.
- Seleziona nell’albero la fact (o una sua misura).
- Premi + Derivata… sotto il pannello Proprietà.
- Scrivi il nome (per esempio
ROAS) e poi la formula.
| Fact | Misura derivata | Formula |
|---|---|---|
FACT_SALES | Margine % | 100.0 * {GROSS_MARGIN} / NULLIF({REVENUE}, 0) |
FACT_BUDGET | Scostamento % | 100.0 * {REVENUE_VARIANCE} / NULLIF({REVENUE_TARGET}, 0) |
FACT_CAMPAIGN_PERFORMANCE | CTR % | 100.0 * {CLICKS} / NULLIF({IMPRESSIONS}, 0) |
FACT_CAMPAIGN_PERFORMANCE | ROAS | {ATTRIBUTED_REVENUE} / NULLIF({MARKETING_SPEND}, 0) |
- Nella formula
{{MISURA}}è l’aggregato della misura (la somma, con l’aggregazione predefinita), non il valore di una riga. Il resto è SQL: operatori,NULLIF, costanti. - Scrivi sempre
NULLIF(denominatore, 0): un gruppo con denominatore zero dà un valore nullo invece di un errore. - Il programma controlla la formula: un nome di misura che non esiste nella fact fa rifiutare la misura (
STAR010). - La misura derivata è non additiva e non ha un’aggregazione da scegliere: il valore si calcola sempre sul gruppo.
- Per eliminarla seleziona la misura e premi Elimina derivata. Le misure che corrispondono a colonne non si eliminano da qui.
Perché rapporto di aggregati e non media di rapporti
Il margine percentuale di tutte le vendite è la somma dei margini divisa per la somma dei ricavi: 27,70%. La media dei margini percentuali delle singole righe darebbe 28,55%, perché conta come uguali una riga da 20 euro e una da 2.000. Lo stesso per il tasso di click delle campagne: 2,54% corretto contro 2,62% con la media delle righe giornaliere.
Esempio: campagne
Domanda: per ogni campagna, spesa, ricavi attribuiti, CTR e ROAS. Si scelgono CAMPAIGN_NAME, le misure MARKETING_SPEND e ATTRIBUTED_REVENUE e le due derivate:
SELECT
d_campaign.CAMPAIGN_NAME AS CAMPAIGN_NAME,
SUM(f.MARKETING_SPEND) AS MARKETING_SPEND,
SUM(f.ATTRIBUTED_REVENUE) AS ATTRIBUTED_REVENUE,
100.0 * (SUM(f.CLICKS)) / NULLIF((SUM(f.IMPRESSIONS)), 0) AS "CTR %",
(SUM(f.ATTRIBUTED_REVENUE)) / NULLIF((SUM(f.MARKETING_SPEND)), 0) AS ROAS
FROM FACT_CAMPAIGN_PERFORMANCE f
LEFT JOIN DIM_CAMPAIGN d_campaign ON d_campaign.CAMPAIGN_KEY = f.CAMPAIGN_KEY
GROUP BY d_campaign.CAMPAIGN_NAME
ORDER BY d_campaign.CAMPAIGN_NAME
| CAMPAIGN_NAME | MARKETING_SPEND | ATTRIBUTED_REVENUE | CTR % | ROAS |
|---|---|---|---|---|
| Audio Summer | 107.808,52 | 668.136,39 | 2,60 | 6,20 |
| Back to School | 61.848,80 | 497.109,74 | 2,84 | 8,04 |
| Black Friday Tech | 69.085,03 | 377.010,13 | 2,94 | 5,46 |
| Corporate Upgrade | 267.588,53 | 1.699.799,79 | 2,48 | 6,35 |
| Spring Storage | 73.293,74 | 472.148,29 | 2,23 | 6,44 |
I valori coincidono con V_CAMPAIGN_PERFORMANCE (nella vista il CTR è arrotondato a due decimali).
Esempio: budget e consuntivo per mese
Nel budget il tempo è nelle colonne BUDGET_MONTH e BUDGET_YEAR della fact, riconosciute come degeneri (H13). Su una fact sola si possono usare come attributi:
SELECT
f.BUDGET_MONTH AS BUDGET_MONTH,
SUM(f.REVENUE_TARGET) AS REVENUE_TARGET,
SUM(f.REVENUE_ACTUAL) AS REVENUE_ACTUAL,
100.0 * (SUM(f.REVENUE_VARIANCE)) / NULLIF((SUM(f.REVENUE_TARGET)), 0) AS "Scostamento %"
FROM FACT_BUDGET f
GROUP BY f.BUDGET_MONTH
ORDER BY f.BUDGET_MONTH
| BUDGET_MONTH | REVENUE_TARGET | REVENUE_ACTUAL | Scostamento % |
|---|---|---|---|
| 1 | 638.703,00 | 623.183,23 | -2,43 |
| 2 | 699.041,00 | 674.052,95 | -3,57 |
| 3 | 641.032,00 | 625.490,01 | -2,42 |
| 4 | 608.257,00 | 571.909,76 | -5,98 |
| 5 | 649.732,00 | 632.342,24 | -2,68 |
| 6 | 708.807,00 | 685.392,78 | -3,30 |
| 7 | 648.170,00 | 632.030,04 | -2,49 |
| 8 | 604.988,00 | 545.198,63 | -9,88 |
| 9 | 616.928,00 | 565.382,29 | -8,36 |
| 10 | 717.971,00 | 675.888,53 | -5,86 |
| 11 | 770.428,00 | 728.363,20 | -5,46 |
| 12 | 554.809,00 | 545.444,45 | -1,69 |
Lo scostamento è negativo quando il consuntivo è sotto il budget. I valori coincidono con V_BUDGET_VS_ACTUAL.
Esempio: margine percentuale per trimestre e categoria
SELECT
d_date.CAL_QUARTER AS CAL_QUARTER,
d_product.CATEGORY AS CATEGORY,
SUM(f.REVENUE) AS REVENUE,
SUM(f.GROSS_MARGIN) AS GROSS_MARGIN,
100.0 * (SUM(f.GROSS_MARGIN)) / NULLIF((SUM(f.REVENUE)), 0) AS "Margine %"
FROM FACT_SALES f
LEFT JOIN DIM_DATE d_date ON d_date.DATE_KEY = f.DATE_KEY
LEFT JOIN DIM_PRODUCT d_product ON d_product.PRODUCT_KEY = f.PRODUCT_KEY
GROUP BY d_date.CAL_QUARTER, d_product.CATEGORY
ORDER BY d_date.CAL_QUARTER, d_product.CATEGORY
| CAL_QUARTER | CATEGORY | REVENUE | GROSS_MARGIN | Margine % |
|---|---|---|---|---|
| 1 | Audio | 24.413,45 | 6.976,45 | 28,58 |
| 1 | Monitor | 42.887,05 | 11.396,05 | 26,57 |
| 1 | Notebook | 155.802,90 | 42.845,90 | 27,50 |
| 1 | Periferiche | 14.882,55 | 4.286,55 | 28,80 |
| 1 | Storage | 33.423,90 | 10.266,90 | 30,72 |
| 2 | Audio | 28.227,30 | 7.783,30 | 27,57 |
| 2 | Monitor | 55.435,40 | 13.977,40 | 25,21 |
| 2 | Notebook | 241.426,35 | 65.145,35 | 26,98 |
Prime 8 righe di 20.
Una query con misure derivate non è una query semplice: Apri nel Query Builder resta disattivo e l’SQL si apre nell’Editor.
H12. Subtotali e dialetti
Con Subtotali (ROLLUP) la stessa query restituisce anche i totali parziali e il totale generale. Esempio: ricavi per categoria e canale, con PostgreSQL come dialetto:
SELECT
d_product.CATEGORY AS CATEGORY,
d_store.CHANNEL AS CHANNEL,
SUM(f.REVENUE) AS REVENUE
FROM FACT_SALES f
LEFT JOIN DIM_PRODUCT d_product ON d_product.PRODUCT_KEY = f.PRODUCT_KEY
LEFT JOIN DIM_STORE d_store ON d_store.STORE_KEY = f.STORE_KEY
GROUP BY ROLLUP (d_product.CATEGORY, d_store.CHANNEL)
ORDER BY d_product.CATEGORY, d_store.CHANNEL
| CATEGORY | CHANNEL | REVENUE |
|---|---|---|
| Audio | B2B | 29.865,65 |
| Audio | E-commerce | 23.280,25 |
| Audio | Retail | 64.796,70 |
| Audio | NULL | 117.942,60 |
| NULL | NULL | 1.309.487,10 |
- Una riga con
NULLnell’ultima colonna di raggruppamento è il subtotale della categoria; conNULLin tutte è il totale generale. Il totale generale coincide con la somma diFACT_SALES. - Dove vanno i
NULLnell’ordinamento dipende dal motore. - Il ROLLUP vale solo per la query semplice: con più fact o con il calcolo nel tempo viene ignorato con un avviso (
QRY012); con una misura semi-additiva e il tempo nel raggruppamento avverte che i subtotali non sono giusti (QRY014). - Con LEFT JOIN, un fatto senza riga di dimensione produce un
NULLche si confonde con un subtotale (QRY018). Con i membri Sconosciuto caricati dal DW, o con INNER JOIN, l’ambiguità sparisce.
Che cosa cambia da un dialetto all’altro
| Dialetto | ROLLUP | NULL tipizzati (drill-across) |
|---|---|---|
| Firebird, InterBase | non supportato: ignorato con avviso (QRY013) | sì: CAST(NULL AS DOUBLE PRECISION) |
| SQLite, MS Access | non supportato (QRY013) | no |
| MySQL, MariaDB | GROUP BY a, b WITH ROLLUP (senza ORDER BY, QRY017) | no |
| PostgreSQL, SQL Server, Oracle | GROUP BY ROLLUP (a, b) | no |
| IBM DB2 | GROUP BY ROLLUP (a, b) | sì |
Sul dialetto Firebird dello schema di esempio la stessa richiesta restituisce l’SQL senza ROLLUP e questo avviso:
W QRY013: ROLLUP ignorato: il dialetto del database non lo supporta.
Il dialetto decide anche le virgolette degli identificatori: un nome come "Margine %" o una parola riservata vengono virgolettati secondo le regole del motore, e un nome semplice no.
H13. Dimensioni degeneri e fact senza misure
Una dimensione degenere è una colonna che sta sulla fact e funziona da attributo, senza una tabella dimensione dietro: il numero d’ordine, il numero di riga, il motivo di un reso, lo stato di un ordine. Nell’albero stanno nella cartella Degeneri della fact e si usano come qualsiasi attributo.
Resi per motivo
Domanda: quanti resi e quanto rimborsato per ogni motivo? Scegli RETURN_REASON (degenere), Numero di righe e REFUND_AMOUNT:
SELECT
f.RETURN_REASON AS RETURN_REASON,
COUNT(*) AS ROW_COUNT,
SUM(f.REFUND_AMOUNT) AS REFUND_AMOUNT
FROM FACT_RETURNS f
GROUP BY f.RETURN_REASON
ORDER BY f.RETURN_REASON
| RETURN_REASON | ROW_COUNT | REFUND_AMOUNT |
|---|---|---|
| Cambio idea | 29 | 10.907,15 |
| Danno trasporto | 28 | 15.054,05 |
| Errore ordine | 33 | 22.626,60 |
| Non conforme | 26 | 14.468,30 |
| Prodotto difettoso | 21 | 9.444,60 |
Numero di righe conta le righe della fact: in FACT_RETURNS una riga è un reso, perciò il conteggio è il numero di resi (137 in tutto).
Ordini: una fact senza misure
FACT_ORDER_HEADER non ha colonne numeriche da sommare: registra che un ordine è avvenuto, quando, per chi e dove. È una fact senza misure, e si interroga contando le righe. Domanda: quanti ordini per metodo di pagamento e stato?
SELECT
f.PAYMENT_METHOD AS PAYMENT_METHOD,
f.ORDER_STATUS AS ORDER_STATUS,
COUNT(*) AS ROW_COUNT
FROM FACT_ORDER_HEADER f
GROUP BY f.PAYMENT_METHOD, f.ORDER_STATUS
ORDER BY f.PAYMENT_METHOD, f.ORDER_STATUS
| PAYMENT_METHOD | ORDER_STATUS | ROW_COUNT |
|---|---|---|
| Bonifico | Annullato | 54 |
| Bonifico | Consegnato | 46 |
| Bonifico | In preparazione | 49 |
| Bonifico | In transito | 62 |
| Carta | Annullato | 51 |
| Carta | Consegnato | 47 |
| Carta | In preparazione | 43 |
| Carta | In transito | 51 |
Prime 8 righe di 16.
Le righe totali sono 786, tante quante gli ordini distinti di FACT_SALES: ogni ordine ha la sua testata. Per analizzare gli ordini per mese, cliente o negozio basta aggiungere gli attributi delle dimensioni collegate (DIM_DATE, DIM_CUSTOMER, DIM_STORE).
- Una colonna degenere appartiene a una sola fact: si usa nelle query su quella fact, non nei confronti fra più fact (H10).
- Colonne di testo come
PAYMENT_METHODeORDER_STATUSfunzionano così come sono. Se molte colonne di questo tipo si accumulano su una fact, spostarle in una piccola dimensione (una junk dimension) rende la fact più stretta e i valori riusabili.
H14. Messaggi e codici
Ogni segnalazione ha un codice stabile. Le STARxxx riguardano il modello (le scrive Valida modello e compaiono nell’albero, nel nodo Problemi del modello); le QRYxxx riguardano la query in costruzione (nel riquadro Segnalazioni). Un errore blocca la generazione dell’SQL o la voce interessata; un avviso lascia generare l’SQL ma dice che è stato corretto o che il risultato va letto con attenzione; una info è solo una nota.
Modello (STAR)
| Codice | Tipo | Significato |
|---|---|---|
STAR001 | errore | Tabella dichiarata come fact o dimensione ma assente dallo schema. |
STAR002 | errore | Grain della fact non dichiarato. |
STAR003 | avviso | Fact senza dimensioni. |
STAR004 | errore | Ruolo che punta a una dimensione non dichiarata. |
STAR005 | errore | Colonna FK del ruolo mancante o non appartenente alla fact. |
STAR006 | errore | Stessa dimensione usata più volte senza nomi di ruolo distinti. |
STAR007 | errore / avviso | Misura senza colonna (errore) o con colonna non numerica (avviso). |
STAR008 | avviso | Misura semi-additiva senza aggregazione nel tempo. |
STAR009 | errore | Aggregazione SUM su una misura non additiva o derivata. |
STAR010 | errore / avviso | Misura derivata: riferimento a una misura inesistente (errore); misura derivata annidata o con additività incoerente (avviso). |
STAR011 | errore | Snapshot periodico senza ruolo temporale principale. |
STAR012 | errore / avviso | Chiave surrogata mancante (errore) o diversa dalla chiave primaria (avviso). |
STAR013 | avviso | Dimensione senza chiave naturale. |
STAR014 | errore | Attributi Type 2 senza colonne di validità (inizio, fine, versione corrente). |
STAR015 | errore | Dimensione Type 2 con chiave surrogata uguale alla chiave naturale. |
STAR016 | errore | Livello di gerarchia su una colonna che non appartiene alla dimensione. |
STAR017 | errore | Stessa tabella dichiarata sia fact sia dimensione. |
STAR018 | info | Nessuna FK fisica fra fact e dimensione (lecito in un DW). |
STAR019 | errore | Nomi di misura duplicati nella stessa fact. |
STAR020 | errore / avviso | Colonne del grain inesistenti (errore) o non indicate (avviso). |
STAR021 | info | Dimensione non usata da nessuna fact. |
STAR022 | info | Snowflake: dimensione con una FK verso un’altra dimensione. |
STAR023 | avviso | Chiave surrogata della dimensione data non intera. |
STAR024 | errore | Membri Sconosciuto e Non applicabile con la stessa chiave. |
STAR025 | errore | Colonna usata sia come misura sia come FK di dimensione. |
STAR026 | avviso | Ruolo temporale che non corrisponde a nessun ruolo della fact. |
STAR027 | errore | Colonna di attributo, chiave o validità non appartenente alla dimensione. |
Query (QRY)
| Codice | Tipo | Significato |
|---|---|---|
QRY001 | errore | Nessuna misura richiesta. |
QRY002 | errore | Fact non dichiarata nel modello, o tabella assente dallo schema. |
QRY003 | errore | Misura inesistente, o componente inesistente di una misura derivata. |
QRY004 | errore | Attributo di una tabella non dichiarata come dimensione. |
QRY005 | errore | Attributo di una dimensione non collegata alla fact (o a una delle fact). |
QRY006 | errore | Ruolo ambiguo: dimensione con più ruoli e nome del ruolo assente o errato. |
QRY007 | errore | Colonna dell’attributo o della misura assente. |
QRY008 | avviso | Aggregazione corretta dalla regola di additività (per esempio SUM → AVG, SUM → LAST). |
QRY009 | errore | LAST o FIRST richiesti senza un ruolo temporale. |
QRY010 | avviso | Misura semi-additiva in una fact senza ruolo temporale. |
QRY011 | errore | COUNT DISTINCT non calcolabile nel calcolo a due livelli. |
QRY012 | avviso | ROLLUP ignorato: la query non è semplice. |
QRY013 | avviso | ROLLUP non supportato dal dialetto. |
QRY014 | avviso | ROLLUP con misura semi-additiva e tempo nel raggruppamento. |
QRY015 | errore | JOIN impossibile: chiave surrogata della dimensione non determinabile. |
QRY016 | errore | Filtro con valori mancanti o non validi per il tipo della colonna. |
QRY017 | info | Con WITH ROLLUP (MySQL) l’ORDER BY viene omesso. |
QRY018 | info | ROLLUP con LEFT JOIN: i NULL dei membri mancanti si confondono con i subtotali. |
H15. Limiti e problemi comuni
Limiti attuali
| Limite | Dettaglio |
|---|---|
| “Ultimo” nel tempo è la chiave temporale più alta. | La chiave della dimensione data deve crescere con il tempo (AAAAMMGG va bene). |
| SCD Type 2: lettura “com’era”. | La query unisce con la chiave surrogata registrata nella fact, quindi mostra gli attributi della versione di allora. Non esiste ancora la lettura “com’è oggi” sulla versione corrente. |
| Filtri solo sugli attributi. | Niente filtri sul valore di una misura (HAVING). |
| Query Builder: solo la forma semplice. | Una fact, nessuna misura derivata, nessun calcolo nel tempo, nessun ROLLUP. |
| Confronto fra fact. | Solo con attributi di dimensioni collegate a tutte le fact; le colonne degeneri non valgono. |
| ROLLUP. | Solo sulla query semplice e nei dialetti che lo supportano. |
| Nomi delle fact e delle dimensioni. | Nell’albero portano il nome della tabella. |
| Il caricamento dei dati non usa ancora il modello. | L’ETL (parte D) non genera ancora chiavi surrogate, versioni SCD2, membri Sconosciuto o la dimensione data a partire da questo modello: il modello descrive il DW, non lo carica. |
Problemi comuni
| Sintomo | Causa | Che cosa fare |
|---|---|---|
| Proponi modello non trova una fact che mi aspetto. | La tabella non ha FK in uscita nel Designer (in un DW sono spesso assenti) o non ha colonne numeriche non chiave. | Aggiungi le FK nel Designer (C4) e ripremi il pulsante: aggiunge solo ciò che manca. |
STAR002 su ogni fact. | Il grain non è mai proposto. | Scrivilo nel pannello Proprietà (H4). |
| Apri nel Query Builder è disattivo. | La query non è semplice (derivate, più fact, calcolo nel tempo, ROLLUP) oppure il Builder non è disponibile. | Usa Apri nell’editor. |
| Chiedo SUM e ottengo AVG o LAST. | La misura è non additiva o semi-additiva (QRY008). | Se la misura è davvero additiva, correggi l’additività nel pannello Proprietà. |
QRY005: dimensione non collegata. | Una delle fact scelte non ha un ruolo verso quella dimensione. | Scegli un attributo di una dimensione comune, oppure collega la fact (H10). |
| Compaiono righe con valori nulli nelle dimensioni. | Fatti senza riga nella dimensione, mantenuti dal LEFT JOIN. | Carica i membri Sconosciuto, oppure attiva Escludi i fatti senza riga di dimensione (H8). |
| Riaprendo lo schema il modello è vuoto. | Lo schema è stato salvato prima di compilare il modello, oppure non è stato salvato dopo. | Il modello vive nel file dello schema: usa Salva schema (C9). |
H16. Collegare l’ETL al modello
Il modello a stella sa quali sono le chiavi surrogate, le chiavi naturali, il grain e le versioni (SCD) di ogni dimensione. La voce ETL → Collegamento al modello a stella… confronta il progetto ETL aperto con il modello dello Schema Designer attivo e segnala che cosa non torna; con Applica correzioni sistema ciò che si può sistemare in automatico.
Che cosa fa
- Fatti: per ogni FK imposta un lookup dalla chiave naturale (campo origine) alla chiave surrogate della dimensione, eseguito sulla destinazione, con valore di ripiego il membro Sconosciuto (−1). Se la dimensione è SCD2 il lookup sceglie la versione corrente.
- Grain: le colonne del grain diventano la chiave di idempotenza della fase del fatto, così rilanciare l’ETL non duplica le righe.
- Dimensioni: la fase scrive in una tabella di staging
STG_<dimensione>(svuotata prima, senza duplicati) e l’SQL dopo l’import inserisce i membri Sconosciuto/Non applicabile e applica SCD1 e SCD2. - Ordine: le fasi delle dimensioni devono precedere quelle dei fatti che le usano.
Lo stesso controllo è eseguito da Valida progetto dopo che la finestra è stata aperta almeno una volta in questa sessione: i messaggi compaiono con il codice ETLSTARnnn.
Esempio: DIM_CUSTOMER (SCD1)
Con chiave naturale CUSTOMER_CODE e attributi di tipo 1, l’SQL generato per Firebird è il seguente. Le istruzioni sono separate dalla riga -- ETL:NEXT, perché il motore ETL ne esegue una per volta.
INSERT INTO "DIM_CUSTOMER" ("CUSTOMER_KEY", "CUSTOMER_CODE", "CUSTOMER_NAME", "SEGMENT") SELECT -1, '-1', 'Sconosciuto', 'Sconosciuto' FROM RDB$DATABASE WHERE NOT EXISTS (SELECT 1 FROM "DIM_CUSTOMER" WHERE "CUSTOMER_KEY" = -1)
-- ETL:NEXT
INSERT INTO "DIM_CUSTOMER" ("CUSTOMER_KEY", "CUSTOMER_CODE", "CUSTOMER_NAME", "SEGMENT") SELECT -2, '-2', 'Non applicabile', 'Non applicabile' FROM RDB$DATABASE WHERE NOT EXISTS (SELECT 1 FROM "DIM_CUSTOMER" WHERE "CUSTOMER_KEY" = -2)
-- ETL:NEXT
UPDATE "DIM_CUSTOMER" SET "CUSTOMER_NAME" = (SELECT STG_."CUSTOMER_NAME" FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE"), "EMAIL" = (SELECT STG_."EMAIL" FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE"), "CITY" = (SELECT STG_."CITY" FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE"), "REGION" = (SELECT STG_."REGION" FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE"), "COUNTRY" = (SELECT STG_."COUNTRY" FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE"), "SEGMENT" = (SELECT STG_."SEGMENT" FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE"), "ACQUISITION_DATE" = (SELECT STG_."ACQUISITION_DATE" FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE") WHERE EXISTS (SELECT 1 FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE" AND ((STG_."CUSTOMER_NAME" <> "DIM_CUSTOMER"."CUSTOMER_NAME" OR (STG_."CUSTOMER_NAME" IS NULL AND "DIM_CUSTOMER"."CUSTOMER_NAME" IS NOT NULL) OR (STG_."CUSTOMER_NAME" IS NOT NULL AND "DIM_CUSTOMER"."CUSTOMER_NAME" IS NULL)) OR (STG_."EMAIL" <> "DIM_CUSTOMER"."EMAIL" OR (STG_."EMAIL" IS NULL AND "DIM_CUSTOMER"."EMAIL" IS NOT NULL) OR (STG_."EMAIL" IS NOT NULL AND "DIM_CUSTOMER"."EMAIL" IS NULL)) OR (STG_."CITY" <> "DIM_CUSTOMER"."CITY" OR (STG_."CITY" IS NULL AND "DIM_CUSTOMER"."CITY" IS NOT NULL) OR (STG_."CITY" IS NOT NULL AND "DIM_CUSTOMER"."CITY" IS NULL)) OR (STG_."REGION" <> "DIM_CUSTOMER"."REGION" OR (STG_."REGION" IS NULL AND "DIM_CUSTOMER"."REGION" IS NOT NULL) OR (STG_."REGION" IS NOT NULL AND "DIM_CUSTOMER"."REGION" IS NULL)) OR (STG_."COUNTRY" <> "DIM_CUSTOMER"."COUNTRY" OR (STG_."COUNTRY" IS NULL AND "DIM_CUSTOMER"."COUNTRY" IS NOT NULL) OR (STG_."COUNTRY" IS NOT NULL AND "DIM_CUSTOMER"."COUNTRY" IS NULL)) OR (STG_."SEGMENT" <> "DIM_CUSTOMER"."SEGMENT" OR (STG_."SEGMENT" IS NULL AND "DIM_CUSTOMER"."SEGMENT" IS NOT NULL) OR (STG_."SEGMENT" IS NOT NULL AND "DIM_CUSTOMER"."SEGMENT" IS NULL)) OR (STG_."ACQUISITION_DATE" <> "DIM_CUSTOMER"."ACQUISITION_DATE" OR (STG_."ACQUISITION_DATE" IS NULL AND "DIM_CUSTOMER"."ACQUISITION_DATE" IS NOT NULL) OR (STG_."ACQUISITION_DATE" IS NOT NULL AND "DIM_CUSTOMER"."ACQUISITION_DATE" IS NULL))))
-- ETL:NEXT
INSERT INTO "DIM_CUSTOMER" ("CUSTOMER_CODE", "CUSTOMER_NAME", "EMAIL", "CITY", "REGION", "COUNTRY", "SEGMENT", "ACQUISITION_DATE") SELECT STG_."CUSTOMER_CODE", STG_."CUSTOMER_NAME", STG_."EMAIL", STG_."CITY", STG_."REGION", STG_."COUNTRY", STG_."SEGMENT", STG_."ACQUISITION_DATE" FROM "STG_DIM_CUSTOMER" STG_ WHERE NOT EXISTS (SELECT 1 FROM "DIM_CUSTOMER" DIM_ WHERE STG_."CUSTOMER_CODE" = DIM_."CUSTOMER_CODE")
Esempio: la stessa dimensione con CITY storicizzata (SCD2)
Con CITY di tipo 2 e le colonne VALID_FROM, VALID_TO, IS_CURRENT: chiude la riga corrente se la città cambia, sovrascrive gli attributi di tipo 1 su tutte le versioni e inserisce le chiavi nuove o chiuse.
UPDATE "DIM_CUSTOMER" SET "VALID_TO" = CURRENT_DATE, "IS_CURRENT" = 0 WHERE "IS_CURRENT" = 1 AND EXISTS (SELECT 1 FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE" AND ((STG_."CITY" <> "DIM_CUSTOMER"."CITY" OR (STG_."CITY" IS NULL AND "DIM_CUSTOMER"."CITY" IS NOT NULL) OR (STG_."CITY" IS NOT NULL AND "DIM_CUSTOMER"."CITY" IS NULL))))
-- ETL:NEXT
UPDATE "DIM_CUSTOMER" SET "CUSTOMER_NAME" = (SELECT STG_."CUSTOMER_NAME" FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE"), "EMAIL" = (SELECT STG_."EMAIL" FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE"), "REGION" = (SELECT STG_."REGION" FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE"), "COUNTRY" = (SELECT STG_."COUNTRY" FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE"), "SEGMENT" = (SELECT STG_."SEGMENT" FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE"), "ACQUISITION_DATE" = (SELECT STG_."ACQUISITION_DATE" FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE") WHERE EXISTS (SELECT 1 FROM "STG_DIM_CUSTOMER" STG_ WHERE STG_."CUSTOMER_CODE" = "DIM_CUSTOMER"."CUSTOMER_CODE" AND ((STG_."CUSTOMER_NAME" <> "DIM_CUSTOMER"."CUSTOMER_NAME" OR (STG_."CUSTOMER_NAME" IS NULL AND "DIM_CUSTOMER"."CUSTOMER_NAME" IS NOT NULL) OR (STG_."CUSTOMER_NAME" IS NOT NULL AND "DIM_CUSTOMER"."CUSTOMER_NAME" IS NULL)) OR (STG_."EMAIL" <> "DIM_CUSTOMER"."EMAIL" OR (STG_."EMAIL" IS NULL AND "DIM_CUSTOMER"."EMAIL" IS NOT NULL) OR (STG_."EMAIL" IS NOT NULL AND "DIM_CUSTOMER"."EMAIL" IS NULL)) OR (STG_."REGION" <> "DIM_CUSTOMER"."REGION" OR (STG_."REGION" IS NULL AND "DIM_CUSTOMER"."REGION" IS NOT NULL) OR (STG_."REGION" IS NOT NULL AND "DIM_CUSTOMER"."REGION" IS NULL)) OR (STG_."COUNTRY" <> "DIM_CUSTOMER"."COUNTRY" OR (STG_."COUNTRY" IS NULL AND "DIM_CUSTOMER"."COUNTRY" IS NOT NULL) OR (STG_."COUNTRY" IS NOT NULL AND "DIM_CUSTOMER"."COUNTRY" IS NULL)) OR (STG_."SEGMENT" <> "DIM_CUSTOMER"."SEGMENT" OR (STG_."SEGMENT" IS NULL AND "DIM_CUSTOMER"."SEGMENT" IS NOT NULL) OR (STG_."SEGMENT" IS NOT NULL AND "DIM_CUSTOMER"."SEGMENT" IS NULL)) OR (STG_."ACQUISITION_DATE" <> "DIM_CUSTOMER"."ACQUISITION_DATE" OR (STG_."ACQUISITION_DATE" IS NULL AND "DIM_CUSTOMER"."ACQUISITION_DATE" IS NOT NULL) OR (STG_."ACQUISITION_DATE" IS NOT NULL AND "DIM_CUSTOMER"."ACQUISITION_DATE" IS NULL))))
-- ETL:NEXT
INSERT INTO "DIM_CUSTOMER" ("CUSTOMER_CODE", "CUSTOMER_NAME", "EMAIL", "REGION", "COUNTRY", "SEGMENT", "ACQUISITION_DATE", "CITY", "VALID_FROM", "VALID_TO", "IS_CURRENT") SELECT STG_."CUSTOMER_CODE", STG_."CUSTOMER_NAME", STG_."EMAIL", STG_."REGION", STG_."COUNTRY", STG_."SEGMENT", STG_."ACQUISITION_DATE", STG_."CITY", CURRENT_DATE, CAST('9999-12-31' AS DATE), 1 FROM "STG_DIM_CUSTOMER" STG_ WHERE NOT EXISTS (SELECT 1 FROM "DIM_CUSTOMER" DIM_ WHERE STG_."CUSTOMER_CODE" = DIM_."CUSTOMER_CODE" AND DIM_."IS_CURRENT" = 1)
Messaggi
| Codice | Significato |
|---|---|
ETLSTAR001 | Una FK della fact non è mappata |
ETLSTAR002/003 | La FK è copiata direttamente, o il lookup punta al posto sbagliato |
ETLSTAR004/005 | Lookup senza valore di ripiego (membro Sconosciuto) o che non sceglie la versione corrente SCD2 |
ETLSTAR006/007 | Rilanciando l’ETL i fatti si duplicano; la chiave di idempotenza non coincide col grain |
ETLSTAR008 | La fase del fatto viene prima di quella della dimensione |
ETLSTAR009-014 | Dimensione scritta direttamente, senza chiavi naturali, staging non svuotato o non deduplicato, chiave naturale o attributo non mappati |
ETLSTAR015-017 | SQL dopo l’import mancante, diverso da quello generato, o non sulla connessione di destinazione |
ETLSTAR018/019 | Dimensione usata ma non caricata da nessuna fase; errore nella generazione dell’SQL |
Che cosa devi fare tu
- Crea nel database di destinazione le tabelle
STG_<dimensione>con le chiavi naturali e gli attributi (lo strumento non genera DDL). - Crea le fasi ETL (una per dimensione verso lo staging, una per fatto) e mappa i campi: le fasi non vengono create in automatico.
- Apri la finestra, leggi le segnalazioni, premi Applica correzioni, salva il progetto ETL.
Limiti
- La chiave surrogate deve essere generata dal database (identity); i membri −1/−2 sono inseriti esplicitamente (in Firebird la colonna identity
BY DEFAULTlo consente). - Il lookup SCD2 sceglie la versione corrente, non quella valida alla data del fatto (nessun point-in-time).
- La chiave naturale dev’essere unica nello staging (la deduplica è impostata dalla correzione automatica). Una dimensione SCD2 non può avere UNIQUE sulla chiave naturale.
- L’SQL è standard (UPDATE/INSERT con sottoquery, niente MERGE) ed è stato provato su DuckDB; le differenze fra dialetti riguardano solo la tabella fittizia, le date e i booleani.
D1. Che cos’è l’ETL
La modalità ETL (Extract, Transform, Load) copia e trasforma i dati da una connessione origine a una connessione destinazione, anche di motori diversi (per esempio da Firebird a Firebird, o da un file CSV a PostgreSQL). Un progetto ETL è fatto di:
- Fasi: ogni fase copia una tabella (o una query) di origine in una tabella di destinazione.
- Regole sui campi: per ogni campo di destinazione si dice da dove viene il valore (copia diretta, costante, espressione, lookup, ecc.).
- Opzioni di esecuzione: svuotare la destinazione, modalità di scrittura, transazioni, gestione degli errori.
- Pianificazione: facoltativa, per eseguire il progetto in automatico.
Il progetto si salva in un file .fdmap; la pianificazione in un file .petl. I menu in modalità ETL sono: File, Impostazioni, ETL e ? (vedi cap. 37).
D2. L’interfaccia
- Barra strumenti ETL (stessi comandi del menu ETL)
- Schede di modalità: ETL attiva
- Filtra fasi… cerca tra fasi e campi
- Espandi / comprimi tutto o la fase corrente
- Regola evidenziata: una trasformazione
- Regola diretta: copia semplice
- Pannello Regola sul campo
- Query iniziale / Query finale della fase
- Anteprima dati: Origine e Destinazione
- Totale record dell’origine
- Fasi ETL pianificate
- Aggiorna l’elenco delle pianificazioni
Leggere l’albero delle fasi
Ogni fase è un nodo che si apre sui suoi campi; ogni riga ha la forma [X] campo_origine -> CAMPO_DESTINAZIONE [regola]:
- [X] indica che il campo è attivo; togliendo la spunta il campo viene saltato.
- Le righe in arancione hanno una trasformazione (tutto tranne Diretto); quelle in bianco sono copie semplici.
- La regola è scritta tra parentesi quadre, con i suoi parametri:
[Costante = -1],[Autoinc (da 1)],[Espressione = CASE(…)],[Lookup CODIFICA: (DESCRIZIONE) -> COD]. - Se c’è una condizione, la riga si chiude con
[Esegui regola solo se: … altrimenti = …]. - Nella riga senza campo origine (
[X] -> ID) il valore non viene dall’origine: è una costante, un autoincrementale o un lookup. - Se manca un campo origine o destinazione, o la connessione non è raggiungibile, un messaggio lo segnala.
In stato vuoto l’albero propone due scorciatoie: Nuova fase e Abbina automaticamente.
D3. Creare un progetto
- Collega le connessioni. Origine e destinazione devono essere già connesse nell’albero. Seleziona la connessione e usa ETL → Connessione origine e Connessione destinazione (dall’albero). Se scegli la stessa connessione per entrambe, il programma ti avvisa.
- Crea le fasi in uno dei modi seguenti.
- Definisci le regole dei campi (D5).
- Salva il progetto (D10) ed esegui (D8).
Tre modi per creare le fasi
| Metodo | Come funziona |
|---|---|
| Nuova fase | Menu ETL → Nuova fase: scegli tabella di origine e di destinazione (o una query personalizzata) e le connessioni. |
| Nuova fase dall’albero | Parte dalla tabella selezionata nell’albero dei database. |
| Abbina automaticamente | Scegli la connessione di origine e di destinazione. Il programma cerca le tabelle con lo stesso nome su entrambe e le elenca con la percentuale di corrispondenza (per esempio "12/15 campi corrispondenti"). Spunti quelle volute e premi Genera fasi: per ognuna crea la fase e una regola Diretto per ogni campo con lo stesso nome. Le tabelle che hanno già una fase sono disabilitate: non si creano mai duplicati. |
Campi
- Genera campi legge i campi dell’origine e crea le regole. Puoi sostituire i campi esistenti e scegliere con Seleziona tutti / Deseleziona tutti quali portare. Una legenda segnala i campi con tipi diversi tra origine e destinazione e avvisa se due righe puntano allo stesso campo di destinazione.
- Aggiungi, modifica, elimina campo: dal menu ETL o dal clic destro. L’eliminazione chiede conferma e funziona anche su più campi selezionati.
- Elimina fase e Svuota tutte le fasi chiedono sempre conferma.
D4. Impostazioni della fase
Dal clic destro sulla fase → Modifica impostazioni si apre una finestra a schede.
| Scheda | Che cosa imposta |
|---|---|
| Sorgente / Destinazione | Connessione di origine e di destinazione (Scegli… oppure Globale, cioè quella del progetto), tabella di origine e di destinazione, Genera campi. Con Query personalizzata l’origine diventa una SELECT scritta da te, oppure scelta tra le query dei tab dell’Editor. |
| Opzioni | Fase attiva (se spenta viene saltata senza eliminarla); Svuota destinazione prima (TRUNCATE / DELETE); per le origini REST, scarica tutte le pagine con un massimo di pagine; Modalità di scrittura; Campi chiave; Filtro WHERE sull’origine. |
| Dedup | Elimina i duplicati sulla base di uno o più campi; con Tieni l’ultimo e un criterio di ordinamento decidi quale riga sopravvive. |
| Idempotenza | Chiave di idempotenza (campi o espressione) per evitare di riscrivere righe già elaborate. Il suggerimento sulla scheda spiega i compromessi. |
| Transazioni | Modalità: Auto o Per blocco (una transazione per ogni blocco di righe, il comportamento storico) oppure Per fase (una sola transazione per tutta la fase). Errore di blocco: Ferma la fase (predefinito) oppure Continua. Troncamento: Consenti, Avvisa (predefinito) o Errore che ferma la fase. |
| Formati | Formato data, separatore decimale e separatore delle migliaia predefiniti, usati quando l’origine contiene testo da convertire (tipico dei CSV). |
| Query iniziale / Query finale | SQL eseguito prima o dopo la fase (per esempio reset di sequenze). Si sceglie se girarlo sulla connessione di origine o di destinazione. Le stesse schede sono nel pannello laterale Regola sul campo (vedi screenshot). |
Modalità di scrittura
La modalità decide come le righe arrivano in destinazione: Inserisci sempre (nessun controllo sulla chiave), Append, Update, Append + Update (aggiorna se esiste, inserisce se manca) e Delete. Le modalità che confrontano le righe con la destinazione richiedono i Campi chiave: se mancano il programma lo segnala prima di partire. I campi chiave vanno indicati con le vere chiavi della tabella di destinazione.
D5. Regole sul campo
- Campo origine e Campo destinazione, con il tipo di ciascuno
- Avviso tipi diversi
- Regola: il tipo di trasformazione
- Espressione e pulsante Assistente…
- Esegui regola solo se: condizione
- Anteprima sui valori reali dell’origine
- Compositore condizioni avanzato (D6)
Si apre con doppio clic su un campo, con Modifica campo, oppure lavori direttamente nel pannello laterale (che ha il pulsante Editor completo). Se il campo di origine e quello di destinazione hanno tipi diversi compare un avviso: valuta una regola Espressione per convertire il valore.
| Regola | Cosa fa |
|---|---|
| Diretto | Copia il valore. In più puoi applicare una azione rapida di pulizia: nessuna, rimuovi testo (togli tutte le occorrenze di un testo, per esempio € prima di scrivere su un campo numerico), sostituisci testo (cerca / sostituisci), maiuscolo, minuscolo, trim. È un solo passo, applicato prima dei formati predefiniti della fase. |
| Costante | Scrive sempre lo stesso valore (per esempio -1 o 100), a prescindere dall’origine. |
| Espressione | Calcola il valore con una formula (vedi sotto). Nell’albero compare come [Espressione = …]. |
| Lookup | Cerca un valore in un’altra tabella. Imposti dove cercare (connessione di origine o di destinazione), la tabella, i campi chiave su cui cercare, il campo (o l’espressione) dell’origine da confrontare, il campo valore da restituire e un valore predefinito se non trova nulla. Esempio nello screenshot: dalla descrizione della via si ricava il codice. Se la tabella di lookup ha più righe per la stessa chiave, si usa l’ultima trovata. |
| Ignora | Il campo non viene scritto. |
| Autoincrement | Numera le righe: parte da un valore iniziale oppure dall’ultimo valore già presente nella destinazione. |
| Formula | Combina più campi dell’origine con un modello che contiene i segnaposto dei campi (per esempio un indirizzo composto da via, numero e civico). Il pulsante Anteprima mostra il risultato su righe vere. |
Espressioni
Il motore delle espressioni è tipizzato e permette di annidare le funzioni. I campi dell’origine si indicano tra graffe, per esempio {CAP}.
- Operatori:
+ - * / %, confronti (= <> < <= > >=),AND,OR,NOT. - Funzioni:
IF,COALESCE,ISNULL,ISBLANK,UPPER,LOWER,TRIM,PROPER,CONCAT,LEFT,RIGHT,SUBSTRING,LENGTH,REPLACE,LPAD,RPAD,ABS, eCASEnelle sue forme. - Il motore accetta anche le funzioni più vecchie (REGEXMATCH, DATE e altre) usate dagli assistenti: l’elenco completo è nell’Assistente.
IF(ISBLANK({CAP}); "00000"; LPAD(TRIM({CAP}); 5; "0"))
CASE({STATO}; "A"; "ATTIVO"; "S"; "SOSPESO"; "ALTRO")
CASE(Permanenti;2;Temporanei;3;1) — forma breve
Il pulsante Assistente… guida nella scelta della funzione e nei suoi argomenti, e Esempi propone modelli pronti (anche per le espressioni regolari). Nell’Anteprima sui valori (screenshot) vedi per ogni valore reale dell’origine il risultato che verrebbe scritto, per esempio Permanenti → 2, Temporanea → 1.
D6. Esegui la regola solo se…
Ogni regola può avere una condizione: se è vera si applica la regola, altrimenti si scrive un valore alternativo. Spunta Esegui regola solo se e imposta:
- Campo da controllare (può essere diverso dal campo origine della regola),
- Tipo di condizione e Valore,
- Nega condizione (inverte il risultato),
- Se la condizione è falsa: un valore fisso (vuoto =
NULL), il contenuto di un altro campo dell’origine o una formula.
| Gruppo | Condizioni |
|---|---|
| Contenuto | Vuoto · Non vuoto · Solo spazi · Solo cifre · Solo lettere (accenti compresi) · Alfanumerico (almeno una lettera e una cifra) |
| Testo | Inizia con · Contiene · Termina con · Uguale · Diverso (senza distinzione tra maiuscole e minuscole) |
| Lunghezza | Lunghezza uguale · maggiore · minore |
| Numeri | Maggiore · minore · uguale (accetta virgola e punto) |
| Altro | Espressione regolare · Data valida nel formato indicato (per esempio dd/mm/yyyy) |
Compositore condizioni avanzato
Per le trasformazioni "se… allora…" con più condizioni il pulsante Compositore (o Apri compositore) costruisce per te un’espressione CASE:
- Scegli Campo, Operatore e Confronta con e premi Aggiungi condizione.
- Ripeti per aggiungere altre condizioni allo stesso ramo; decidi se devono essere tutte vere (E) o basta una (O).
- Scrivi il Risultato se il ramo è vero (oppure inseriscilo da un campo) e premi Conferma ramo.
- Aggiungi altri rami: compaiono in Rami già aggiunti; puoi rimuovere condizioni o rami.
- Indica l’Altrimenti (valore di default) e controlla l’Anteprima espressione prima di confermare con OK.
D7. Guardare i dati
Mentre costruisci le regole puoi consultare i dati reali:
- Pannello in basso: due schede, Origine e Destinazione, che seguono la fase selezionata. Mostra i dati in sola lettura e, a destra, il Totale record dell’origine (nello screenshot, 489). I dati arrivano a blocchi, senza caricare tutta la tabella.
- Finestra indipendente: clic destro sulla fase → Visualizza dati. Non segue la selezione: è comoda su un secondo schermo per confrontare una fase precisa.
D8. Eseguire
| Azione | Come |
|---|---|
| Eseguire tutto il progetto | Menu ETL → Esegui oppure F9. Le fasi disattivate vengono saltate. |
| Provare una sola fase | Clic destro sulla fase → Esegui fase. |
| Interrompere | ETL → Annulla, o il pulsante Annulla della finestra di avanzamento. |
Durante l’esecuzione una finestra mostra la fase corrente, una barra di avanzamento (definita se il numero di righe è noto, indeterminata in caso contrario) e un registro con inizio e fine di ogni fase, record letti e scritti, ed eventuali errori. L’interfaccia resta reattiva.
Funzioni di sicurezza
- Controllo dello schema: con Registra baseline schema (menu della fase) il programma memorizza la struttura attuale di origine e destinazione e può segnalare quando in seguito cambia, per esempio se una colonna viene rinominata.
- Ripresa dopo interruzione (checkpoint): per una fase molto lunga si può indicare un campo di ripresa sull’origine; un file di checkpoint, salvato accanto al progetto, ricorda a che punto si era arrivati, così un’esecuzione interrotta riparte da lì invece che dall’inizio. Non è compatibile con la deduplica della stessa fase.
- Errori: ogni errore riporta fase, campo e riga, e una categoria (configurazione, connessione, trasformazione, scrittura, idempotenza, checkpoint, REST).
D9. Pianificare l’esecuzione
Per eseguire il progetto a orari fissi, senza aprire PlyxSQL a mano, usa il clic destro sulla fase → Pianifica (oppure ETL → Salva per il servizio). Si apre la finestra della pianificazione:
| Campo | Significato |
|---|---|
| Connessioni | Origine e destinazione. Il progetto deve avere le connessioni salvate: altrimenti il programma te lo segnala. |
| Frequenza | Ogni ora · Giornaliera · Settimanale · Mensile · Fine settimana · Fine mese |
| Intervallo, Ora | Ogni quanto ripetere l’esecuzione e a che ora |
| Giorno della settimana / del mese | Per Settimanale e Mensile. Il giorno del mese ha una nota per i mesi più corti |
| Recupera esecuzione mancata | Se il computer era spento all’orario previsto, l’esecuzione parte appena possibile |
Il pulsante Salva scrive un file .petl nella cartella delle pianificazioni. I file .petl li esegue lo scheduler (TFDPetlScheduler), che può girare dentro un’applicazione, in un servizio Windows o in un programma da console:
- Controlla la cartella subito all’avvio, non solo allo scadere del timer: un file già scaduto parte appena l’host riparte.
- Non esegue mai due scansioni sovrapposte.
- Se più processi (per esempio l’applicazione e il servizio) guardano la stessa cartella, un meccanismo di blocco evita che lo stesso file giri due volte.
In fondo alla finestra il pannello Fasi ETL pianificate (N) elenca i file .petl presenti nella cartella: per ciascuno il nome del progetto, la frequenza e il numero di fasi. Aggiorna rilegge la cartella (la lettura avviene in background, senza bloccare l’interfaccia).
D10. Menu, salvataggio e stampa
| Voce | Effetto |
|---|---|
| ETL → Nuova fase / Nuova fase dall’albero | Crea una fase |
| ETL → Abbina automaticamente | Crea le fasi per le tabelle omonime |
| ETL → Modifica / Elimina fase, Svuota tutte le fasi | Gestione fasi |
| ETL → Nuovo / Modifica / Elimina / Genera campi | Gestione campi |
| ETL → Connessione origine / destinazione (dall’albero) | Assegna la connessione selezionata nell’albero |
| ETL → Salva / Carica progetto | File .fdmap |
| ETL → Salva per il servizio | Salva il progetto per l’esecuzione da servizio (con pianificazione) |
| ETL → Esegui (F9) / Annulla | Esecuzione |
Il clic destro sulla fase offre in più: Modifica impostazioni, Genera campi, Esegui fase, Visualizza dati, Registra baseline schema, Pianifica, Espandi tutto, Comprimi tutto e Stampa tutte le fasi. Quest’ultima apre un’anteprima ridimensionabile con l’elenco completo di fasi e regole, con i pulsanti Stampa e Salva su file: utile come documentazione del mapping.
Se un campo origine o destinazione citato da una regola non esiste più, o una connessione del progetto non è raggiungibile, l’apertura del progetto ti avvisa e ti permette di riconnettere a mano.
D11. Suggerimenti con l’AI
Con il servizio AI configurato (File → Configurazione AI):
- Suggerisci campi: propone gli abbinamenti tra campi di origine e destinazione e aggiorna quelli già presenti.
- Genera espressione: nell’Assistente descrivi a parole cosa vuoi ottenere e, se serve, fornisci un esempio di valore; il programma propone l’espressione.
E1. A che cosa serve il Profiler
La scheda Performance - Profiler misura quanto è veloce una query o una stored procedure. Ogni esecuzione diventa una barra in un grafico colorato in base alla durata, con il piano di esecuzione del database quando il motore lo permette. Così vedi subito quali query rallentano e puoi confrontare prima e dopo un’ottimizzazione (per esempio dopo aver aggiunto un indice).
Il Profiler lavora sulla connessione attiva dell’albero e ne usa il dialetto. Ogni misura riporta anche il colore di accento della connessione, così distingui a colpo d’occhio le query provenienti da database diversi.
INSERT, UPDATE, DELETE e DDL: non c’è un rollback automatico. Per provare una scrittura, avvia prima una transazione (Tx) e chiudila con RB, oppure lavora su un database di prova.E2. Che cosa viene misurato
| Tipo di istruzione | Cosa si misura |
|---|---|
SELECT, WITH, SHOW, PRAGMA, EXPLAIN | Il tempo di esecuzione (apertura e primo blocco di righe), poi il numero di righe. Contare le righe può obbligare il driver a leggerle tutte: quel costo è mostrato a parte come fetch e non gonfia il tempo principale. |
Altre istruzioni (INSERT, UPDATE, DELETE, DDL…) | Il tempo di esecuzione e le righe interessate. Il piano non viene richiesto, salvo che tu abbia abilitato l’analisi anche sulle scritture (vedi E6). |
| Stored procedure | Tempo e righe. Per le procedure il piano non viene catturato. |
| Esecuzione in errore | Il tempo fino all’errore e il messaggio del database. Nessun piano. |
E3. Soglie e colori
| Esito | Quando | Aspetto della barra |
|---|---|---|
| Buona | meno di 150 ms | Verde |
| Attenzione | da 150 ms a meno di 600 ms | Ambra, con un piccolo indicatore di forma |
| Critica | 600 ms o più | Rossa, con indicatore di forma |
| Errore | la query è fallita | Bordo rosso tratteggiato e icona ! |
Le soglie (150 e 600 ms) sono i valori predefiniti e si possono cambiare, così come i colori. Oltre al colore c’è sempre un indicatore di forma, utile a chi distingue male rosso e verde.
E4. Il grafico
- Ogni esecuzione è una barra; la più recente è a destra. Se la barra ha due segmenti impilati, il secondo è il costo del fetch completo (
(+N ms fetch)). - Restano visibili le ultime 25 barre (impostabile): quando ne arriva una nuova, la più vecchia esce dal grafico.
- Mentre una query è in esecuzione compare una barra fantasma pulsante; al termine si trasforma nella barra vera, con una breve animazione.
- In alto quattro indicatori (KPI): ULTIMA ESECUZIONE, MEDIA, MIN / MAX e QUERY PROFILATE.
- La legenda spiega i colori: Buona, Attenzione, Critica, Errore.
- Prima della prima misura il grafico mostra un messaggio che invita a profilare una query.
E5. Esaminare una misura
- Passa il mouse su una barra: un suggerimento mostra l’SQL abbreviato, il tempo (con eventuale fetch), le righe, il dialetto (badge) e, per le procedure, l’etichetta stored procedure.
- Clicca una barra per selezionarla: si apre il pannello di dettaglio con l’SQL, il dialetto, la data e l’ora (
gg/mm/aaaa hh:mm:ss), tempo, righe (n/dse non disponibili) e il piano di esecuzione in un riquadro a larghezza fissa. Per le query in errore compare l’etichetta ERRORE e il messaggio. - Rotella del mouse sul grafico con una barra selezionata: scorre il piano, tre righe per scatto.
- Tastiera: il grafico prende il fuoco con un riquadro dedicato; ← e → spostano la selezione tra le barre, Invio o Spazio la confermano.
E6. Il piano di esecuzione
Il formato dipende dal motore: ognuno usa il proprio meccanismo.
| Motore | Come si ottiene il piano |
|---|---|
| PostgreSQL | EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON): tempi reali, ma la query viene eseguita una seconda volta. |
| MySQL | EXPLAIN FORMAT=JSON: non riesegue la query. |
| SQL Server | SHOWPLAN_XML: compila senza eseguire e restituisce un documento XML, apribile come .sqlplan in SSMS. I comandi SET girano su una connessione di servizio clonata, così la tua sessione non cambia. |
| SQLite | EXPLAIN QUERY PLAN |
| Oracle | EXPLAIN PLAN con visualizzazione DBMS_XPLAN (formato TYPICAL). Usa la PLAN_TABLE con un identificatore proprio e la ripulisce a fine lettura. Se la tabella manca, il messaggio indica la causa. |
| Firebird | Firebird non ha un EXPLAIN SQL: il piano si legge dalle tabelle di monitoraggio MON$ (MON$COMPILED_STATEMENTS), disponibili dalla versione 5. Sulle versioni precedenti il piano non è disponibile. |
| InterBase, DB2, Informix, MS Access | Nessun piano: si misurano solo tempo e righe. |
- Il piano è un extra: se non si riesce a ottenerlo la misura resta valida e nel dettaglio compare
[piano non disponibile]con il motivo. - Viene richiesto solo per istruzioni di lettura. Per
INSERT/UPDATE/DELETEserve abilitare l’opzione di analisi sulle scritture (disattivata di default), perché su alcuni motori richiederebbe di eseguire di nuovo l’istruzione. - Un
;finale nel testo viene rimosso prima di chiedere il piano (su Oracle causerebbe un errore).
E7. Storico ed esportazione
Il Profiler conserva in memoria le ultime 200 misure (le più vecchie escono per prime; impostabile, 0 = illimitato). L’elenco si può salvare in un file CSV (separatore ;) con le colonne Timestamp, Dialect, IsStoredProc, ElapsedMs, FetchAllMs, RowsAffected, Severity, SQL ed Error: utile per confrontare più sessioni di ottimizzazione in un foglio di calcolo.
E8. Esecuzione in background
Le misure possono girare su una connessione gemella in un thread di sfondo: l’interfaccia non si blocca, e il risultato compare nel grafico a fine esecuzione. Si può avviare una sola profilazione alla volta; un’altra richiesta, mentre la prima è in corso, viene rifiutata con un messaggio. L’interruzione è "best effort": dipende dal driver e, se non è supportata, la misura termina comunque da sola.
F1. Che cos’è l’Analisi
La scheda Analisi trasforma il risultato di una query in un grafico: barre, linee, torta, radar, mappe, treemap e altri 19 tipi in tutto. Serve a vedere i dati senza dover esportare in Excel. Dal grafico puoi poi salvare l’immagine, il PDF o un file Excel.
In modalità Analisi i menu diventano File, Impostazioni, Analytics e ?; Builder, Designer ed ETL sono nascosti. Il pannello è autonomo: ha un proprio elenco di colonne e una propria configurazione.
F2. Dalla query del Builder al grafico
I dati dell’Analisi sono sempre quelli di una query. Il modo più rapido per prepararla è il Builder:
- Tab della connessione su cui gira la query (qui
CSV_Conn, una connessione LocalSQL su CSV) - Tabella nel diagramma, con i campi selezionati
- SQL generato nell’Editor
- Contatore del risultato:
45 righe x 3 col [0 ms] - Griglia dei risultati
- Scegli la connessione con il suo tab (cap. 11) e aggiungi la tabella con doppio clic dall’albero (cap. 3). Nell’esempio:
POPOLAZIONE_EUROPA, con tre campi (codice_iso,paese,popolazione). - Prepara le colonne che servono al grafico: una colonna di etichette (la X) e una o più colonne numeriche (le Y). Aggiungi filtri,
GROUP BYe aggregati nel Builder: i grafici disegnano ciò che la query restituisce, quindi la query deve già dare i dati nella forma finale (fa eccezione l’istogramma, che raggruppa da solo). - Esegui con Run. Controlla in griglia che le righe siano quelle attese (
45 righe x 3 col). - Passa alla scheda Analisi (clic sulla scheda in alto). L’Analisi prende il risultato della query attiva nell’Editor, cioè quella appena eseguita: scegli tipo di grafico, colonna X e colonne Y (F3).
F3. L’interfaccia
- Esporta ▾: PNG, SVG, PDF, CSV, Excel
- Copia immagine negli appunti
- Salva ▾ / Carica ▾: configurazione o analisi completa
- Aggiorna: rilegge i dati
- Risoluzione (1x, 2x, 3x)
- Titolo del grafico
- Tipo grafico
- Colonna X (etichette)
- Colonne Y (valori): una o più colonne
- Opzioni di visualizzazione
- Formato numerico per colonna
- Grafico (qui un radar: ogni raggio è un paese, la distanza dal centro è la popolazione)
- Legenda
Il pannello a sinistra mostra solo i controlli utili al tipo di grafico scelto: cambiando tipo le sezioni non pertinenti spariscono e quelle rimaste si compattano senza vuoti. Tutte le modifiche si vedono subito.
- Tipo grafico, Colonna X e Colonne Y sono la base: la X dà le etichette, le Y i valori.
- Opzioni: Mostra legenda, Griglia, Mostra valori (scrive il valore su barre e punti), Etichette verticali (utile con molte categorie) e Tooltip al passaggio mouse.
- Titolo e Risoluzione (1x, 2x, 3x) restano nella barra in alto, perché valgono per l’intero grafico e non per una singola colonna.
F4. I tipi di grafico
| Tipo | Colonne necessarie |
|---|---|
| Barre · Barre impilate · Linee · Area · Combo | X = etichette, una o più Y. Combo: ogni serie può essere barra o linea e usare l’asse Y di destra. |
| Torta · Radar | X = etichette, Y = valori |
| Istogramma | Una sola colonna Y (la prima), la X è ignorata. Il grafico crea da solo gli intervalli (da 2 a 100) e conta i valori in ciascuno: non serve aggregare nella query. |
| Dispersione (scatter) · Bolle | X = colonna numerica (ogni riga è un punto nella sua posizione vera); una o più Y. Per le bolle scegli anche la colonna Dimensione bolla; senza dimensione si comportano come la dispersione. |
| Candele (candlestick) | X = etichetta (di solito la data) e esattamente 4 serie nell’ordine apertura, massimo, minimo, chiusura. L’ordine segue quello delle colonne della query: esponile così nel Builder. |
| Box plot | X = categoria, una Y = valore. Il programma calcola minimo, primo quartile, mediana, terzo quartile e massimo per ogni categoria. |
| Heatmap | X = colonna categoria (asse orizzontale), Riga heatmap = categoria sull’asse verticale, Y = valore che dà il colore della cella. |
| Cascata (waterfall) | X = categoria, Y = variazione (positiva o negativa). Il grafico aggiunge in coda la barra Totale. |
| Funnel (imbuto) | X = fase, Y = valore. La prima fase vale il 100% e le successive sono proporzionali. |
| Mappa (coropletica) | X = codice dell’area, Y = valore (vedi F6). |
| Treemap | X = etichetta, Y = valore (area del rettangolo). Facoltativo: Gruppo treemap, una seconda colonna che raggruppa i rettangoli in riquadri colorati. |
| Sparkline | X = etichette, più colonne Y: ognuna diventa una corsia compatta, senza assi, con l’ultimo punto evidenziato e minimo/massimo annotati. Adatta a riassunti con più metriche. |
| Sankey | Colonne Sorgente e Destinazione (i nodi) e Y = flusso. Un solo salto: per più passaggi serve una query per ogni coppia. |
codice_iso, la Y è popolazione. Nella lista delle Y compaiono tutte le colonne della query: selezionane solo quelle numeriche.F5. Opzioni di analisi
| Opzione | Effetto | Vale per |
|---|---|---|
| Evidenzia outlier | Cerchia i punti oltre 2 deviazioni standard dalla media della serie | Barre, Linee |
| Linea di tendenza | Regressione lineare sovrapposta alla serie | Tipi con asse cartesiano |
| Media mobile (N periodi) | Linea tratteggiata più chiara per ogni serie visibile. 0 = disattivata | Barre, Barre impilate, Linee, Area, Combo |
| Soglia (valore + etichetta) | Linea orizzontale tratteggiata con etichetta, per esempio un obiettivo mensile | Tipi con asse Y lineare (non torta, radar, mappe, heatmap, funnel, treemap, sparkline, Sankey) |
| Intervalli istogramma | Numero di intervalli (2–100) | Istogramma |
| Max punti | Oltre questo numero il grafico semplifica i dati e segnala dati aggregati. 0 = valore predefinito | Tutti |
Quando il grafico ha semplificato i dati, un singolo punto rappresenta un gruppo di righe: tienilo presente se usi il grafico per risalire a una riga precisa.
F6. Mappe e densità
- Livello mappa: Regioni o Province
- File mappa (cartella
mappe) e pulsante per rileggere la cartella - Densità (KDE) al posto delle regioni
- Colori della scala: bassa, media, alta densità
- Scala dei colori con minimo e massimo
- Classifica dei valori (con "+N altre")
- Zoom: "zoom attivo — doppio click per reset"
La mappa colora ogni area in base al valore. Per usarla:
- Nel Builder prepara una query con una colonna codice e una colonna valore (nell’esempio
codice_isoepopolazione). - Scegli il tipo Mappa (Choropleth), la colonna del codice come X e il valore come Y.
- Scegli il File mappa tra quelli trovati nella cartella
mappeaccanto al programma (nell’esempioeurope.geojson). Se aggiungi un file mentre il programma è aperto, premi il pulsante di aggiornamento accanto all’elenco.
- I codici si confrontano senza distinguere maiuscole e minuscole e accettano sia i codici ISTAT numerici (Italia: regioni 1–20, province 1–107; per esempio Roma = 58, Milano = 15) sia i codici ISO a due lettere (
IT,FR,US…). - Per default il programma cerca
italy_regions.geojsonoitaly_provinces.geojson(a seconda del Livello mappa). Qualsiasi altro file.geojsoncon le proprietàcodeename(Europa, Mondo, o i tuoi confini) compare da solo nell’elenco. I file non sono inclusi: vanno forniti a parte. - Con Densità (KDE) la mappa non colora le aree ma mostra una nuvola di densità di punti geografici: servono le colonne Longitudine e Latitudine (e, facoltativo, un peso).
- Colori mappa/heatmap: tre campioni (bassa, media, alta densità). Un clic apre il selettore di colore; valgono anche per la heatmap.
- Zoom e spostamento con il mouse; il doppio clic riporta alla vista iniziale.
F7. Formato dei numeri
Nella sezione Formato numerico colonna scegli una colonna e il formato con cui mostrarne i valori:
| Impostazione | Effetto |
|---|---|
| Formato | Automatico (K/M) (predefinito: 91.8M, 764…), Numero, Valuta o Percentuale |
| Decimali | Numero di cifre decimali |
| Separatore migliaia | Attiva il punto delle migliaia |
| Simbolo valuta | Per il formato Valuta; vuoto = € |
Premi Applica formato a colonna: la colonna compare nell’elenco Colonne formattate. Il formato vale in ogni punto in cui la colonna è mostrata come numero: etichette dei valori, assi, tooltip, legenda, CSV ed export SVG. Si può formattare una colonna alla volta, e il formato resta anche se cambi tipo di grafico o colonne Y.
F8. Esportare, copiare e salvare
| Pulsante | Risultato |
|---|---|
| Esporta ▾ → PNG | Immagine del grafico. Il selettore Risoluzione (1x, 2x, 3x) regola la definizione delle immagini |
| Esporta ▾ → SVG | Immagine vettoriale (testo XML) |
| Esporta ▾ → PDF | Documento PDF con il grafico |
| Esporta ▾ → CSV | I dati del grafico, con i formati scelti |
| Esporta ▾ → Excel | File .xlsx; se possibile con il grafico incluso, altrimenti solo i dati: un messaggio ti dice cosa è stato salvato |
| Copia immagine | Mette il grafico negli appunti, senza finestra di salvataggio: ideale per incollarlo in Word o PowerPoint |
Salvare l’analisi
| Voce | Cosa salva |
|---|---|
Salva ▾ → solo configurazione (.fdcfg) | Tipo di grafico, colonne, colori, formati, trend e soglia. Non la connessione né la query: va applicata a una query già aperta con la stessa struttura. |
Salva ▾ → analisi completa (.fdanalysis) | Tutto: parametri di connessione, testo SQL e configurazione. La password, se c’è, è protetta con Windows (DPAPI) e non è mai scritta in chiaro. |
| Carica ▾ → configurazione / analisi completa | La configurazione si riapplica alla query corrente. L’analisi completa apre una connessione e una query proprie, le esegue e applica la configurazione, tutto in un colpo. |
.fdanalysis con password su un’altra macchina o un altro utente, la password non è leggibile e l’apertura fallisce con un messaggio chiaro.Riaprire un’analisi dalla schermata iniziale
Le analisi complete (.fdanalysis) salvate in una cartella compaiono nella schermata iniziale come riquadri con l’anteprima. Un clic su un riquadro apre solo quell’analisi: connessione e query vengono ricreate e le altre schede (Tables, Builder, Designer, ETL, Profiler), l’albero e i menu vengono nascosti. Premi F10 per tornare alla schermata iniziale. L’ultima cartella usata si ricorda da sola tra una sessione e l’altra.
Il menu Analytics in alto ripete le stesse azioni: Aggiorna (F5), esporta PNG, SVG e CSV, salva e carica la configurazione.
F9. Aggiornare i dati
Aggiorna riesegue la query e ridisegna il grafico. L’operazione gira in background su una copia della connessione: la schermata non si blocca e il pulsante cambia in Aggiornamento… finché non finisce. Un clic mentre un aggiornamento è in corso viene ignorato, non messo in coda. Se la connessione non è disponibile o la query dà errore compare un messaggio.
F10. Interagire con il grafico
- Passa il mouse su un dato (se Tooltip è attivo) per vedere etichetta e valore, nel formato scelto.
- Clic sulla legenda: mostra o nasconde la serie corrispondente.
- Sulle mappe: zoom e spostamento con il mouse, doppio clic per tornare alla vista iniziale.
F11. Problemi comuni
| Sintomo | Causa e rimedio |
|---|---|
| Il grafico è vuoto | La query non ha restituito righe, oppure le colonne Y scelte non sono numeriche. Controlla la griglia nel Builder o nell’Editor. |
| Troppe barre, illeggibile | Aggrega o filtra nella query, o usa TOP / LIMIT. |
| Le candele sono sbagliate | Servono 4 colonne esattamente nell’ordine apertura, massimo, minimo, chiusura: riordinale nella query. |
| La mappa è vuota o poche aree sono colorate | I codici della query non corrispondono a quelli del file GeoJSON (per esempio ISTAT numerico contro ISO a due lettere), oppure manca il file nella cartella mappe. |
| "Nessuna connessione" all’aggiornamento | La connessione della query non è aperta: connettila dall’albero e riprova. |
| Riaprendo un’analisi con password non parte | Il file è stato salvato su un altro computer o con un altro utente Windows (vedi F8). |
1. Cos’è il Builder
Il Builder è il generatore visuale di query di PlyxSQL. Ogni tabella è un nodo sul canvas, le relazioni sono linee tra i campi e l’SQL viene ricalcolato a ogni modifica. Non serve scrivere una riga di codice per SELECT, JOIN, WHERE, GROUP BY, CTE, subquery e funzioni di finestra.
Il codice generato si adatta al dialetto della connessione attiva (Firebird, PostgreSQL, SQL Server, MySQL e gli altri supportati): le opzioni che il dialetto non prevede, per esempio certi tipi di JOIN o lock, vengono disabilitate e marcate come non disponibili.
2. L’interfaccia
- Barra comandi: esecuzione, salvataggio, ERD, Explain… (cap. 9)
- Tab: una riga per connessione e una per le query (cap. 11)
- Nodo tabella: nome, alias e campi (cap. 4)
- Ricerca campo dentro il nodo
- Relazione tra due campi: JOIN (cap. 5)
- Contatore campi visibili / totali, con frecce di scorrimento
- Pannello SQL Avanzato (cap. 8)
- Minimap per orientarsi in diagrammi grandi
- Zoom − / percentuale / +
- Pulsanti d’intestazione del nodo: ◉ ✓ □ ×
Sotto il Builder trovi l’Editor SQL, che mostra la query generata. Il pulsante [QB] Builder nella sua barra riporta l’attenzione sul Builder.
3. Aggiungere tabelle
Con una connessione attiva, fai doppio clic su una tabella nell’albero a sinistra: viene aggiunta al Builder, nella tab della connessione corrente.
In alternativa, il pulsante Schema della barra comandi importa lo schema dalla connessione attiva. Le tabelle già presenti nel diagramma si possono duplicare (Duplicate table node, o Ctrl+D) e rinominare con un alias.
4. Il nodo tabella
Intestazione
Mostra schema.tabella e, se impostato, l’alias tra parentesi. Se alla tabella è applicato un lock o un hint, compare tra parentesi quadre (per esempio [FOR UPDATE]). Un ⚑ segnala un commento di tabella. Da destra a sinistra i pulsanti sono:
| Pulsante | Funzione |
|---|---|
| × | Rimuove la tabella dal diagramma (e le sue relazioni). |
| □ | Deseleziona tutti i campi della tabella: nessuno finisce nella SELECT. |
| ✓ | Seleziona tutti i campi della tabella. |
| ◉ | Mostra o nasconde i valori del primo record accanto ai campi (richiede connessione). |
Campi
- Ogni riga mostra nome e tipo (per esempio
CHAR(120)); le chiavi primarie hanno il badge PK. - Un clic sul campo lo include o lo esclude dalla
SELECT: i campi selezionati sono in grassetto. - Doppio clic sul campo imposta l’alias di colonna (
AS); sull’intestazione imposta l’alias di tabella; sul bordo destro dell’intestazione il commento di tabella. - Piccoli badge sul campo indicano
CASE WHEN, funzione finestra, espressione calcolata, funzione scalare, commento e alias. - La barra cerca campo… filtra i campi di quel nodo: utile con tabelle da decine di colonne.
- Se la tabella ha più campi di quelli visualizzabili, compaiono le frecce ▲ ▼ e il contatore (nell’esempio
1-10/50); anche la rotella del mouse sul nodo scorre i campi. - Trascina il bordo destro del nodo per cambiarne la larghezza.
5. Relazioni e JOIN
Ogni campo ha un pallino sul bordo del nodo. Per creare un JOIN:
- Premi sul pallino del campo di partenza (lato destro) e trascina: segue il mouse una linea provvisoria.
- Rilascia sul campo dell’altra tabella.
- Nel popup JOIN type scegli il tipo di unione.
| Tipo | Note |
|---|---|
| INNER JOIN | Solo le righe con corrispondenza in entrambe le tabelle. |
| LEFT / RIGHT / FULL JOIN | Mantengono le righe senza corrispondenza di un lato o di entrambi. |
| CROSS JOIN | Prodotto cartesiano. |
| CROSS APPLY / OUTER APPLY | Tipici di SQL Server. |
| JOIN LATERAL | Tipico di PostgreSQL. |
Il popup riporta il nome del dialetto; le voci non supportate sono disabilitate. La relazione appare come una curva tra i due campi (visibile nell’esempio tra IDUBICAZIONE e CODICE). Selezionala e premi Canc per eliminarla; Esc annulla una relazione in corso.
Self-join e alias duplicati
Dal menu del campo, Add self-join (same table, new alias)… aggiunge la stessa tabella con un nuovo alias. Quando due tabelle hanno colonne con lo stesso nome, Auto-alias duplicate columns (JOIN)… (o il pulsante Auto-a,b… nel pannello) assegna gli alias automaticamente.
6. Campi, aggregati e ordinamento
Tutto si imposta dal menu contestuale del campo (cap. 7) oppure, più in fretta, dalla riga corrispondente nel pannello SQL Avanzato. Quando usi un aggregato, i campi non aggregati vanno in GROUP BY: puoi marcarli a mano oppure scegliere la modalità ROLLUP, CUBE o GROUPING SETS dalle opzioni del pannello.
7. Menu contestuale del campo
Clic destro su un campo. L’intestazione del menu riporta TABELLA.CAMPO (tipo).
| Voce | Effetto |
|---|---|
| Aggregates | No aggregation, COUNT, COUNT DISTINCT, SUM e AVG (solo campi numerici), MIN, MAX, STRING_AGG / LISTAGG / GROUP_CONCAT. |
| Add WHERE condition… | Filtro guidato su quel campo. |
| Add WHERE condition (RAW)… | Espressione libera. |
| WHERE summary… | Riepilogo del WHERE, modificabile a mano. |
| Sort order (ORDER BY) | None, ASC, DESC. |
| Select / Deselect / GROUP BY | Includi o escludi dalla SELECT; raggruppa per questo campo. |
| Add CASE WHEN… | Editor di espressione condizionale (con Edit / Remove se già presente). |
| Add OVER (window function)… | Funzione di finestra (con Edit / Remove). |
| Computed expression | COALESCE, NULLIF, IIF, espressione SQL libera. |
| Add self-join… | Vedi cap. 5. |
| Analyze field… | Statistiche della colonna. |
| Set field comment… | Commento sul campo (Edit / Remove). |
| Add scalar function… | Procedura guidata per TRIM, CAST, funzioni di data ecc. (Edit / Remove). |
| Lock / hint tabella | Eredita dalla query oppure lock specifico della tabella (NOLOCK, UPDLOCK, FOR UPDATE, FOR SHARE, SKIP LOCKED). Le voci non applicabili al dialetto sono disabilitate; il testo di hint è abilitato solo per SQL Server e MySQL. |
| Duplicate table node | Duplica l’intero nodo. |
| Auto-alias duplicate columns… | Alias automatico sulle colonne omonime. |
8. Pannello SQL Avanzato
È la colonna a destra del canvas. Le sezioni si aprono e chiudono con un clic sul titolo; la linguetta ◄ ► sul bordo comprime l’intero pannello per recuperare spazio.
| Sezione | Contenuto e azioni |
|---|---|
| Alias Tabelle | Elenco delle tabelle con l’alias corrente (o nessun alias). Clic sulla matita ✎ per modificarlo. |
| Campi & Aggregati | Una riga per campo, con prefisso di tre lettere della tabella (nell’esempio SBU.IDUTENTE). Clic sul bordo sinistro: seleziona/deseleziona. Clic al centro: scorre gli aggregati (nessuno → COUNT → COUNT DISTINCT → SUM → AVG → MIN → MAX). Clic sul badge GB: GROUP BY. Clic all’estremità destra: ordinamento ↑ / ↓ / nessuno. |
| GROUP BY / HAVING | I campi raggruppati e la riga HAVING: un clic apre la finestra di modifica. |
| CTE (WITH … AS) | Elenco delle CTE con il numero tra parentesi; + Aggiungi CTE apre l’editor con nome, corpo, opzioni ricorsiva e materialized. |
| Opzioni | DISTINCT, TOP / LIMIT, OFFSET, RETURNING, modalità del GROUP BY (plain, ROLLUP, CUBE, GROUPING SETS), lock di query. In fondo: + Nota (annotazione sul canvas), + Subq. (subquery), Auto-a,b… (alias automatici). |
| WHERE Builder | + Condizione e + Gruppo AND/OR costruiscono un albero di filtri. La matita ✎ apre il riepilogo del testo completo, dove si può passare alla modalità manuale: l’albero visuale viene ignorato e vale il testo scritto. Clear WHERE azzera tutto. |
| SQL Preview | Anteprima dell’SQL generato, con colorazione delle parole chiave. |
9. Barra comandi
| Pulsante | Azione | Requisiti |
|---|---|---|
| Run | Genera l’SQL, lo porta nell’Editor ed esegue. | Connessione attiva |
| Schema | Importa lo schema dalla connessione. | Connessione |
| Clear | Svuota il diagramma, previa conferma. Si può annullare con Undo. | — |
| Save / Load | Salva e carica il diagramma in un file .json. Se il file non è valido il diagramma corrente resta invariato. | — |
| Stampa il diagramma su più pagine. | — | |
| Undo / Redo | Annulla e ripristina; ogni azione sul modello è un singolo passo. | — |
| SQL | Copia l’SQL generato negli appunti. | — |
| Fit | Adatta lo zoom per mostrare tutto il diagramma. | — |
| ERD | Alterna la vista Builder e la vista diagramma entità-relazione. | — |
| DDL | Mostra lo script DDL del diagramma. | — |
| AI | Genera la query da una richiesta in linguaggio naturale. | Servizio AI configurato |
| Perf | Performance Advisor: suggerimenti sulla query. | — |
| Snip | Libreria di snippet. | — |
| Export | Esporta il diagramma in PNG, SVG, HTML o Markdown. | — |
| Tabs | Aggiunge un nuovo tab di query (chiede il nome). | — |
| Subq | Inserisce un nodo subquery. | — |
| Expl | Piano di esecuzione in forma testuale (interruttore). | Connessione |
| ExpG | Piano di esecuzione come grafo di nodi. | Connessione |
| CmpPlan | Confronto tra due piani di esecuzione. | Connessione |
| Save.fdp / Load.fdp | Salva e apre il progetto .mfdproj (vedi cap. 13). | — |
10. Navigazione e selezione
| Gesto | Effetto |
|---|---|
| Rotella del mouse | Zoom centrato sul puntatore. Sopra un nodo con scorrimento scorre i campi; sopra il pannello laterale scorre il pannello. |
| Tasto destro + trascina oppure Alt + sinistro | Panoramica del canvas. |
| Trascina un nodo | Sposta la tabella; al rilascio si aggancia alla griglia. |
| Trascina sullo sfondo | Selezione ad area (rubber band). |
| Ctrl + clic | Aggiunge o toglie un nodo dalla selezione multipla; trascinandone uno si muove tutto il gruppo. |
| Minimap | Trascina nella minimap per spostare la vista. |
| Pulsanti − / % / + | Zoom da 30% a 300%; un clic sulla percentuale riporta a 100%. |
11. Tab di query
Il Builder ha due righe di tab. La prima contiene una voce per ogni connessione aperta (nell’esempio SBT): cliccandola si attiva quel database anche nell’albero e nell’Editor. La seconda contiene le query della connessione: ognuna ha il proprio diagramma indipendente.
- + (o Ctrl+T) crea una nuova query nella connessione attiva.
- × sul tab (o Ctrl+W) la chiude, dopo conferma.
- Clic destro sul tab: Rinomina tab…. Il nome viene aggiornato anche nel tab corrispondente dell’Editor.
12. Dal Builder all’Editor
Ogni tab del Builder è collegato a un tab dell’Editor SQL. Con Run l’SQL generato viene portato nell’Editor sulla connessione corretta e quindi eseguito.
[QB] Builder, il Builder controlla il testo e lo riscrive a ogni modifica del diagramma: le tue correzioni a mano andrebbero perse. Per rifinire la query a mano premi il pulsante: diventa [FR] Free e il Builder smette di sovrascrivere l’Editor (vedi cap. 17).13. Salvare il lavoro
| Cosa | Come |
|---|---|
| Un diagramma | Save / Load → file .json. |
| Una query come immagine o documento | Export → PNG, SVG, HTML, Markdown. |
| L’intero progetto | Save.fdp / Load.fdp → file .mfdproj. Salva le connessioni e i tab; il titolo della finestra mostra un asterisco (*) quando ci sono modifiche non salvate. |
| Una query ricorrente | Ctrl+Shift+S la salva come snippet. |
14. Scorciatoie da tastiera
| Tasti | Azione |
|---|---|
| F1 | Guida alle scorciatoie |
| Ctrl+Z / Ctrl+Y | Annulla / ripristina |
| Ctrl+A | Seleziona tutti i nodi |
| Ctrl+C | Copia l’SQL generato |
| Ctrl+D | Duplica il nodo selezionato |
| Ctrl+F | Cerca tabelle e campi nel diagramma |
| Ctrl+R | Trova e rinomina ovunque |
| Ctrl+Shift+F / Ctrl+G / Ctrl+0 | Adatta tutto / zoom sulla selezione / reset zoom |
| + / − | Zoom avanti / indietro |
| Tab / Shift+Tab | Nodo successivo / precedente |
| Canc | Elimina il nodo o la relazione selezionati |
| Esc | Annulla la relazione in corso o chiude l’overlay |
| Ctrl+E | Explain Plan a grafo |
| Ctrl+H | Storico query |
| Ctrl+P | Stampa |
| Ctrl+T / Ctrl+W / Ctrl+Tab | Nuovo tab / chiudi tab / tab successivo |
| Ctrl+Shift+S / Ctrl+Shift+L | Salva come snippet / apri libreria snippet |
| Ctrl+Shift+T | Tema scuro / chiaro |
15. Cos’è l’Editor
L’Editor SQL è la metà bassa della finestra: qui scrivi, formatti ed esegui le query e leggi i risultati. Mostra l’SQL generato dal Builder, ma funziona anche da solo come editor completo.
- Execute: esegue la query
- [FR] Free / [QB] Builder: chi comanda il testo
- Undo / Redo
- Copia, Find, Format, ⚙, Pulisci, Carica
- Script: esecuzione batch
- Tx, OK, RB: transazione
- Hist: cronologia
- Tab dell’Editor (connessione e query)
- Gutter con i numeri di riga
- Barra di stato: driver @ host / database
A destra della barra comandi trovi la posizione del cursore (Ln 1, Col 1) e, quando serve, l’indicatore degli errori di sintassi.
16. Scrivere SQL
- Colorazione delle parole chiave in tempo reale, anche su testi lunghi.
- IntelliSense: si apre da solo mentre digiti (già dal primo carattere dopo
SELECT,WHEREe simili, o dopo il punto) con tabelle e campi dello schema. Puoi aprirlo con F2 o Ctrl+Spazio; scorri con ↑ ↓, conferma con Invio o Tab, chiudi con Esc. - Ctrl+/ commenta o decommenta la riga corrente (
--). - Tab inserisce due spazi.
- Indicatore errori: la barra comandi segnala eventuali problemi di sintassi mentre scrivi.
17. Modalità Builder / Free
Il pulsante accanto a Execute decide chi è proprietario del testo:
| Pulsante | Significato |
|---|---|
[QB] Builder | Il testo è quello generato dal Builder e viene riscritto a ogni modifica del diagramma. |
[FR] Free | SQL libero: il Builder non tocca più l’Editor. Execute esegue ciò che hai scritto. |
[FR] Free, poi rifinisci a mano. Per tornare al testo generato dal Builder, premi di nuovo il pulsante.Nello screenshot la query SELECT * FROM "SBUTENTI" INNER JOIN … è in modalità Free: il Builder non la sovrascrive.
18. Eseguire query e script
| Azione | Come | Dettagli |
|---|---|---|
| Eseguire la query | Execute, F5 o Ctrl+Invio | Richiede una connessione attiva. Se la query contiene parametri (:nome) si apre una finestra per impostarne tipo e valore. Una query con più recordset mostra i risultati in tab separati. |
| Eseguire uno script | Script o F6 | Esegue più istruzioni di seguito, con avanzamento. Riconosce correttamente i blocchi BEGIN … END (i ; interni a un trigger non spezzano l’istruzione), il formato isql SET TERM ^ e il separatore GO di SQL Server. |
| Aprire un file .sql | Carica o Ctrl+O | Il file si apre in un nuovo tab. Sono accettati sia UTF-8 sia file ANSI vecchi (per esempio salvati da Notepad). |
19. Transazioni
Per default le istruzioni vengono eseguite normalmente. Per raggruppare più modifiche in un’unica transazione usa i tre pulsanti:
| Pulsante | Azione | Attivo quando |
|---|---|---|
| ● Tx | BEGIN TRANSACTION (Ctrl+B) | Connessione aperta e nessuna transazione in corso |
| ✔ OK | COMMIT | Transazione in corso |
| ↺ RB | ROLLBACK | Transazione in corso |
OK e RB sono sbiaditi (come nello screenshot) finché non avvii una transazione. Gli esiti compaiono nel pannello Messaggi.
20. Pannello risultati
Dopo l’esecuzione, sotto l’Editor si apre il pannello dei risultati. Si chiude con × e si ridimensiona trascinando il divisore.
| Elemento | Funzione |
|---|---|
| Riga di stato | Righe restituite o interessate, oppure l’errore su una riga sola (il dettaglio completo è nel pannello Messaggi). |
| Ricerca 🔍 | Filtra le righe già caricate. |
| Paginazione | Per risultati grandi la query viene letta a blocchi: i pulsanti avanti/indietro scorrono i blocchi (paginazione SQL, o sul client). Se la query non ha ORDER BY compare un avviso ⚠ perché l’ordine dei blocchi non è garantito. |
| Export | CSV, JSON, XML, XLSX, oppure script SQL di INSERT INTO. |
| ✎ Modifica | Rende la griglia modificabile quando il risultato proviene da una sola tabella; compaiono Nuova riga, Elimina riga, Salva e Annulla. Le modifiche restano in cache finché non le salvi. Se il risultato non è modificabile il pulsante lo segnala nel suggerimento. |
| Msg | Mostra o nasconde il pannello Messaggi (log di esecuzioni, errori, transazioni); il pulsante × Pulisci lo svuota. |
21. Barra comandi
| Pulsante | Azione |
|---|---|
| Execute | Esegue la query (F5). |
| [FR] Free / [QB] Builder | Cambia la modalità (cap. 17). |
| ↶ ↷ | Annulla / ripristina la digitazione. |
| Copia | Copia tutto il testo negli appunti. |
| Find | Trova e sostituisci (Ctrl+H): Trova successivo, Sostituisci, Sostituisci tutto, con modalità Regex. |
| Format | Formatta l’SQL: parole chiave maiuscole e indentazione. |
| ⚙ | Opzioni del formattatore. |
| Pulisci | Svuota il tab corrente. |
| Carica | Apre uno o più file .sql in nuovi tab (Ctrl+O). |
| Script | Esegue come batch (F6). |
| Tx / OK / RB | Transazione (cap. 19). |
| Hist | Cronologia delle query (Ctrl+Alt+H). |
22. Tab dell’Editor
La struttura è la stessa del Builder: una voce per connessione (SBT) e, accanto, le query (Query 2). Un asterisco dopo il nome (Query 2 *) indica modifiche non salvate.
- + o Ctrl+T: nuovo tab nella connessione attiva.
- × o Ctrl+W: chiude il tab, dopo conferma.
- Ctrl+Tab: passa al tab successivo.
- Clic destro → Rinomina…: il nome si aggiorna anche nel tab collegato del Builder.
In basso a sinistra la barra di stato indica il driver, il server e il database a cui è collegato il tab (nell’esempio FB @ localhost / SB.FDB).
23. Cronologia e recupero
Cronologia
Hist apre l’elenco delle query eseguite: massimo 100 voci, senza duplicati, con ricerca e anteprima. Da lì puoi inserire una query in un tab.
Recupero dopo un arresto anomalo
Ogni 30 secondi il tab attivo viene salvato in un file temporaneo. Se l’applicazione si chiude in modo anomalo, al riavvio ti viene proposto di importare le bozze recuperate.
24. Scorciatoie dell’Editor
| Tasti | Azione |
|---|---|
| F5 / Ctrl+Invio | Esegui |
| F6 | Esegui come script |
| F2 / Ctrl+Spazio | IntelliSense |
| Ctrl+/ | Commenta / decommenta la riga |
| Ctrl+H | Trova e sostituisci |
| Ctrl+B | BEGIN TRANSACTION |
| Ctrl+O | Carica file .sql |
| Ctrl+Alt+H | Cronologia |
| Ctrl+T / Ctrl+W / Ctrl+Tab | Nuovo tab / chiudi tab / tab successivo |
| Tab | Inserisce due spazi |
25. La barra dei menu
La barra in alto contiene tutti i comandi dell’applicazione. Le voci cambiano in base alla modalità attiva (le schede sopra l’area di lavoro) e allo stato corrente: una voce grigia significa che manca qualcosa (una connessione, una tabella nel diagramma, del testo nell’editor). Le tabelle qui sotto riportano, per ogni voce, la condizione che la rende attiva.
| Modalità | Menu visibili |
|---|---|
| Builder | File, Modifica, Query, Vista, Schema, DDL, Connessione, Tab, Snippet, Strumenti, Impostazioni, Extra, ? |
| Designer | Compare il menu Schema Designer; Query, Vista e Schema (quelli del Builder) sono nascosti |
| ETL | Compare il menu ETL. Modifica, DDL, Connessione, Tab, Snippet, Strumenti ed Extra sono nascosti; restano File, Impostazioni e ? |
| Analisi | Compare il menu Analisi (aggiorna, esporta, configurazione) |
26. Menu File
| Voce | Scorciatoia | Quando è attiva |
|---|---|---|
| Nuovo progetto | Ctrl + N | Sempre |
| Nuovo tab editor / Chiudi tab editor | Ctrl + T / Ctrl + W | Chiudi: se esiste almeno un tab |
| Salva tab editor | Ctrl + Shift + E | Solo se il tab è stato modificato |
| Carica file SQL | Ctrl + O | Apre uno o più file in nuovi tab |
| Salva progetto | Ctrl + S | Solo con modifiche non salvate |
| Salva progetto con nome | — | Sempre |
| Apri progetto (.mfdproj) | Ctrl + Shift + O | Sempre |
| Recenti | — | Elenco dei progetti usati di recente |
| Esporta → SQL, DDL, Markdown | — | SQL: serve testo nell’editor. DDL e Markdown: Modalità Builder, con almeno una tabella nel diagramma |
| Esporta → CSV, JSON, XML, Excel | — | Serve SQL nell’editor e connessione |
| Esporta → SVG, PNG, HTML | — | Immagini o pagina del diagramma. Modalità Builder, con almeno una tabella nel diagramma |
| Stampa diagramma | Ctrl + P | Modalità Builder, con almeno una tabella nel diagramma |
| Configurazione AI | — | Impostazioni del servizio AI |
| Esci | Alt + F4 |
27. Menu Modifica
| Voce | Scorciatoia | Quando è attiva |
|---|---|---|
| Annulla / Ripristina | Ctrl + Z / Ctrl + Y | Agiscono sul Builder o sul Designer attivo |
| Copia tutto l’SQL | Ctrl + Shift + C | Serve testo nell’editor |
| Trova / Sostituisci | Ctrl + H | Serve testo nell’editor |
| Trova e rinomina globale | Ctrl + Shift + R | Rinomina tabella o campo in tutto il diagramma. Modalità Builder, con almeno una tabella nel diagramma |
| Formatta SQL / Opzioni formattatore | Ctrl + Shift + F | Le opzioni sono sempre accessibili |
| Svuota editor | — | Serve testo nell’editor |
| Modalità Free | Ctrl + Shift + M | Scollega l’Editor dal Builder (cap. 17). Solo in modalità Builder |
| Distacca editor / Riancora editor | — | Porta l’Editor in una finestra mobile e viceversa |
28. Menu Query
| Voce | Scorciatoia | Quando è attiva |
|---|---|---|
| Esegui | F5 | Serve SQL nell’editor e connessione |
| Esegui come script | F6 | Come sopra, solo in modalità Builder |
| Esegui query del Builder | F7 | Esegue la query del tab attivo del Builder. Serve la connessione dell’albero |
| Begin / Commit / Rollback | Ctrl + B / Ctrl + M / Ctrl + Shift + B | Begin senza transazione attiva; Commit e Rollback con transazione attiva |
| Genera DML → SELECT, SELECT keyset, INSERT, INSERT multiplo, UPDATE, DELETE, MERGE, TRUNCATE | — | Generano lo script dal diagramma. Modalità Builder, con almeno una tabella nel diagramma |
| Genera DDL → CREATE TABLE + FK + INDEX, ALTER (differenze da snapshot), CREATE VIEW, tabella temporanea, PIVOT, UNPIVOT, COMMENT ON | — | Come sopra (ALTER vale anche nel Designer) |
| Query AI | Ctrl + Shift + A | Genera la query da linguaggio naturale |
| Genera prompt AI | Ctrl + Shift + J | Prompt JSON dallo schema semantico. Serve uno schema aperto nel Designer |
| Costruisci diagramma dal testo dell’editor | — | Dal testo SQL crea il diagramma. Serve testo, connessione, Builder |
29. Menu Vista
| Voce | Scorciatoia | Quando è attiva |
|---|---|---|
| IntelliSense | Ctrl + Spazio | Attiva/disattiva il completamento automatico |
| Numeri di riga | — | Mostra/nascondi nell’editor |
| Pannello messaggi | Ctrl + Shift + G | |
| Cronologia editor | Ctrl + Shift + H | |
| Tema scuro / chiaro | — | Alterna il tema |
| Minimappa, Pannello laterale | — | Solo Builder |
| Modalità ER | — | Alterna Builder ed ERD. Solo Builder |
| Adatta alla vista / Zoom sulla selezione | Ctrl + 0 / Ctrl + Shift + 0 | Modalità Builder, con almeno una tabella nel diagramma |
| Reimposta vista | — | Solo Builder |
| Explain → Mostra piano, Grafo del piano, Confronta piani, Nascondi | Ctrl + E (Mostra piano) | Serve connessione e diagramma; Nascondi solo se il piano è visibile |
30. Menu Schema
Comandi sul diagramma del Builder e sull’albero dello schema.
| Voce | Scorciatoia | Quando è attiva |
|---|---|---|
| Importa schema | Ctrl + I | Serve connessione. Solo Builder |
| Aggiorna albero / Espandi radice | F5 (Aggiorna) | Serve l’albero |
| Invia schema a IntelliSense | Ctrl + Shift + I | Serve albero, editor e connessione |
| Aggiungi tabella / Rimuovi tabella | Ctrl + Shift + T / Canc | Rimuovi: serve una tabella |
| Duplica tabella, Self-join | Ctrl + D | Modalità Builder, con almeno una tabella nel diagramma |
| Aggiungi / Rimuovi relazione | — | Aggiungi: servono almeno 2 tabelle. Rimuovi: almeno una relazione |
| Aggiungi CTE, Nota, Subquery, Nodo procedura | — | Solo Builder |
| Alias automatici (tabelle / campi duplicati) | — | Assegna a, b, c… alle tabelle; alias univoci alle colonne omonime |
| Ripara collegamenti tab | — | Ricontrolla i collegamenti tra i tab del Builder e dell’Editor |
| WHERE → Aggiungi gruppo AND/OR, Cancella WHERE | — | Cancella: solo se ci sono condizioni |
| Cerca nel diagramma / Dialogo di ricerca | Ctrl + F | Solo Builder |
| Seleziona tutto / Deseleziona / Svuota diagramma | Ctrl + A / Esc | Modalità Builder, con almeno una tabella nel diagramma |
| Procedura guidata funzione scalare | — | Sul campo selezionato |
| Analizza campo | — | Statistiche (MIN/MAX/AVG…). Serve connessione |
| Pannello parametri | Ctrl + Shift + P | Pannello :param della query. Serve connessione |
31. Menu DDL
Procedure guidate per creare e modificare oggetti sul database. Tutte le voci tranne Crea tabella richiedono una connessione attiva.
| Voce | Scorciatoia | Quando è attiva |
|---|---|---|
| Tabella → Crea, Modifica (ALTER), Elimina | — | Crea funziona anche senza connessione; il resto richiede connessione |
| Indice → Crea, Elimina, Ricostruisci | — | |
| Trigger → Crea, Elimina, Abilita/Disabilita | — | |
| Vista → Crea, Elimina | — | |
| Procedura → Crea, Elimina, Esegui con parametri | — | |
| Chiave esterna → Crea, Elimina | — | |
| Sequenza → Crea, Elimina, Reimposta valore | — | |
| Seleziona prime N righe | — | Mostra le prime N righe |
32. Menu Connessione
| Voce | Scorciatoia | Quando è attiva |
|---|---|---|
| Nuova connessione | — | Crea o seleziona un file .fdc |
| Connetti / Disconnetti | — | Connetti se non sei connesso; Disconnetti se connesso |
| Carica connessioni | — | Carica i file .fdc da una cartella |
| Abilita / Disabilita auto-save | — | Auto-save del diagramma. Solo Builder |
| Backup / Ripristino database | — | Procedure guidate. Serve connessione |
| Importa dati | — | Procedura guidata. Serve connessione |
| Esegui query del tab attivo | — | Serve connessione |
33. Menu Tab
| Voce | Scorciatoia | Quando è attiva |
|---|---|---|
| Nuovo tab editor / Chiudi tab editor | Ctrl + T / Ctrl + W | |
| Nuovo tab query | Ctrl + Alt + T | Aggiunge un tab al Builder |
| Rimuovi tab query | Ctrl + Alt + W | Solo se i tab sono più di uno |
| Rinomina tab query | — | Il nome si propaga anche all’Editor |
34. Menu Snippet
Snippet e cronologia delle query del Builder.
| Voce | Scorciatoia | Quando è attiva |
|---|---|---|
| Mostra snippet | Ctrl + Alt + S | Sfoglia e inserisce snippet. Solo Builder |
| Carica / Salva snippet | — | File JSON. Salva solo se esistono snippet |
| Cronologia query del Builder | — | Solo se ci sono voci |
| Svuota cronologia Builder | — | Solo se ci sono voci |
| Carica / Salva cronologia | — | Salva solo se ci sono voci |
35. Menu Strumenti
| Voce | Scorciatoia | Quando è attiva |
|---|---|---|
| Valida diagramma | Ctrl + Shift + V | Controlla la coerenza. Modalità Builder, con almeno una tabella nel diagramma |
| Performance Advisor | — | Analisi indici e prestazioni. Serve connessione |
| Confronta schemi | — | Con connessione, o con tabelle nel diagramma |
| Confronta dati | — | Serve connessione |
| Confronta schemi (Tag) | — | Serve l’albero |
| Trova utilizzi | — | Dove viene usato l’oggetto selezionato. Serve connessione |
| Gestione utenti / Cambia password / Esci utente | — | Solo con accesso effettuato; Gestione utenti solo per l’amministratore |
| Carica demo | — | Diagramma di esempio. Solo Builder |
| Guida scorciatoie | F1 |
36. Impostazioni, Extra e ?
| Voce | Scorciatoia | Quando è attiva |
|---|---|---|
| Dialetto | — | Standard, SQL Server, Oracle, MySQL, MariaDB, PostgreSQL, Firebird, InterBase, SQLite. In fondo, a supporto limitato nel Builder: MS Access, IBM DB2, Informix |
| Rileva dialetto automaticamente | — | Prende il dialetto dalla connessione |
| Lingua | — | Italiano, English, Deutsch, Français, Español, Português, Русский, 中文, 日本語 |
| Extra → Converti SQL per tributi | — | Serve testo nell’editor |
| Extra → Gestione drop | — | Procedura guidata di drop |
| ? → Informazioni, Licenza, Registrami | — | Sempre |
37. Menu delle altre modalità
Quando passi a un’altra scheda compaiono i menu dedicati; il Designer è descritto nella parte C; l’ETL è descritto nella parte D; l’Analisi è descritta nella parte F.
| Menu | Contenuto |
|---|---|
| Schema Designer | Aggiungi tabella e FK, elimina selezione, disposizione automatica, zoom (Ctrl+=, Ctrl+-); importa da DDL o da database, aggiorna dal database; genera DDL (F7) e REST; salva, carica ed esporta (SVG, PNG, pacchetto semantico, dialetto); analisi star schema (parte H); tab di schema (Ctrl+Alt+N / Ctrl+Alt+W); generazione AI (Ctrl+Shift+I) e raffinamento. |
| ETL | Nuova fase, abbinamento automatico, modifica ed eliminazione fasi; campi (nuovo, modifica, elimina, genera); fase e connessioni sorgente/destinazione dall’albero; salva e carica progetto ETL, salva per il servizio; Esegui (F9) e Annulla. |
| Analisi | Aggiorna (F5); esporta in PNG, SVG, CSV; salva e carica la configurazione. |