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.

PlyxSQL — FireDAC SQL ManagerBarra dei menu e barra degli strumenticambiano con la scheda attiva — parte I e capitoli 25–37Albero (Tree)connessioni e databaseParte A: connettersiParte B: albero e TablesTablesParte BBuilderCap. 1–14DesignerParti C, G, HETLParte DAnalisysParte FPerformance-ProfilerParte EBuilderdiagramma di tabelle e JOIN → SQLbarra Run · Schema · ERD · Explain…tab di query, snippet, AIDesignercanvas di tabelle e chiavi esterneconfigurazione semantica per l’AI (G)Analisi star schema (H)ETLfasi, campi, regoleesecuzione e pianificazioneAnalisigrafici dalla queryesporta PNG · SVG · CSVPerformance-Profilermisura la query nell’Editorpiano, storicoStar schema (H)fatti, dimensioni, queryETL ↔ stella (H16)Editor SQL (cap. 15–24)in basso, condiviso: testo SQL, risultati, messaggi, transazioni, cronologiaFrecce: la query del Builder va all’Editor, all’Analisi e al Profiler; il Designer apre lo star schema, che si collega all’ETL.
ParteArgomentoChe cosa trovi
AConnessioniTipi di connessione, rete, file, ODBC, SSH, salvataggio→
BAlbero e TablesAlbero database, ricerca, esportazione, modifica dati e struttura→
CDesignerSchema visuale, chiavi esterne, ruoli, DDL→
GConfigurazione semanticaAlias, lookup, calcolati, filtri, prompt AI, pacchetto→
HStar schemaFatti, dimensioni, grain, query guidate, collegamento all’ETL→
DETLFasi, regole sui campi, esecuzione, pianificazione→
EPerformance-ProfilerMisure, soglie, piano di esecuzione, storico→
FAnalisiGrafici e mappe dai risultati di una query→
IBarre degli strumentiI pulsanti di ogni scheda, con schermate numerate→
1–14BuilderDiagramma, JOIN, campi, barra comandi, tab, salvataggio→
15–24Editor SQLScrivere ed eseguire SQL, risultati, transazioni, cronologia→
25–37MenuTutte 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.

SchedaMenu visibiliGruppi della barra
Tables / BuilderFile, Modifica, Query, Vista, Schema, DDL, Connessione, Tab, Snippet/History, Strumenti, Impostazioni, Extra, ?1, 2, esecuzione, transazioni, editor, AI, confronto (I2)
DesignerFile, Modifica, Schema Design, DDL, Connessione, Tab, Snippet/History, Strumenti, Impostazioni, Extra, ?1, 2, schema, vista, genera, importa/salva, tab, AI, confronto (I3)
ETLFile, Impostazioni, ETL, ?1, 2, fasi, campi, connessioni, progetto, esecuzione (I4)
AnalisysFile, Impostazioni, Analytics, ?1, 2, configurazione, esportazione, aggiorna (I5)
Performance-ProfilerFile, Impostazioni, Analytics, ?come Analisys (I6)
Ordine dei pulsantiNelle schermate i pulsanti delle schede Designer, ETL, Analisys e Profiler compaiono nell’ordine inverso rispetto a quello del menu: le tabelle seguono l’ordine in cui li vedi, da sinistra a destra.

Gruppi comuni a tutte le schede

#PulsanteChe cosa faTasti
1Nuovo progettoParte da un progetto vuoto. Se ce n’è uno con modifiche chiede di salvarle.Ctrl+N
1Apri progettoApre un file progetto salvato (connessioni, tab, diagrammi).Ctrl+Shift+O
1Salva progettoSalva il progetto. Il titolo della finestra mostra * finché ci sono modifiche non salvate.Ctrl+S
1Salva con nomeSalva il progetto in un nuovo file.Ctrl+Shift+S
2ConnettiApre la connessione attiva (quella scelta nell’albero).—
2DisconnettiChiude la connessione attiva.—

I2. Builder

Barra degli strumenti con la scheda Builder: gruppi numerati da 1 a 7

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:

#PulsanteChe cosa faTasti
3EseguiEsegue l’SQL corrente nell’Editor o la parte selezionata.F5
3Esegui come scriptEsegue il testo come script a più istruzioni.F6
3Esegui query del BuilderGenera ed esegue la query del tab attivo del Builder.F7
4Inizia transazioneBEGIN TRANSACTION: le istruzioni successive restano in sospeso.Ctrl+B
4CommitRende definitive le modifiche della transazione.Ctrl+M
4RollbackAnnulla le modifiche della transazione.Ctrl+Shift+B
5AnnullaAnnulla l’ultima operazione.Ctrl+Z
5RipristinaRipristina l’operazione annullata.Ctrl+Y
5Formatta SQLRiformatta il testo SQL corrente.Ctrl+Shift+F
5Copia tuttoCopia l’intero testo SQL negli appunti.Ctrl+Shift+C
6Query con AIGenera la query da una richiesta in linguaggio naturale.Ctrl+Shift+A
6Costruisci dal SQL dell’EditorLegge l’SQL dell’Editor e disegna tabelle e JOIN nel Builder.Ctrl+Shift+Q
7Confronta schemiConfronta lo schema di due connessioni e mostra le differenze.—
7Confronta datiConfronta i dati di due tabelle.—
7Confronta tagConfronta 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

Barra degli strumenti con la scheda Designer: gruppi numerati da 1 a 9

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).

#PulsanteChe cosa faTasti
3Genera prompt AIGenera il JSON-prompt dallo schema semantico configurato (finestra di verifica del prompt AI).Ctrl+Shift+J
3Raffina con AIChiede all’AI di modificare lo schema già presente.—
3Genera con AIDescrivi lo schema a parole e il programma lo propone.Ctrl+Shift+I
4Rinomina tab schemaRinomina il tab schema attivo.—
4Chiudi tab schemaChiude il tab schema attivo.Ctrl+Alt+W
4Nuovo tab schemaAggiunge un nuovo tab schema al Designer.Ctrl+Alt+N
5Esporta PNGSalva il diagramma come immagine PNG.—
5Esporta SVGSalva il diagramma come immagine vettoriale SVG.—
5Pulisci schemaSvuota lo schema (chiede conferma).—
5Carica schemaCarica un file schema .sdschema (JSON), con il modello a stella se c’è.—
5Esporta pacchetto semanticoEsporta il Configuratore Semantico in un JSON portabile per un componente server (G18).—
5Salva schemaSalva lo schema in un file (tabelle, colonne, FK, posizioni, modello a stella).—
5Aggiorna dal databaseRiallinea lo schema già nel canvas con il database.—
5Importa da databaseLegge lo schema dalla connessione attiva, scegliendo le tabelle.—
5Importa da DDLCostruisce lo schema da uno script DDL.—
6Esporta dialettoEsporta il DDL nel dialetto scelto.—
6Genera RESTVoce Genera REST del menu Schema Design.—
6Genera ALTERGenera gli ALTER TABLE delle differenze rispetto a uno snapshot.—
6Genera DDLGenera lo script DDL dello schema nel tab Schema Designer dell’Editor (C8).F7
7RiduciRiduce lo zoom del canvas.Ctrl+-
7IngrandisciAumenta lo zoom del canvas.Ctrl+=
7AdattaAdatta lo zoom per mostrare tutto lo schema.Ctrl+Shift+0
7Disposizione automaticaDispone le tabelle in automatico.—
8Elimina selezioneElimina le tabelle o le chiavi esterne selezionate.—
8Aggiungi chiave esternaCrea una chiave esterna fra due tabelle.—
8Aggiungi tabellaAggiunge una tabella al canvas.—
9Confronta schemiConfronta lo schema di due connessioni e mostra le differenze.—
9Confronta datiConfronta i dati di due tabelle.—
9Confronta tagConfronta i tag (versioni) dello schema.—
Esegui nel DesignerNel Designer il tab dell’Editor contiene il DDL e “Esegui” lo lancia come script, istruzione per istruzione. Se però nell’Editor c’è una sola SELECT (per esempio quella aperta dalla finestra star schema) viene eseguita come query e i risultati compaiono nel pannello risultati, in basso.

I4. ETL

Barra degli strumenti con la scheda ETL: gruppi numerati da 1 a 7

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.

#PulsanteChe cosa faTasti
3Annulla esecuzioneInterrompe l’importazione in corso.—
3Esegui ETLEsegue le fasi del progetto ETL (D8).F9
4Salva per il servizioSalva un file .petl per il servizio Windows delle importazioni pianificate (D9).—
4Carica progetto ETLApre un progetto ETL salvato.—
4Salva progetto ETLSalva il progetto ETL per riaprirlo in questa applicazione.—
5Connessione di destinazioneImposta come destinazione la connessione scelta nell’albero.—
5Connessione di origineImposta come origine la connessione scelta nell’albero.—
6Genera campiCrea i campi della fase dalle colonne.—
6Elimina campoElimina il campo selezionato.—
6Modifica campoApre le regole del campo selezionato (D5).—
6Nuovo campoAggiunge un campo alla fase.—
7Elimina tutte le fasiElimina tutte le fasi (chiede conferma).—
7Elimina faseElimina la fase selezionata.—
7Modifica faseApre le impostazioni della fase (D4).—
7Genera fasi da tabelle corrispondentiCrea una fase per ogni coppia di tabelle con lo stesso nome in origine e destinazione.—
7Nuova faseAggiunge una fase al progetto.—

I5. Analisys

Barra degli strumenti con la scheda Analisys: gruppi numerati da 1 a 5

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.

#PulsanteChe cosa faTasti
3Carica configurazioneCarica la configurazione del grafico da un file.—
3Salva configurazioneSalva la configurazione del grafico in un file.—
4Esporta CSVEsporta i dati del grafico in CSV.—
4Esporta SVGEsporta il grafico come SVG.—
4Esporta PNGEsporta il grafico come immagine PNG.—
5AggiornaRilegge i dati della query e ridisegna il grafico.F5

I6. Performance-Profiler

Barra degli strumenti con la scheda Performance-Profiler: gli stessi gruppi di Analisys

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

DoveChe 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 schemaIl 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.

Finestra Analisi star schema appena aperta

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.

Finestra Analisi star schema con una query di tre misure di FACT_BUDGET

Pulsanti

PulsanteChe cosa fa
Proponi modello dallo schemaBozza di fact e dimensioni dalle chiavi esterne (H3).
Valida modelloScrive le segnalazioni STARxxx nel riquadro in basso (H14).
+ Attributo / + Misura / + FiltroAggiungono alla query il nodo selezionato nell’albero.
Colonne del grain…, Applica al modello, + Derivata…Modificano il modello (H4, H11).
Elimina fact/dimensioneToglie dall’albero il nodo selezionato.
Copia SQLCopia la query negli appunti.
EseguiEsegue 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’editorPorta l’SQL nell’Editor; per eseguirlo premi Esegui (una SELECT dà un result set anche nel Designer, v. I3).
Apri nel Query BuilderSolo 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:

Designer con la query star nell’Editor e il risultato in griglia

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:

SchedaPer cosa serve
ReteServer di database: Firebird, InterBase, MySQL / MariaDB, SQL Server, PostgreSQL, Oracle, Informix, IBM DB2, più SQLite e MS Access come file.
File / LocalSQLSQLite, CSV, Excel / ODS, JSON, XML, tracciati a posizione fissa, ClientDataSet, FDMemTable e API REST: i file diventano tabelle su cui scrivere SQL.
ODBCQualsiasi sorgente con un driver ODBC installato, oppure un DSN già definito in Windows.
SSH TunnelNon è 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

Schermata iniziale con Nuovo progetto

All’avvio compare la schermata iniziale, con tre colonne e due pulsanti:

ElementoChe 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 recenteI 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.
PreferitiI 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-corsiUn elenco di video tutorial collegato online.
Apri progettoApre 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 / LightScelta del tema.

A3. Aprire il dialogo 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

Dialogo Nuova Connessione, scheda Rete1234567891011
  1. Alias connessione
  2. Schede: Rete, File / LocalSQL, ODBC, SSH Tunnel
  3. Driver
  4. Server / host e Porta
  5. Database / percorso con Browse…
  6. Nome utente e Password
  7. Crea database se non esiste
  8. Parametri aggiuntivi (Chiave=Valore)
  9. Test connessione
  10. Parametri avanzati…
  11. Connetti e aggiungi

Quando scegli il driver, porta e utente vengono impostati ai valori predefiniti:

DriverPortaUtenteNote
FB (Firebird)3050SYSDBADatabase = nome o percorso sul server, per esempio SB.FDB
IB (InterBase)3050SYSDBA
MySQL3306rootVale anche per MariaDB (vedi nota)
MSSQL (SQL Server)1433sa
PG (PostgreSQL)5432postgres
Ora (Oracle)1521sys
Infx (Informix)9088informix
IBM (DB2)50000db2inst1
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.

MariaDBPer MariaDB si usa il driver MySQL. Il dialetto MariaDB si sceglie a mano per quella connessione (Impostazioni → Dialetto) e viene salvato nel progetto.

A5. Scheda File / LocalSQL

Scheda File / LocalSQL con tendina dei tipi

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.

TipoCosa fa
SQLite — fileApre un database SQLite (.db, .sqlite, .s3db). Indichi il percorso del file.
SQLite — in-memoryDatabase :memory:: i dati esistono solo durante la sessione.
LocalSQL — ClientDataSetCartella con file .cds .cdc .aff .icp; ogni file è una tabella.
LocalSQL — FDMemTableCartella con file .bin .mem.
LocalSQL — CSVCartella con .csv / .txt, importati come tabelle in memoria.
LocalSQL — SQLite fileCartella con .db / .sqlite: i database vengono collegati con ATTACH DATABASE.
LocalSQL — Tracciato a posizione fissaFile di testo a larghezza fissa descritti da un tracciato.
REST — API JSONEndpoint HTTP che restituiscono JSON.
JSON, XMLFile .json e .xml trattati come tabelle.
Excel / ODSFile .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

A6. Scheda ODBC

Elenca i driver ODBC installati sul computer (in ordine alfabetico). Puoi usarla in due modi:

Per i driver basati su file (Excel, Access…) il pulsante … accanto a Database permette di scegliere il file.

A7. Scheda SSH Tunnel

Scheda SSH Tunnel

Serve quando il database non è raggiungibile direttamente ma solo tramite un server SSH. Spunta Abilita tunnel SSH e compila:

CampoSignificato
SSH HostIndirizzo del server SSH (per esempio bastion.myserver.com).
Porta SSHPredefinita 22.
Utente SSHUtente per l’accesso al server SSH.
Password SSHOpzionale. Non viene salvata nel progetto per sicurezza: va reinserita a ogni sessione.
Chiave .ppk/.pemFile della chiave privata, in alternativa alla password.
Richiede plink.exe (PuTTY)Il programma lo cerca in 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

PulsanteCosa fa
▶ Test connessioneProva 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 aggiungiApre la connessione, la salva e la aggiunge all’albero, creando in automatico le tab collegate nell’Editor e nel Builder.
CancelChiude 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

Cosa non viene salvatoLa password SSH non è mai scritta nel progetto. L’opzione interna 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):

NodoVoci
Cartella ConnessioniNuova connessione, Gestione connettori, Apri cartella connettori, Confronta schemi, Confronta dati, Aggiorna.
File .fdcConnetti; 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

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

  1. 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.
  2. 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.
  3. 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.

PaginazioneI risultati lunghi vengono scaricati a pagine. Ogni endpoint dichiara se il token della pagina successiva va passato come parametro oppure se la risposta contiene già l’URL completo da richiamare.

A12. Problemi comuni

SintomoCausa 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 plinkPuTTY non è installato o plink.exe non è nel PATH. Installalo (vedi A7).
Il test riesce ma la connessione è offlineIl test non salva né aggiunge nulla: serve premere Connetti e aggiungi.
Il database Firebird non esisteSpunta 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 riaperturaI dati REST stanno in memoria e ripartono vuoti. Rilancia la query: il programma riscarica la tabella al volo.
Dati CSV tutti in una colonnaDelimitatore 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.

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

Vista dati della tabella1234567891011
  1. Titolo: la tabella mostrata
  2. Barra di navigazione: primo, precedente, successivo, ultimo, aggiorna
  3. Altre righe: carica il blocco successivo
  4. Colonna su cui agisce il filtro
  5. Operatore del filtro
  6. Valore da cercare
  7. Applica e X (azzera il filtro)
  8. Contatore: posizione e totale righe
  9. Esporta: CSV, JSON, XML, XLSX, MemTable, ClientDS
  10. Filtro=: filtra sul valore della cella
  11. 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

OperatoreSignificato
=Uguale
contieneTesto contenuto nel valore
>   <Maggiore, minore
<>Diverso
è nullo / non è nulloValore assente o presente

Gli operatori disponibili dipendono dal tipo della colonna scelta (per esempio, quelli numerici su un campo numerico).

Il filtro non cambia l’SQLAgisce sulle righe già caricate in griglia. Per filtrare lato database usa il Builder o l’Editor.

B4. Esportare i dati

PulsanteRisultato
CSVFile .csv
JSONFile .json
XMLFile .xml
XLSXCartella di lavoro Excel; al termine ti chiede se aprirla in Excel
MemTableFile binario .fdmt (FDMemTable)
ClientDSFile .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.

Non sempre disponibileLa modifica funziona solo su connessioni a un database vero e connesso. È bloccata sulle connessioni LocalSQL (CSV, Excel, REST, JSON…): in quel caso il pulsante torna su e compare un avviso. Se cambi tabella verso una connessione non scrivibile mentre stai modificando, la griglia torna in sola lettura.

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:

NodoVoci del menu
Cartella TabelleCrea tabella, Aggiorna
TabellaApri 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 indiceCrea indice · Ricostruisci · Elimina
Cartella Trigger / un triggerCrea trigger · Abilita / Disabilita · Elimina
Cartella Constraints / un vincoloAggiungi chiave esterna · Elimina vincolo
Cartella Viste / una vistaCrea vista · Apri nel Builder · Crea trigger sulla vista · Trova utilizzi · Mostra dipendenze · Elimina
Cartella Sequenze / una sequenzaCrea sequenza · Reimposta valore · Elimina
Cartella Stored Procedure / una proceduraCrea procedura · Crea da corpo SQL · Esegui · Mostra dipendenze · Elimina
Radice del databaseAggiorna, Capacità del server, Matrice SQL, ERD, Confronta schemi/dati, Backup, Ripristino, Esporta/Importa pacchetto team, Disconnetti

Cosa chiedono le procedure guidate

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.

Designer dello schema1234567
  1. Barra strumenti del Designer
  2. Tab dello schema (nell’esempio sbt_Schema1)
  3. Trova tabella, Vai e Avvicina
  4. Barra laterale con filtri e layout
  5. Tabella: intestazione con nome e ruolo (MST = master), colonne con tipo
  6. Relazione (chiave esterna)
  7. 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

PulsanteFunzione
▦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:1Zoom 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

  1. Aggiungi una tabella: menu Schema Designer → Aggiungi tabella oppure clic destro sul canvas.
  2. Nella finestra Modifica tabella scrivi Nome tabella, Commento, Nota e, per le tabelle di lookup, il nome del campo label.
  3. Aggiungi le colonne (clic destro sulla tabella → Aggiungi colonna). Per ogni colonna:
CampoSignificato
Nome colonna, TipoNome e tipo di dato; per un tipo non in elenco usa Tipo custom.
Lunghezza, Precisione, ScaleDimensione del tipo (per esempio VARCHAR(30) o DECIMAL(15,2)).
Default, CHECK constraint, CommentoValore predefinito, vincolo di controllo e commento.
Nullable, Primary Key, Auto Inc, UniqueOpzioni a spunta. Auto Inc genera l’identità nel modo giusto per il dialetto (su Firebird sequenza e trigger).

Da qualcosa che esiste già

C4. Relazioni (chiavi esterne)

  1. Clic destro sulla colonna di partenza → Disegna FK.
  2. 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.

Tabelle lontane?Usa Avvicina nella barra superiore per portare la tabella di destinazione accanto a quella di partenza, poi disegna la FK.

C5. Muoversi nel canvas

GestoEffetto
Trascina una tabellaLa sposta
Trascina il bordo della tabellaLa ridimensiona
Rotella sopra una tabella lungaScorre i campi (frecce ▲ ▼ nella riga indicatore)
Doppio clic su una colonnaApre la modifica della colonna
Doppio clic sull’intestazioneApre la modifica della tabella
MinimapTrascina per spostare la vista
Ctrl+= / Ctrl+-Zoom avanti / indietro
Ctrl+Shift+0Adatta lo schema alla finestra
CancElimina la tabella o la FK selezionata
EscAnnulla 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):

RuoloEtichetta
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

  1. Premi F7 (o Genera DDL nel menu Schema Designer, o clic destro sul canvas).
  2. Nella finestra Export DDL scegli il Dialetto, la Versione del server e, se serve, Includi DROP statements.
  3. 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 schemaFile 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 SVGImmagine del diagramma
Svuota schemaCancella tutto il canvas (si può annullare)
Nuovo tab schema (Ctrl+Alt+N), Chiudi (Ctrl+Alt+W), RinominaPiù schemi aperti insieme, ognuno nel proprio tab
Aggiungi tabella / FK, Elimina selezione, Auto layoutCome da barra laterale e menu contestuale
Zoom avanti / indietro / adattaCtrl+=, 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:

  1. Domanda in linguaggio naturale.
  2. Rilevamento delle tabelle: il programma sceglie le tabelle configurate il cui nome o le cui keyword compaiono nella domanda.
  3. Prompt JSON: schema, alias, lookup, filtri, vincoli e valori dei parametri vengono assemblati in un unico documento strutturato.
  4. Invio all’AI (Anthropic, OpenAI o Ollama, a seconda del profilo attivo) e ricezione dell’SQL.
  5. Controllo di sicurezza: ammessa solo una query di lettura (G12).
  6. Esecuzione di verifica con un limite di righe, e possibilità di salvare la coppia domanda/SQL come esempio verificato.
Un livello separato dallo schemaLa configurazione semantica è un livello indipendente dal DDL: non cambia le tabelle, non entra nello script generato e non si mescola con annulla/ripristina dello schema. Ogni configurazione è legata alla tabella tramite un identificatore interno, non per nome: se rinomini la tabella, la configurazione la segue.

G2. Dove si apre

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

Configurazione semantica di tabella, scheda Generale12345678
  1. Schede: Generale, Alias campi, Lookup, Calcolati, Keyword filter, Filtri fissi, Esempi
  2. Alias tabella
  3. Descrizione
  4. Ruoli ammessi [RBAC]
  5. Keyword identificazione tabella
  6. Campi attivi
  7. + Tutti / − Nessuno
  8. 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.

Nel Designer è solo un’anteprimaLe restrizioni sui ruoli sono applicate dal componente server, che riceve un ruolo già autenticato. Nel Designer servono a configurare e a vedere "che cosa vedrebbe questo ruolo": non sono un controllo di sicurezza.

Keyword identificazione tabella

Una espressione per riga: le parole che, se compaiono nella domanda, fanno includere la tabella nel prompt. Sintassi:

SimboloSignificatoEsempio
+ORinsegne+insegna: compare "insegne" oppure "insegna"
&ANDinsegne&insegna: compaiono entrambe
-NOT-occupazione: non compare "occupazione"
( )Raggruppamento-(a+b+c): nessuna delle tre compare
spazio, virgola, ;AND implicito tra due terminia 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.

Attenzione all’esempio dello screenshotinsegne+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:

ColonnaSignificato
CampoIl campo fisico. Se ne cambi il nome per errore e non corrisponde più a un campo reale, la riga viene ignorata
AliasSinonimi 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.
RuoliRuoli ammessi a vedere il campo, separati da virgola; vuoto = nessuna restrizione (solo anteprima nel Designer)

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:

ColonnaSignificato
CampoIl 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
JoinINNER, 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}%'
Graffe singole e doppie quadre{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:

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:

ColonnaContenuto
DomandaLa domanda tipica, come la scriverebbe un operatore
SQLLa query giusta
Test regressioneSI (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

Configurazione semantica globale12345678910
  1. Constraint generali
  2. Custom key: Parametro, Key, Valore, Default
  3. Colonna Default
  4. + Riga aggiunge una riga alla griglia sopra
  5. Alias di aggregazione
  6. Precompila standard
  7. Ruoli configurabili
  8. Suite di regressione
  9. Telemetria
  10. 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:

ColonnaSignificatoEsempio
ParametroIl nome del segnaposto (senza le parentesi)COMUNE
KeyL’etichetta leggibile che l’operatore usa nella domanda. Accetta la stessa sintassi delle keyword, quindi sinonimi come riccione+rnriccione
ValoreIl testo che prende il posto di [[PARAMETRO]] nelle querySB
DefaultSI indica il valore predefinito di quel ParametroSI

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.

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:

EspressioneSignificato
YEAR(TODAY()) · YEAR(TODAY())-1 · YEAR(TODAY())+1Anno 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.

Finestra Genera prompt AI1234567891011121314151617
  1. Domanda (question)
  2. Mantieni il contesto della domanda precedente
  3. Anteprima come ruolo
  4. Dialetto
  5. Versione
  6. AI attiva: profilo, provider e modello
  7. ⚙: apre la Configurazione AI
  8. Genera prompt
  9. Copia
  10. Invia a AI
  11. Inserisci nell’editor
  12. Testa SQL
  13. ✓ Verifica e salva come esempio
  14. Passi: registro dell’invio
  15. Anteprima JSON / risposta AI
  16. Esito e righe dell’esecuzione di verifica
  17. Chiudi

Campi in alto

CampoSignificato
Domanda (question)La domanda come la scriverebbe un operatore ("quante occupazioni permanenti a Riccione nel 2025?").
Mantieni il contesto della domanda precedenteSpuntalo 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 ruoloSimula 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, VersioneIl 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 attivaIl 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

PulsanteChe cosa faAttivo quando
Genera promptCostruisce 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
CopiaCopia 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 AIManda 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’editorPorta 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 SQLProva 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 esempioSalva 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
ChiudiChiude la finestra senza altre azioni.Sempre

Che cosa succede dopo "Invia a AI"

  1. La domanda può essere servita dalla cache (Trovato in cache — verifica in corso…): in quel caso non c’è nessuna chiamata all’AI (G13).
  2. Altrimenti l’SQL ricevuto passa dal controllo di sicurezza (solo letture, G12). Se è rifiutato, lo stato mostra ✗ Rifiutata dai controlli di sicurezza: motivo.
  3. Se è ammesso, viene eseguito in verifica sulla connessione corrente, con un limite di righe. In caso di errore compare ✗ Esecuzione fallita: messaggio e l’errore viene rimandato all’AI per un nuovo tentativo (correzione automatica).
  4. 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.
  5. Se la comunicazione con l’AI non riesce, lo stato dice ✗ Errore di comunicazione con l’AI — vedi sopra e 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:

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.

Salva lo schemaL’esempio è scritto nella configurazione in memoria del Designer: per renderlo permanente devi salvare lo schema su file. Non c’è nessun salvataggio automatico nascosto, come per ogni altra modifica fatta nei dialoghi di configurazione semantica.
StatisticheOgni esecuzione di verifica, anche un Testa SQL fallito, viene registrata nella telemetria (G13): una query scritta a mano che non passa la verifica è un dato utile per capire che cosa manca alla configurazione.
Serve un profilo AI attivoPer Invia a AI serve un profilo (G17). Senza, il resto della finestra funziona comunque: puoi generare il prompt, copiarlo in un’AI esterna e provare l’SQL con Testa SQL.

Cosa contiene il prompt

SezioneOrigine
tags, questionDialetto e versione; la domanda
constraintsConstraint generali (G10)
tablesSchema reale delle tabelle incluse (campi, chiavi primarie) più alias e descrizione
custom_semantic / custom_semantic_matchesCustom key e, per ognuna, se la domanda la nomina
query_fieldsI campi attivi (G3)
field_aliasesSinonimi dei campi (G4), identificatore umano
lookupsCollegamenti tra tabelle (G5)
calculated_fieldsCampi calcolati (G6)
matched_filtersKeyword filter scattati (G7)
always_filtersFiltri fissi (G8)
examplesEsempi (G9)
aggregate_aliasesVocabolario di aggregazione (G10)
previous_turnDomanda e SQL precedenti, per le conversazioni (vedi sotto)

G12. Sicurezza

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").

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

  1. 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.
  2. Per le tabelle principali (non tutte insieme): alias, descrizione, keyword e campi attivi. Togli i campi inutili.
  3. Premi Importa da FK nella scheda Lookup e completa cardinalità e join dove sono noti.
  4. Aggiungi i filtri fissi obbligatori (cancellazione logica, tenant) e i keyword filter ricorrenti.
  5. Scrivi 2–3 esempi per i pattern difficili.
  6. 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.
  7. Lancia la Suite di regressione e rifalla a ogni modifica importante.

G15. Problemi comuni

SintomoCausa e rimedio
La tabella giusta non entra nel promptNessuna 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 scattaLa tabella non è stata inclusa, oppure la keyword del filtro non compare nella domanda. Controlla il messaggio al salvataggio (G7).
L’AI usa il comune sbagliatoManca 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 campiTroppi 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 è giustaIl confronto è testuale: verifica a mano. Se l’esempio è solo di stile, imposta Test regressione = NO (G9).
Un ruolo vede ancora una tabella riservataNel 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.

Grafico semantico12345678
  1. Tab dello schema (qui AI_SEMANTIC_Schema1; l’asterisco indica modifiche non salvate)
  2. ⚙ Config. globale (G10)
  3. ⇄ per tornare allo schema fisico
  4. Nodo di una tabella configurata (selezionato: bordo arancione)
  5. Contatori filtri e campi calcolati
  6. Relazione di lookup con cardinalità e join
  7. Minimappa
  8. Nodo senza keyword: la tabella non verrà mai riconosciuta dal testo di una domanda

Come si legge un nodo

ParteContenuto
IntestazioneAlias 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 rigaLa prima keyword di identificazione, oppure — nessuna keyword.
Chip N filtriQuanti 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.

Controllo rapidoPrima di provare le domande, guarda il grafico: un nodo senza keyword non scatterà mai; una tabella isolata (nessuna curva) non verrà collegata alle altre; un contatore 0 filtri su una tabella che dovrebbe averne è il segnale di un filtro dimenticato.

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.

Configurazione AI12345678910
  1. Profili configurati (● = attivo)
  2. Provider: Anthropic, OpenAI, Ollama
  3. Modello
  4. Endpoint
  5. Parametri Ollama (solo per Ollama)
  6. Finestra di contesto (num_ctx) e token massimi (num_predict)
  7. Timeout in ms
  8. Salva profilo
  9. ● Attiva
  10. Chiudi
CampoSignificato
Profili configuratiL’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 ●.
ProviderAnthropic (Claude), OpenAI, Ollama (modello locale, sul tuo computer o su un server tuo)
ModelloIl nome del modello (nello screenshot gpt-oss:20b, un modello Ollama; per Claude per esempio claude-sonnet-4-6)
Chiave APIPer Anthropic e OpenAI. Non serve per Ollama.
EndpointIndirizzo 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 CPU0 = 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

  1. Apri File → Configurazione AI.
  2. Scegli + Nuovo (o modifica "Predefinito"), dai un nome, scegli provider, modello e, se serve, chiave ed endpoint.
  3. Premi Salva profilo, poi ● Attiva: il programma conferma che quel profilo sarà usato da ogni finestra che chiama l’AI.
  4. In basso trovi AI attiva: nome del profilo. Con più profili ne attivi uno alla volta.
La chiave API non si porta su un altro computerLa chiave è salvata protetta con Windows (DPAPI): legata all’utente e alla macchina. Aprendo il profilo da un altro computer o con un altro utente Windows la chiave risulta vuota e va reinserita, senza errori. Il file delle impostazioni sta nella cartella dell’utente (%APPDATA%\PGSOFT\plyxsql).
Prima volta dopo un aggiornamentoSe esistevano già impostazioni AI di una versione precedente, vengono migrate automaticamente in un profilo chiamato Predefinito, attivato da solo; la vecchia chiave in chiaro viene cancellata dopo la migrazione.
Locale o cloud?Con Ollama i dati dello schema e le domande restano sul tuo computer o sulla tua rete: utile con dati riservati. I servizi cloud (Anthropic, OpenAI) sono di norma più precisi sulle query complesse ma inviano il prompt a un servizio esterno. Scegli in base alla riservatezza richiesta.

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.

Esporta pacchetto semantico
  1. Dal menu Schema Designer scegli Esporta pacchetto semantico (server)….
  2. Se nessuna tabella ha una configurazione, un messaggio ti invita a configurarne almeno una (clic destro sulla tabella → ⚙ Configura semantica…) prima di esportare.
  3. 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.
  4. Alla fine un messaggio riporta quante tabelle configurate sono state esportate.
Modello a stellaIl modello a stella (parte H) è un livello separato dalla configurazione semantica: non è incluso nel pacchetto semantico.

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:

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.

TabellaRuoloRigheContenuto
DIM_DATEdimensione data365ogni giorno del 2026; DATE_KEY è la data in forma AAAAMMGG
DIM_CUSTOMERdimensione20clienti con città, regione, paese e segmento
DIM_PRODUCTdimensione10prodotti con categoria (5) e brand
DIM_STOREdimensione5negozi con canale: Retail, E-commerce, B2B
DIM_CAMPAIGNdimensione5campagne con tipo, canale, date di inizio e fine
FACT_SALESfact1.607una riga per riga d’ordine: quantità, prezzo, sconto, ricavi, costi, margine
FACT_ORDER_HEADERfact786una riga per ordine: canale, pagamento, stato (nessuna misura)
FACT_RETURNSfact137una riga per reso: quantità, rimborso, motivo, esito
FACT_INVENTORY_SNAPSHOTfact600giacenze a fine mese per prodotto e negozio (10 × 5 × 12)
FACT_BUDGETfact300budget e consuntivo per mese, categoria e negozio (12 × 5 × 5)
FACT_CAMPAIGN_PERFORMANCEfact122impression, 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.

Per riprodurre gli esempiLo script è per Firebird 3 ed elimina e ricrea le tabelle e le viste con questi nomi: eseguilo con 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ì.
Da dove vengono i numeriOgni risultato di questa parte è stato ottenuto eseguendo l’SQL generato dal programma sui dati dello script, e confrontato con un calcolo indipendente e con le viste dello script: i totali coincidono. Nell’ultima cifra decimale i motori possono arrotondare in modo diverso.

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 cosaCome funziona
Dove vive il modelloNella sezione "star_model" del file dello schema (Salva schema, C9). Un file salvato prima di questa funzione si apre normalmente, con il modello vuoto.
RiferimentiIl modello cita tabelle e colonne per identificatore, non per nome: rinominare una tabella o una colonna nel Designer non lo rompe.
ModificheSe 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 semanticoIl modello a stella è separato dalla configurazione semantica: non è incluso nel pacchetto del G18.
UscitaL’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

ElementoRegola
FactTabella 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).
TestataUna 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.
DimensioneOgni 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…).
MisureColonne 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…).
DegeneriNumeri 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.
SCDUna 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.
CalendarioNella 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

FactTipoDimensioniMisureDegeneri
FACT_SALEStransazionaleDIM_DATE, DIM_CUSTOMER, DIM_PRODUCT, DIM_STOREQUANTITY, UNIT_PRICE, DISCOUNT_AMOUNT, REVENUE, COST_AMOUNT, GROSS_MARGINORDER_NUMBER, ORDER_LINE
FACT_ORDER_HEADERsenza misureDIM_DATE, DIM_CUSTOMER, DIM_STORE—ORDER_NUMBER, ORDER_CHANNEL, PAYMENT_METHOD, ORDER_STATUS
FACT_RETURNStransazionaleDIM_DATE, DIM_CUSTOMER, DIM_PRODUCT, DIM_STORERETURNED_QUANTITY, REFUND_AMOUNTORIGINAL_ORDER_NUMBER, ORIGINAL_ORDER_LINE, RETURN_REASON, RESOLUTION_TYPE
FACT_INVENTORY_SNAPSHOTsnapshot periodicoDIM_DATE, DIM_PRODUCT, DIM_STOREQUANTITY_ON_HAND, QUANTITY_RESERVED, QUANTITY_AVAILABLE, QUANTITY_INCOMING, INVENTORY_VALUE—
FACT_BUDGETtransazionaleDIM_STOREREVENUE_TARGET, REVENUE_ACTUAL, REVENUE_VARIANCEBUDGET_YEAR, BUDGET_MONTH, PRODUCT_CATEGORY
FACT_CAMPAIGN_PERFORMANCEtransazionaleDIM_CAMPAIGN, DIM_DATEIMPRESSIONS, 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.

Da rivedere sempre

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.

FactGrain (una riga è…)Colonne del grain
FACT_SALESUna riga per ogni riga d'ordine venduta (ORDER_NUMBER + ORDER_LINE)ORDER_NUMBER, ORDER_LINE
FACT_ORDER_HEADERUna riga per ordineORDER_NUMBER
FACT_RETURNSUna riga per ogni reso registratoRETURN_KEY
FACT_INVENTORY_SNAPSHOTUna riga per prodotto, negozio e fine meseSNAPSHOT_DATE_KEY, PRODUCT_KEY, STORE_KEY
FACT_BUDGETUna riga per mese, categoria di prodotto e negozioBUDGET_YEAR, BUDGET_MONTH, PRODUCT_CATEGORY, STORE_KEY
FACT_CAMPAIGN_PERFORMANCEUna riga per campagna e giornoCAMPAIGN_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:

TipoSignificatoNello schema di esempio
transazionaleUna riga per evento, mai modificataFACT_SALES, FACT_RETURNS, FACT_CAMPAIGN_PERFORMANCE, FACT_BUDGET
snapshot periodicoUna riga per soggetto a ogni periodo (la fotografia di fine mese). Richiede il ruolo temporaleFACT_INVENTORY_SNAPSHOT
snapshot accumulanteUna riga per processo, aggiornata a ogni tappa (ordinato, spedito, consegnato), con più datenessuna
senza misureRegistra 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àRegolaEsempi nello schema
additivaSi somma lungo tutte le dimensioni.REVENUE, QUANTITY, COST_AMOUNT, REFUND_AMOUNT, MARKETING_SPEND
semi-additivaSi 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 additivaNon 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:

CampoChe cosa decide
Additivitàadditiva, semi-additiva (non si somma nel tempo), non additiva
AggregazioneL’aggregazione usata quando non ne scegli una: SUM, COUNT, COUNT DISTINCT, AVG, MIN, MAX, LAST, FIRST
Nel tempoSolo 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).

Il caso del prezzo unitarioSul prezzo unitario 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

DimensioneChiave surrogataChiave naturaleAttributiFact che la usano
DIM_DATEDATE_KEYCALENDAR_DATE95
DIM_CUSTOMERCUSTOMER_KEYCUSTOMER_CODE73
DIM_PRODUCTPRODUCT_KEYPRODUCT_CODE53
DIM_STORESTORE_KEYSTORE_CODE55
DIM_CAMPAIGNCAMPAIGN_KEYCAMPAIGN_CODE61

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:

FactDIM_DATEDIM_CUSTOMERDIM_PRODUCTDIM_STOREDIM_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.

Nello schema di esempioNessuna fact ha due FK verso la stessa 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]│
└──────────────────────┴──────────────────────┴────────────────────────────┘
  1. Proponi modello dallo schema — bozza di fact e dimensioni (H3)
  2. Valida modello — segnalazioni STARxxx (H14)
  3. Albero Fatti / Dimensioni — sotto, una riga di suggerimento sul nodo selezionato
  4. Proprietà — grain e tipo della fact, additività e aggregazioni della misura, nome del ruolo; Applica al modello, + Derivata…, Elimina derivata, Colonne del grain…
  5. Raggruppa per (righe) — + Attributo, ↑ Su, Rimuovi
  6. Misure (colonne) — + Misura, aggregazione della misura selezionata, Rimuovi
  7. Filtri — operatore, valore, + Filtro, Rimuovi
  8. Subtotali (ROLLUP) e Escludi i fatti senza riga di dimensione (INNER JOIN)
  9. SQL generato — aggiornato a ogni modifica; la riga sopra dice la forma della query
  10. Segnalazioni — codici QRYxxx della query (H14)
  11. 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

GestoEffetto
Doppio clic su un attributoLo 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 misuraLa aggiunge a Misure. Numero di righe conta le righe della fact al suo grain, con COUNT(*).
Selezionare un attributo e premere + FiltroAggiunge un filtro con l’operatore e il valore scritti accanto (H8).
Cambiare l’aggregazione nell’elenco MisureSeleziona la misura nell’elenco e scegli l’aggregazione: l’SQL si aggiorna. “predefinita” usa quella del modello.

Dove va l’SQL

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?

  1. Apri FACT_SALES › Dimensioni › DIM_PRODUCT e fai doppio clic su CATEGORY; poi DIM_STORE e doppio clic su CHANNEL. Compaiono in Raggruppa per, nell’ordine in cui li scegli.
  2. Apri FACT_SALES › Misure e fai doppio clic su REVENUE e su GROSS_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
CATEGORYCHANNELREVENUEGROSS_MARGIN
AudioB2B29.865,658.448,65
AudioE-commerce23.280,256.681,25
AudioRetail64.796,7018.271,70
MonitorB2B37.878,609.983,60
MonitorE-commerce50.092,2513.217,25
MonitorRetail136.592,6535.516,65

Prime 6 righe di 15.

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:

AttributoOperatoreValore
DIM_CUSTOMER › SEGMENTINBusiness; Enterprise
DIM_DATE › CALENDAR_DATEBETWEEN01/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
BRANDREVENUEQUANTITYROW_COUNT
DataFlash18.994,3012461
KeyLab12.896,5514957
SoundCore19.486,1513458
TechNova143.038,9513353
ViewMax47.002,0513558

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.

CategoriaSUM su tutto l’anno (sbagliata)LAST nel tempo (giusta)
Audio15.3081.542
Monitor14.1141.320
Notebook15.1591.583
Periferiche14.6361.151
Storage15.6911.667
Totale74.9087.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
CATEGORYQUANTITY_ON_HANDINVENTORY_VALUE
Audio1.542120.707,00
Monitor1.320325.117,00
Notebook1.5831.113.301,00
Periferiche1.15164.264,00
Storage1.667173.284,00
  1. base: somma le misure per categoria e per istante (una riga per categoria e fine mese).
  2. bounds: trova per ogni categoria il primo e l’ultimo istante.
  3. 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_QUARTERQUANTITY_ON_HAND
16.021
26.272
36.245
47.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):

CATEGORYQUANTITY_ON_HAND
Audio1.275,67
Monitor1.176,17
Notebook1.263,25
Periferiche1.219,67
Storage1.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.

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
CATEGORYREVENUE (FACT_SALES)REFUND_AMOUNT (FACT_RETURNS)
Audio117.942,606.809,20
Monitor224.563,508.743,55
Notebook784.707,1547.179,95
Periferiche72.743,603.849,60
Storage109.530,255.918,40

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_QUARTERREVENUE (FACT_SALES)REFUND_AMOUNT (FACT_RETURNS)
1271.409,8517.457,75
2370.535,4524.967,30
3354.635,8515.333,20
4312.905,9514.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:

CHANNELREVENUE (FACT_SALES)REVENUE_TARGET (FACT_BUDGET)
B2B262.133,551.568.118,00
E-commerce327.485,851.540.501,00
Retail719.867,704.750.247,00
Attenzione ai dati di esempioNello script il budget (circa 7,9 milioni) e il consuntivo di 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.

  1. Seleziona nell’albero la fact (o una sua misura).
  2. Premi + Derivata… sotto il pannello Proprietà.
  3. Scrivi il nome (per esempio ROAS) e poi la formula.
FactMisura derivataFormula
FACT_SALESMargine %100.0 * {GROSS_MARGIN} / NULLIF({REVENUE}, 0)
FACT_BUDGETScostamento %100.0 * {REVENUE_VARIANCE} / NULLIF({REVENUE_TARGET}, 0)
FACT_CAMPAIGN_PERFORMANCECTR %100.0 * {CLICKS} / NULLIF({IMPRESSIONS}, 0)
FACT_CAMPAIGN_PERFORMANCEROAS{ATTRIBUTED_REVENUE} / NULLIF({MARKETING_SPEND}, 0)

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_NAMEMARKETING_SPENDATTRIBUTED_REVENUECTR %ROAS
Audio Summer107.808,52668.136,392,606,20
Back to School61.848,80497.109,742,848,04
Black Friday Tech69.085,03377.010,132,945,46
Corporate Upgrade267.588,531.699.799,792,486,35
Spring Storage73.293,74472.148,292,236,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_MONTHREVENUE_TARGETREVENUE_ACTUALScostamento %
1638.703,00623.183,23-2,43
2699.041,00674.052,95-3,57
3641.032,00625.490,01-2,42
4608.257,00571.909,76-5,98
5649.732,00632.342,24-2,68
6708.807,00685.392,78-3,30
7648.170,00632.030,04-2,49
8604.988,00545.198,63-9,88
9616.928,00565.382,29-8,36
10717.971,00675.888,53-5,86
11770.428,00728.363,20-5,46
12554.809,00545.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_QUARTERCATEGORYREVENUEGROSS_MARGINMargine %
1Audio24.413,456.976,4528,58
1Monitor42.887,0511.396,0526,57
1Notebook155.802,9042.845,9027,50
1Periferiche14.882,554.286,5528,80
1Storage33.423,9010.266,9030,72
2Audio28.227,307.783,3027,57
2Monitor55.435,4013.977,4025,21
2Notebook241.426,3565.145,3526,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
CATEGORYCHANNELREVENUE
AudioB2B29.865,65
AudioE-commerce23.280,25
AudioRetail64.796,70
AudioNULL117.942,60
NULLNULL1.309.487,10

Che cosa cambia da un dialetto all’altro

DialettoROLLUPNULL tipizzati (drill-across)
Firebird, InterBasenon supportato: ignorato con avviso (QRY013)sì: CAST(NULL AS DOUBLE PRECISION)
SQLite, MS Accessnon supportato (QRY013)no
MySQL, MariaDBGROUP BY a, b WITH ROLLUP (senza ORDER BY, QRY017)no
PostgreSQL, SQL Server, OracleGROUP BY ROLLUP (a, b)no
IBM DB2GROUP 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_REASONROW_COUNTREFUND_AMOUNT
Cambio idea2910.907,15
Danno trasporto2815.054,05
Errore ordine3322.626,60
Non conforme2614.468,30
Prodotto difettoso219.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_METHODORDER_STATUSROW_COUNT
BonificoAnnullato54
BonificoConsegnato46
BonificoIn preparazione49
BonificoIn transito62
CartaAnnullato51
CartaConsegnato47
CartaIn preparazione43
CartaIn transito51

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).

Limiti e consigli

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)

CodiceTipoSignificato
STAR001erroreTabella dichiarata come fact o dimensione ma assente dallo schema.
STAR002erroreGrain della fact non dichiarato.
STAR003avvisoFact senza dimensioni.
STAR004erroreRuolo che punta a una dimensione non dichiarata.
STAR005erroreColonna FK del ruolo mancante o non appartenente alla fact.
STAR006erroreStessa dimensione usata più volte senza nomi di ruolo distinti.
STAR007errore / avvisoMisura senza colonna (errore) o con colonna non numerica (avviso).
STAR008avvisoMisura semi-additiva senza aggregazione nel tempo.
STAR009erroreAggregazione SUM su una misura non additiva o derivata.
STAR010errore / avvisoMisura derivata: riferimento a una misura inesistente (errore); misura derivata annidata o con additività incoerente (avviso).
STAR011erroreSnapshot periodico senza ruolo temporale principale.
STAR012errore / avvisoChiave surrogata mancante (errore) o diversa dalla chiave primaria (avviso).
STAR013avvisoDimensione senza chiave naturale.
STAR014erroreAttributi Type 2 senza colonne di validità (inizio, fine, versione corrente).
STAR015erroreDimensione Type 2 con chiave surrogata uguale alla chiave naturale.
STAR016erroreLivello di gerarchia su una colonna che non appartiene alla dimensione.
STAR017erroreStessa tabella dichiarata sia fact sia dimensione.
STAR018infoNessuna FK fisica fra fact e dimensione (lecito in un DW).
STAR019erroreNomi di misura duplicati nella stessa fact.
STAR020errore / avvisoColonne del grain inesistenti (errore) o non indicate (avviso).
STAR021infoDimensione non usata da nessuna fact.
STAR022infoSnowflake: dimensione con una FK verso un’altra dimensione.
STAR023avvisoChiave surrogata della dimensione data non intera.
STAR024erroreMembri Sconosciuto e Non applicabile con la stessa chiave.
STAR025erroreColonna usata sia come misura sia come FK di dimensione.
STAR026avvisoRuolo temporale che non corrisponde a nessun ruolo della fact.
STAR027erroreColonna di attributo, chiave o validità non appartenente alla dimensione.

Query (QRY)

CodiceTipoSignificato
QRY001erroreNessuna misura richiesta.
QRY002erroreFact non dichiarata nel modello, o tabella assente dallo schema.
QRY003erroreMisura inesistente, o componente inesistente di una misura derivata.
QRY004erroreAttributo di una tabella non dichiarata come dimensione.
QRY005erroreAttributo di una dimensione non collegata alla fact (o a una delle fact).
QRY006erroreRuolo ambiguo: dimensione con più ruoli e nome del ruolo assente o errato.
QRY007erroreColonna dell’attributo o della misura assente.
QRY008avvisoAggregazione corretta dalla regola di additività (per esempio SUM → AVG, SUM → LAST).
QRY009erroreLAST o FIRST richiesti senza un ruolo temporale.
QRY010avvisoMisura semi-additiva in una fact senza ruolo temporale.
QRY011erroreCOUNT DISTINCT non calcolabile nel calcolo a due livelli.
QRY012avvisoROLLUP ignorato: la query non è semplice.
QRY013avvisoROLLUP non supportato dal dialetto.
QRY014avvisoROLLUP con misura semi-additiva e tempo nel raggruppamento.
QRY015erroreJOIN impossibile: chiave surrogata della dimensione non determinabile.
QRY016erroreFiltro con valori mancanti o non validi per il tipo della colonna.
QRY017infoCon WITH ROLLUP (MySQL) l’ORDER BY viene omesso.
QRY018infoROLLUP con LEFT JOIN: i NULL dei membri mancanti si confondono con i subtotali.

H15. Limiti e problemi comuni

Limiti attuali

LimiteDettaglio
“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

SintomoCausaChe 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

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

CodiceSignificato
ETLSTAR001Una FK della fact non è mappata
ETLSTAR002/003La FK è copiata direttamente, o il lookup punta al posto sbagliato
ETLSTAR004/005Lookup senza valore di ripiego (membro Sconosciuto) o che non sceglie la versione corrente SCD2
ETLSTAR006/007Rilanciando l’ETL i fatti si duplicano; la chiave di idempotenza non coincide col grain
ETLSTAR008La fase del fatto viene prima di quella della dimensione
ETLSTAR009-014Dimensione scritta direttamente, senza chiavi naturali, staging non svuotato o non deduplicato, chiave naturale o attributo non mappati
ETLSTAR015-017SQL dopo l’import mancante, diverso da quello generato, o non sulla connessione di destinazione
ETLSTAR018/019Dimensione usata ma non caricata da nessuna fase; errore nella generazione dell’SQL

Che cosa devi fare tu

  1. Crea nel database di destinazione le tabelle STG_<dimensione> con le chiavi naturali e gli attributi (lo strumento non genera DDL).
  2. Crea le fasi ETL (una per dimensione verso lo staging, una per fatto) e mappa i campi: le fasi non vengono create in automatico.
  3. Apri la finestra, leggi le segnalazioni, premi Applica correzioni, salva il progetto ETL.

Limiti

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:

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

Modalità ETL123456789101112
  1. Barra strumenti ETL (stessi comandi del menu ETL)
  2. Schede di modalità: ETL attiva
  3. Filtra fasi… cerca tra fasi e campi
  4. Espandi / comprimi tutto o la fase corrente
  5. Regola evidenziata: una trasformazione
  6. Regola diretta: copia semplice
  7. Pannello Regola sul campo
  8. Query iniziale / Query finale della fase
  9. Anteprima dati: Origine e Destinazione
  10. Totale record dell’origine
  11. Fasi ETL pianificate
  12. 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]:

In stato vuoto l’albero propone due scorciatoie: Nuova fase e Abbina automaticamente.

D3. Creare un progetto

  1. 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.
  2. Crea le fasi in uno dei modi seguenti.
  3. Definisci le regole dei campi (D5).
  4. Salva il progetto (D10) ed esegui (D8).

Tre modi per creare le fasi

MetodoCome funziona
Nuova faseMenu ETL → Nuova fase: scegli tabella di origine e di destinazione (o una query personalizzata) e le connessioni.
Nuova fase dall’alberoParte dalla tabella selezionata nell’albero dei database.
Abbina automaticamenteScegli 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

D4. Impostazioni della fase

Dal clic destro sulla fase → Modifica impostazioni si apre una finestra a schede.

SchedaChe cosa imposta
Sorgente / DestinazioneConnessione 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.
OpzioniFase 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.
DedupElimina i duplicati sulla base di uno o più campi; con Tieni l’ultimo e un criterio di ordinamento decidi quale riga sopravvive.
IdempotenzaChiave di idempotenza (campi o espressione) per evitare di riscrivere righe già elaborate. Il suggerimento sulla scheda spiega i compromessi.
TransazioniModalità: 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.
FormatiFormato data, separatore decimale e separatore delle migliaia predefiniti, usati quando l’origine contiene testo da convertire (tipico dei CSV).
Query iniziale / Query finaleSQL 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.

Verifica prima di eseguirePrima dell’esecuzione il progetto viene validato: campi chiave mancanti, identificatori non validi, campi di dedup assenti e simili producono errori o avvisi, che trovi nel log.

D5. Regole sul campo

Finestra Regola sul campo1234567
  1. Campo origine e Campo destinazione, con il tipo di ciascuno
  2. Avviso tipi diversi
  3. Regola: il tipo di trasformazione
  4. Espressione e pulsante Assistente…
  5. Esegui regola solo se: condizione
  6. Anteprima sui valori reali dell’origine
  7. 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.

RegolaCosa fa
DirettoCopia 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.
CostanteScrive sempre lo stesso valore (per esempio -1 o 100), a prescindere dall’origine.
EspressioneCalcola il valore con una formula (vedi sotto). Nell’albero compare come [Espressione = …].
LookupCerca 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.
IgnoraIl campo non viene scritto.
AutoincrementNumera le righe: parte da un valore iniziale oppure dall’ultimo valore già presente nella destinazione.
FormulaCombina 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}.

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:

GruppoCondizioni
ContenutoVuoto · Non vuoto · Solo spazi · Solo cifre · Solo lettere (accenti compresi) · Alfanumerico (almeno una lettera e una cifra)
TestoInizia con · Contiene · Termina con · Uguale · Diverso (senza distinzione tra maiuscole e minuscole)
LunghezzaLunghezza uguale · maggiore · minore
NumeriMaggiore · minore · uguale (accetta virgola e punto)
AltroEspressione regolare · Data valida nel formato indicato (per esempio dd/mm/yyyy)
Errori di scritturaUn’espressione regolare non valida o un numero non leggibile non bloccano l’esecuzione: quella condizione risulta semplicemente falsa e il campo prende il valore alternativo.

Compositore condizioni avanzato

Per le trasformazioni "se… allora…" con più condizioni il pulsante Compositore (o Apri compositore) costruisce per te un’espressione CASE:

  1. Scegli Campo, Operatore e Confronta con e premi Aggiungi condizione.
  2. Ripeti per aggiungere altre condizioni allo stesso ramo; decidi se devono essere tutte vere (E) o basta una (O).
  3. Scrivi il Risultato se il ramo è vero (oppure inseriscilo da un campo) e premi Conferma ramo.
  4. Aggiungi altri rami: compaiono in Rami già aggiunti; puoi rimuovere condizioni o rami.
  5. 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:

D8. Eseguire

AzioneCome
Eseguire tutto il progettoMenu ETL → Esegui oppure F9. Le fasi disattivate vengono saltate.
Provare una sola faseClic destro sulla fase → Esegui fase.
InterrompereETL → 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

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:

CampoSignificato
ConnessioniOrigine e destinazione. Il progetto deve avere le connessioni salvate: altrimenti il programma te lo segnala.
FrequenzaOgni ora · Giornaliera · Settimanale · Mensile · Fine settimana · Fine mese
Intervallo, OraOgni quanto ripetere l’esecuzione e a che ora
Giorno della settimana / del mesePer Settimanale e Mensile. Il giorno del mese ha una nota per i mesi più corti
Recupera esecuzione mancataSe 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:

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

VoceEffetto
ETL → Nuova fase / Nuova fase dall’alberoCrea una fase
ETL → Abbina automaticamenteCrea le fasi per le tabelle omonime
ETL → Modifica / Elimina fase, Svuota tutte le fasiGestione fasi
ETL → Nuovo / Modifica / Elimina / Genera campiGestione campi
ETL → Connessione origine / destinazione (dall’albero)Assegna la connessione selezionata nell’albero
ETL → Salva / Carica progettoFile .fdmap
ETL → Salva per il servizioSalva il progetto per l’esecuzione da servizio (con pianificazione)
ETL → Esegui (F9) / AnnullaEsecuzione

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):

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.

Le query vengono eseguite davveroPer misurare il tempo il Profiler esegue l’istruzione. Questo vale anche per 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.
Che cosa viene profilatoIl Profiler misura il testo SQL che c’è in quel momento nell’Editor, eseguendolo sulla connessione attiva dell’albero. Un Editor vuoto non avvia nulla. Su connessioni LocalSQL (file CSV, Excel, REST…) la misura gira sulla stessa connessione e in modo sincrono (l’interfaccia attende il risultato): è necessario perché le tabelle "virtuali" esistono solo su quella connessione. Sugli altri database la misura parte in background. L’acquisizione del piano è attiva per impostazione predefinita e le soglie partono da 150 e 600 ms.

E2. Che cosa viene misurato

Tipo di istruzioneCosa si misura
SELECT, WITH, SHOW, PRAGMA, EXPLAINIl 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 procedureTempo e righe. Per le procedure il piano non viene catturato.
Esecuzione in erroreIl tempo fino all’errore e il messaggio del database. Nessun piano.

E3. Soglie e colori

EsitoQuandoAspetto della barra
Buonameno di 150 msVerde
Attenzioneda 150 ms a meno di 600 msAmbra, con un piccolo indicatore di forma
Critica600 ms o piùRossa, con indicatore di forma
Errorela query è fallitaBordo 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

E5. Esaminare una misura

E6. Il piano di esecuzione

Il formato dipende dal motore: ognuno usa il proprio meccanismo.

MotoreCome si ottiene il piano
PostgreSQLEXPLAIN (ANALYZE, BUFFERS, FORMAT JSON): tempi reali, ma la query viene eseguita una seconda volta.
MySQLEXPLAIN FORMAT=JSON: non riesegue la query.
SQL ServerSHOWPLAN_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.
SQLiteEXPLAIN QUERY PLAN
OracleEXPLAIN 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.
FirebirdFirebird 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 AccessNessun piano: si misurano solo tempo e righe.

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.

Se la profilazione non parteUn messaggio indica la causa: nessuna connessione attiva nell’albero, query o connessione non impostate, oppure profilazione già in corso.

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:

Builder con la query per l'analisi12345
  1. Tab della connessione su cui gira la query (qui CSV_Conn, una connessione LocalSQL su CSV)
  2. Tabella nel diagramma, con i campi selezionati
  3. SQL generato nell’Editor
  4. Contatore del risultato: 45 righe x 3 col [0 ms]
  5. Griglia dei risultati
  1. 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).
  2. Prepara le colonne che servono al grafico: una colonna di etichette (la X) e una o più colonne numeriche (le Y). Aggiungi filtri, GROUP BY e 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).
  3. Esegui con Run. Controlla in griglia che le righe siano quelle attese (45 righe x 3 col).
  4. 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).
Prima esegui la querySe nell’Editor non c’è un risultato aperto (la query non è mai stata eseguita, o è stata chiusa), passando alla scheda Analisi compare il messaggio Active query e il programma ti riporta al Builder. Esegui la query con Run / Execute e poi riprova. Se cambi query nell’Editor, torna sul Builder, eseguila e rientra nell’Analisi per ricaricare i dati: il titolo del grafico riparte da Title e va rinominato.
Meno righe, grafici più leggibiliUna barra per ognuna di migliaia di righe non si legge: filtra o aggrega nel Builder, oppure usa TOP / LIMIT dal pannello SQL Avanzato (cap. 8). Oltre un certo numero di punti il grafico semplifica da solo i dati e lo segnala con la nota dati aggregati.
Cambiare querySe carichi una query diversa, i menu di colonna (X, Y, formati…) si azzerano: gli indici delle colonne non avrebbero più lo stesso significato.

F3. L’interfaccia

Analisi - grafico radar12345678910111213
  1. Esporta ▾: PNG, SVG, PDF, CSV, Excel
  2. Copia immagine negli appunti
  3. Salva ▾ / Carica ▾: configurazione o analisi completa
  4. Aggiorna: rilegge i dati
  5. Risoluzione (1x, 2x, 3x)
  6. Titolo del grafico
  7. Tipo grafico
  8. Colonna X (etichette)
  9. Colonne Y (valori): una o più colonne
  10. Opzioni di visualizzazione
  11. Formato numerico per colonna
  12. Grafico (qui un radar: ogni raggio è un paese, la distanza dal centro è la popolazione)
  13. 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.

F4. I tipi di grafico

TipoColonne necessarie
Barre · Barre impilate · Linee · Area · ComboX = etichette, una o più Y. Combo: ogni serie può essere barra o linea e usare l’asse Y di destra.
Torta · RadarX = etichette, Y = valori
IstogrammaUna 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) · BolleX = 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 plotX = categoria, una Y = valore. Il programma calcola minimo, primo quartile, mediana, terzo quartile e massimo per ogni categoria.
HeatmapX = 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).
TreemapX = etichetta, Y = valore (area del rettangolo). Facoltativo: Gruppo treemap, una seconda colonna che raggruppa i rettangoli in riquadri colorati.
SparklineX = 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.
SankeyColonne Sorgente e Destinazione (i nodi) e Y = flusso. Un solo salto: per più passaggi serve una query per ogni coppia.
Nel radar dello screenshotLa X è codice_iso, la Y è popolazione. Nella lista delle Y compaiono tutte le colonne della query: selezionane solo quelle numeriche.

F5. Opzioni di analisi

OpzioneEffettoVale per
Evidenzia outlierCerchia i punti oltre 2 deviazioni standard dalla media della serieBarre, Linee
Linea di tendenzaRegressione lineare sovrapposta alla serieTipi con asse cartesiano
Media mobile (N periodi)Linea tratteggiata più chiara per ogni serie visibile. 0 = disattivataBarre, Barre impilate, Linee, Area, Combo
Soglia (valore + etichetta)Linea orizzontale tratteggiata con etichetta, per esempio un obiettivo mensileTipi con asse Y lineare (non torta, radar, mappe, heatmap, funnel, treemap, sparkline, Sankey)
Intervalli istogrammaNumero di intervalli (2–100)Istogramma
Max puntiOltre questo numero il grafico semplifica i dati e segnala dati aggregati. 0 = valore predefinitoTutti

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à

Analisi - mappa coropletica1234567
  1. Livello mappa: Regioni o Province
  2. File mappa (cartella mappe) e pulsante per rileggere la cartella
  3. Densità (KDE) al posto delle regioni
  4. Colori della scala: bassa, media, alta densità
  5. Scala dei colori con minimo e massimo
  6. Classifica dei valori (con "+N altre")
  7. Zoom: "zoom attivo — doppio click per reset"

La mappa colora ogni area in base al valore. Per usarla:

  1. Nel Builder prepara una query con una colonna codice e una colonna valore (nell’esempio codice_iso e popolazione).
  2. Scegli il tipo Mappa (Choropleth), la colonna del codice come X e il valore come Y.
  3. Scegli il File mappa tra quelli trovati nella cartella mappe accanto al programma (nell’esempio europe.geojson). Se aggiungi un file mentre il programma è aperto, premi il pulsante di aggiornamento accanto all’elenco.

F7. Formato dei numeri

Nella sezione Formato numerico colonna scegli una colonna e il formato con cui mostrarne i valori:

ImpostazioneEffetto
FormatoAutomatico (K/M) (predefinito: 91.8M, 764…), Numero, Valuta o Percentuale
DecimaliNumero di cifre decimali
Separatore migliaiaAttiva il punto delle migliaia
Simbolo valutaPer 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

PulsanteRisultato
Esporta ▾ → PNGImmagine del grafico. Il selettore Risoluzione (1x, 2x, 3x) regola la definizione delle immagini
Esporta ▾ → SVGImmagine vettoriale (testo XML)
Esporta ▾ → PDFDocumento PDF con il grafico
Esporta ▾ → CSVI dati del grafico, con i formati scelti
Esporta ▾ → ExcelFile .xlsx; se possibile con il grafico incluso, altrimenti solo i dati: un messaggio ti dice cosa è stato salvato
Copia immagineMette il grafico negli appunti, senza finestra di salvataggio: ideale per incollarlo in Word o PowerPoint

Salvare l’analisi

VoceCosa 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 completaLa 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.
Analisi salvata su un altro computerLa protezione DPAPI lega il file all’utente e al computer Windows che l’hanno salvato: aprendo un .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

F11. Problemi comuni

SintomoCausa e rimedio
Il grafico è vuotoLa query non ha restituito righe, oppure le colonne Y scelte non sono numeriche. Controlla la griglia nel Builder o nell’Editor.
Troppe barre, illeggibileAggrega o filtra nella query, o usa TOP / LIMIT.
Le candele sono sbagliateServono 4 colonne esattamente nell’ordine apertura, massimo, minimo, chiusura: riordinale nella query.
La mappa è vuota o poche aree sono colorateI 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’aggiornamentoLa connessione della query non è aperta: connettila dall’albero e riprova.
Riaprendo un’analisi con password non parteIl 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

Schermata del Builder 1 2 3 10 4 5 6 7 8 9
  1. Barra comandi: esecuzione, salvataggio, ERD, Explain… (cap. 9)
  2. Tab: una riga per connessione e una per le query (cap. 11)
  3. Nodo tabella: nome, alias e campi (cap. 4)
  4. Ricerca campo dentro il nodo
  5. Relazione tra due campi: JOIN (cap. 5)
  6. Contatore campi visibili / totali, con frecce di scorrimento
  7. Pannello SQL Avanzato (cap. 8)
  8. Minimap per orientarsi in diagrammi grandi
  9. Zoom − / percentuale / +
  10. 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.

Se non succede nullaControlla che la connessione sia connessa e che l’albero non sia in modalità sfoglia dati (Browse): in quel caso il doppio clic apre i dati della tabella nella griglia invece di aggiungerla al Builder.

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:

PulsanteFunzione
×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

5. Relazioni e JOIN

Ogni campo ha un pallino sul bordo del nodo. Per creare un JOIN:

  1. Premi sul pallino del campo di partenza (lato destro) e trascina: segue il mouse una linea provvisoria.
  2. Rilascia sul campo dell’altra tabella.
  3. Nel popup JOIN type scegli il tipo di unione.
TipoNote
INNER JOINSolo le righe con corrispondenza in entrambe le tabelle.
LEFT / RIGHT / FULL JOINMantengono le righe senza corrispondenza di un lato o di entrambi.
CROSS JOINProdotto cartesiano.
CROSS APPLY / OUTER APPLYTipici di SQL Server.
JOIN LATERALTipico 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.

Controllo immediatoIl risultato di ogni scelta è visibile subito nel tab SQL Preview del pannello e nell’Editor sotto il canvas.

Clic destro su un campo. L’intestazione del menu riporta TABELLA.CAMPO (tipo).

VoceEffetto
AggregatesNo 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 BYIncludi 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 expressionCOALESCE, 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 tabellaEredita 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 nodeDuplica 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.

SezioneContenuto e azioni
Alias TabelleElenco delle tabelle con l’alias corrente (o nessun alias). Clic sulla matita ✎ per modificarlo.
Campi & AggregatiUna 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 / HAVINGI 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.
OpzioniDISTINCT, 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 PreviewAnteprima dell’SQL generato, con colorazione delle parole chiave.
Testo libero (RAW)Dove inserisci espressioni libere (HAVING, WHERE RAW, hint) compare un’etichetta RAW: quel testo viene copiato nell’SQL così com’è, senza controlli di dialetto.

9. Barra comandi

PulsanteAzioneRequisiti
RunGenera l’SQL, lo porta nell’Editor ed esegue.Connessione attiva
SchemaImporta lo schema dalla connessione.Connessione
ClearSvuota il diagramma, previa conferma. Si può annullare con Undo.—
Save / LoadSalva e carica il diagramma in un file .json. Se il file non è valido il diagramma corrente resta invariato.—
PrintStampa il diagramma su più pagine.—
Undo / RedoAnnulla e ripristina; ogni azione sul modello è un singolo passo.—
SQLCopia l’SQL generato negli appunti.—
FitAdatta lo zoom per mostrare tutto il diagramma.—
ERDAlterna la vista Builder e la vista diagramma entità-relazione.—
DDLMostra lo script DDL del diagramma.—
AIGenera la query da una richiesta in linguaggio naturale.Servizio AI configurato
PerfPerformance Advisor: suggerimenti sulla query.—
SnipLibreria di snippet.—
ExportEsporta il diagramma in PNG, SVG, HTML o Markdown.—
TabsAggiunge un nuovo tab di query (chiede il nome).—
SubqInserisce un nodo subquery.—
ExplPiano di esecuzione in forma testuale (interruttore).Connessione
ExpGPiano di esecuzione come grafo di nodi.Connessione
CmpPlanConfronto tra due piani di esecuzione.Connessione
Save.fdp / Load.fdpSalva e apre il progetto .mfdproj (vedi cap. 13).—
GestoEffetto
Rotella del mouseZoom 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 nodoSposta la tabella; al rilascio si aggancia alla griglia.
Trascina sullo sfondoSelezione ad area (rubber band).
Ctrl + clicAggiunge o toglie un nodo dalla selezione multipla; trascinandone uno si muove tutto il gruppo.
MinimapTrascina 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.

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.

Builder o Free?Finché il pulsante dell’Editor mostra [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

CosaCome
Un diagrammaSave / Load → file .json.
Una query come immagine o documentoExport → PNG, SVG, HTML, Markdown.
L’intero progettoSave.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 ricorrenteCtrl+Shift+S la salva come snippet.

14. Scorciatoie da tastiera

TastiAzione
F1Guida alle scorciatoie
Ctrl+Z / Ctrl+YAnnulla / ripristina
Ctrl+ASeleziona tutti i nodi
Ctrl+CCopia l’SQL generato
Ctrl+DDuplica il nodo selezionato
Ctrl+FCerca tabelle e campi nel diagramma
Ctrl+RTrova e rinomina ovunque
Ctrl+Shift+F / Ctrl+G / Ctrl+0Adatta tutto / zoom sulla selezione / reset zoom
+ / −Zoom avanti / indietro
Tab / Shift+TabNodo successivo / precedente
CancElimina il nodo o la relazione selezionati
EscAnnulla la relazione in corso o chiude l’overlay
Ctrl+EExplain Plan a grafo
Ctrl+HStorico query
Ctrl+PStampa
Ctrl+T / Ctrl+W / Ctrl+TabNuovo tab / chiudi tab / tab successivo
Ctrl+Shift+S / Ctrl+Shift+LSalva come snippet / apri libreria snippet
Ctrl+Shift+TTema 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.

Editor SQL12345678910
  1. Execute: esegue la query
  2. [FR] Free / [QB] Builder: chi comanda il testo
  3. Undo / Redo
  4. Copia, Find, Format, ⚙, Pulisci, Carica
  5. Script: esecuzione batch
  6. Tx, OK, RB: transazione
  7. Hist: cronologia
  8. Tab dell’Editor (connessione e query)
  9. Gutter con i numeri di riga
  10. 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

17. Modalità Builder / Free

Il pulsante accanto a Execute decide chi è proprietario del testo:

PulsanteSignificato
[QB] BuilderIl testo è quello generato dal Builder e viene riscritto a ogni modifica del diagramma.
[FR] FreeSQL libero: il Builder non tocca più l’Editor. Execute esegue ciò che hai scritto.
Flusso consigliatoCostruisci la base nel Builder, passa a [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

AzioneComeDettagli
Eseguire la queryExecute, F5 o Ctrl+InvioRichiede 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 scriptScript o F6Esegue 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 .sqlCarica o Ctrl+OIl file si apre in un nuovo tab. Sono accettati sia UTF-8 sia file ANSI vecchi (per esempio salvati da Notepad).
Senza connessioneSe la connessione non è aperta, l’esecuzione mostra un messaggio d’aiuto invece di partire. Connettiti dall’albero e riprova.

19. Transazioni

Per default le istruzioni vengono eseguite normalmente. Per raggruppare più modifiche in un’unica transazione usa i tre pulsanti:

PulsanteAzioneAttivo quando
● TxBEGIN TRANSACTION (Ctrl+B)Connessione aperta e nessuna transazione in corso
✔ OKCOMMITTransazione in corso
↺ RBROLLBACKTransazione 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.

ElementoFunzione
Riga di statoRighe restituite o interessate, oppure l’errore su una riga sola (il dettaglio completo è nel pannello Messaggi).
Ricerca 🔍Filtra le righe già caricate.
PaginazionePer 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.
ExportCSV, JSON, XML, XLSX, oppure script SQL di INSERT INTO.
✎ ModificaRende 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.
MsgMostra o nasconde il pannello Messaggi (log di esecuzioni, errori, transazioni); il pulsante × Pulisci lo svuota.

21. Barra comandi

PulsanteAzione
ExecuteEsegue la query (F5).
[FR] Free / [QB] BuilderCambia la modalità (cap. 17).
↶ ↷Annulla / ripristina la digitazione.
CopiaCopia tutto il testo negli appunti.
FindTrova e sostituisci (Ctrl+H): Trova successivo, Sostituisci, Sostituisci tutto, con modalità Regex.
FormatFormatta l’SQL: parole chiave maiuscole e indentazione.
⚙Opzioni del formattatore.
PulisciSvuota il tab corrente.
CaricaApre uno o più file .sql in nuovi tab (Ctrl+O).
ScriptEsegue come batch (F6).
Tx / OK / RBTransazione (cap. 19).
HistCronologia 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.

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

TastiAzione
F5 / Ctrl+InvioEsegui
F6Esegui come script
F2 / Ctrl+SpazioIntelliSense
Ctrl+/Commenta / decommenta la riga
Ctrl+HTrova e sostituisci
Ctrl+BBEGIN TRANSACTION
Ctrl+OCarica file .sql
Ctrl+Alt+HCronologia
Ctrl+T / Ctrl+W / Ctrl+TabNuovo tab / chiudi tab / tab successivo
TabInserisce due spazi

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
BuilderFile, Modifica, Query, Vista, Schema, DDL, Connessione, Tab, Snippet, Strumenti, Impostazioni, Extra, ?
DesignerCompare il menu Schema Designer; Query, Vista e Schema (quelli del Builder) sono nascosti
ETLCompare il menu ETL. Modifica, DDL, Connessione, Tab, Snippet, Strumenti ed Extra sono nascosti; restano File, Impostazioni e ?
AnalisiCompare il menu Analisi (aggiorna, esporta, configurazione)
Nomi delle vociI nomi qui sono descrittivi, ricavati dalla funzione di ciascun comando: il testo esatto dipende dalla lingua scelta in Impostazioni → Lingua.
Scorciatoie uguali, modalità diverseAlcune combinazioni sono riusate in modalità diverse (per esempio F7, Ctrl+Shift+I e Ctrl+Shift+0 nel Designer). Nel Builder F5 è assegnato sia a Esegui sia ad Aggiorna albero.

26. Menu File

VoceScorciatoiaQuando è attiva
Nuovo progettoCtrl + NSempre
Nuovo tab editor / Chiudi tab editorCtrl + T / Ctrl + WChiudi: se esiste almeno un tab
Salva tab editorCtrl + Shift + ESolo se il tab è stato modificato
Carica file SQLCtrl + OApre uno o più file in nuovi tab
Salva progettoCtrl + SSolo con modifiche non salvate
Salva progetto con nome—Sempre
Apri progetto (.mfdproj)Ctrl + Shift + OSempre
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 diagrammaCtrl + PModalità Builder, con almeno una tabella nel diagramma
Configurazione AI—Impostazioni del servizio AI
EsciAlt + F4

27. Menu Modifica

VoceScorciatoiaQuando è attiva
Annulla / RipristinaCtrl + Z / Ctrl + YAgiscono sul Builder o sul Designer attivo
Copia tutto l’SQLCtrl + Shift + CServe testo nell’editor
Trova / SostituisciCtrl + HServe testo nell’editor
Trova e rinomina globaleCtrl + Shift + RRinomina tabella o campo in tutto il diagramma. Modalità Builder, con almeno una tabella nel diagramma
Formatta SQL / Opzioni formattatoreCtrl + Shift + FLe opzioni sono sempre accessibili
Svuota editor—Serve testo nell’editor
Modalità FreeCtrl + Shift + MScollega 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

VoceScorciatoiaQuando è attiva
EseguiF5Serve SQL nell’editor e connessione
Esegui come scriptF6Come sopra, solo in modalità Builder
Esegui query del BuilderF7Esegue la query del tab attivo del Builder. Serve la connessione dell’albero
Begin / Commit / RollbackCtrl + B / Ctrl + M / Ctrl + Shift + BBegin 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 AICtrl + Shift + AGenera la query da linguaggio naturale
Genera prompt AICtrl + Shift + JPrompt 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

VoceScorciatoiaQuando è attiva
IntelliSenseCtrl + SpazioAttiva/disattiva il completamento automatico
Numeri di riga—Mostra/nascondi nell’editor
Pannello messaggiCtrl + Shift + G
Cronologia editorCtrl + 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 selezioneCtrl + 0 / Ctrl + Shift + 0Modalità Builder, con almeno una tabella nel diagramma
Reimposta vista—Solo Builder
Explain → Mostra piano, Grafo del piano, Confronta piani, NascondiCtrl + 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.

VoceScorciatoiaQuando è attiva
Importa schemaCtrl + IServe connessione. Solo Builder
Aggiorna albero / Espandi radiceF5 (Aggiorna)Serve l’albero
Invia schema a IntelliSenseCtrl + Shift + IServe albero, editor e connessione
Aggiungi tabella / Rimuovi tabellaCtrl + Shift + T / CancRimuovi: serve una tabella
Duplica tabella, Self-joinCtrl + DModalità 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 ricercaCtrl + FSolo Builder
Seleziona tutto / Deseleziona / Svuota diagrammaCtrl + A / EscModalità Builder, con almeno una tabella nel diagramma
Procedura guidata funzione scalare—Sul campo selezionato
Analizza campo—Statistiche (MIN/MAX/AVG…). Serve connessione
Pannello parametriCtrl + Shift + PPannello :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.

VoceScorciatoiaQuando è 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

VoceScorciatoiaQuando è 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

VoceScorciatoiaQuando è attiva
Nuovo tab editor / Chiudi tab editorCtrl + T / Ctrl + W
Nuovo tab queryCtrl + Alt + TAggiunge un tab al Builder
Rimuovi tab queryCtrl + Alt + WSolo 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.

VoceScorciatoiaQuando è attiva
Mostra snippetCtrl + Alt + SSfoglia 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

VoceScorciatoiaQuando è attiva
Valida diagrammaCtrl + Shift + VControlla 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 scorciatoieF1

36. Impostazioni, Extra e ?

VoceScorciatoiaQuando è 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.

MenuContenuto
Schema DesignerAggiungi 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.
ETLNuova 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.
AnalisiAggiorna (F5); esporta in PNG, SVG, CSV; salva e carica la configurazione.