Associazione Dati

L’associazione dati è il ponte tra il tuo database di progetto e i widget del tuo board IoT. Quasi qualsiasi proprietà configurabile di un widget — titoli, valori, colori, serie dei grafici, intervalli dei gauge — può essere alimentata dinamicamente da dati live provenienti dalla TimescaleDB del progetto. Questa pagina spiega come collegare le colonne delle tabelle alle proprietà dei widget e come raffinare i dati con i filtri.

Per uno sguardo più ampio su come i dati arrivano nel database del progetto, vedi la panoramica della Gestione dei Dati.

I due modi per associare i dati

Nel Board Studio di IronFlock esistono due modalità fondamentali di associazione:

1. Riferimenti a valore — associano un singolo valore scalare (il record più recente di una colonna) a una proprietà del widget.
2. Riferimenti a tabella — associano un intero set di risultati (più righe) a una proprietà del widget che si aspetta un array.

Entrambe le modalità supportano il filtraggio e offrono aggiornamenti in tempo reale: appena nuove righe arrivano nel database del progetto, le proprietà associate vengono aggiornate automaticamente, senza polling.

Riferimenti a valore

La maggior parte dei campi di configurazione di un widget attende un singolo valore — un titolo, una lettura numerica, un colore, un’etichetta di stato. Sotto questi campi nell’editor del widget trovi un piccolo interruttore di associazione dati.

Quando attivi l’interruttore e fai clic sul campo, si apre un menu a tendina con tutti i dati disponibili nel database del progetto. Puoi:

1. Scegliere una tabella dal database del progetto.
2. Scegliere una colonna all’interno di quella tabella da associare alla proprietà.

Esempio: Puoi associare il campo titolo di un widget gauge alla colonna name di una tabella machine, oppure il campo valore di un widget numerico all’ultima lettura di temperature in una tabella sensor_data.

Il valore più recente

Un riferimento a valore fornisce sempre il singolo valore più recente per la colonna selezionata. “Più recente” è determinato dalla colonna obbligatoria tsp — ogni tabella nel database del progetto ha una colonna timestamp tsp, e vince la riga con il tsp più grande.

Icona filtro

Una volta associata una colonna a una proprietà del widget, accanto all’interruttore dei dati sotto il campo appare una piccola icona filtro. Facendo clic si apre una finestra di dialogo dove configurare filtri che restringono le righe considerate per l’estrazione del valore. Vedi Configurazione dei filtri sotto.

Riferimenti a tabella

Alcuni widget si aspettano un array di valori invece di uno scalare. Un widget grafico, ad esempio, ha bisogno di molti punti (x, y) per tracciare una linea; un widget tabella ha bisogno di molte righe.

In questi casi, l’editor del widget mostra un pulsante Aggiungi (per aggiungere elementi dell’array manualmente) insieme a un interruttore di associazione dati accanto all’etichetta del campo.

• Modalità manuale: Fai clic su Aggiungi per appendere elementi uno alla volta con valori statici.
• Modalità associazione dati: Attiva l’interruttore per associare l’array a una tabella. Seleziona la tabella e ogni riga qualificante diventa un elemento dell’array.

Puoi usare l’icona filtro accanto all’interruttore per restringere le righe restituite esattamente a ciò che serve — vedi Configurazione dei filtri.

Mappare colonne ai campi di elemento array

Una volta attiva l’associazione dati per un riferimento a tabella, configuri un singolo modello di elemento array con valori dalla tabella collegata. Per un grafico a linee, gli elementi hanno bisogno di valori x e y — rendili data-driven scegliendo le colonne della tabella associata per ciascun asse. Ogni riga del set di risultati filtrato viene poi resa nel grafico usando quella mappatura.

Lo stesso schema vale per qualunque widget che accetta array: grafici a barre, tabelle, liste, heatmap e altri.

Configurazione dei filtri

I filtri restringono le righe usate da un riferimento a valore o a tabella. Le sezioni della finestra di dialogo vengono applicate nell’ordine in cui sono mostrate — che è anche l’ordine in cui le applica il database del progetto:

1. Finestra temporale mobile

Configura come i record vengono filtrati per tempo:

• Finestra mobile — mostra solo le righe degli ultimi N minuti, ore, giorni, ecc. rispetto a ora.
• Finestra temporale personalizzata — specifica i nomi di un parametro di inizio e di un parametro di fine. Questi nomi sono forniti a runtime da un Widget Calendario, che permette all’utente finale di scegliere un intervallo sul board.

2. Filtri arbitrari su colonne

Aggiungi un numero qualsiasi di filtri a livello di colonna usando una di queste sorgenti di valore:

• Valori costanti — valori hard-coded (es. status = 'active').
• Parametri filtro — valori forniti da un Widget Filtro tramite l’URL.
• Segmenti del path di routing — valori estratti dall’URL corrente tramite Widget di Navigazione.

3. Aggregazione

Per impostazione predefinita un’associazione restituisce righe non elaborate. Portala su Aggregato nel tempo e il database del progetto raggruppa i record selezionati in bucket temporali — oppure in categorie — restituendo un valore calcolato per ogni gruppo: medie orarie, record per macchina, il totale di oggi.

Poiché i filtri agiscono prima di questo passaggio, sono loro a decidere quali record entrano in ciascun bucket. L’aggregazione è trattata per intero in una pagina dedicata: vedi Aggregazione e Downsampling.

4. Limite righe

Imposta un tetto al numero di righe restituite per il widget. Il limite non può superare 3000 — questo tetto protegge sia il tuo browser sia il database del progetto da set di risultati sovradimensionati.

Per un’associazione aggregata il numero di bucket restituiti viene invece derivato dalla larghezza del widget o dall’intervallo che hai scelto, e il limite di righe funge solo da salvaguardia di riserva.

Tutte le sezioni si compongono: la finestra temporale restringe l’intervallo di tempo, i filtri di colonna affinano ulteriormente le righe, l’aggregazione le riduce a un valore per bucket e il limite di righe fissa l’output finale.

Selezione di campi da colonne JSON

Il database del progetto supporta colonne JSON per dati non strutturati o semi-strutturati (payload di telemetria dei dispositivi, blob di configurazione, record annidati).

Quando associ una colonna JSON a una proprietà del widget, compare un input aggiuntivo per specificare il percorso al campo foglia all’interno della struttura JSON. Il percorso usa la notazione standard degli oggetti JavaScript:

sensor.temperature
payload.items.0.value
metadata.location.city

Il widget estrae il valore in quel percorso da ogni record. Funziona sia per riferimenti a valore (la foglia estratta dal record JSON più recente) sia per riferimenti a tabella (la foglia estratta da ogni riga).

Riepilogo

• Usa i riferimenti a valore per proprietà scalari (titolo, valore, colore) — ottieni il valore più recente per tsp.
• Usa i riferimenti a tabella per proprietà array (serie di grafici, tabelle, liste) — mappi colonne ai campi di elemento array.
• Usa la finestra di dialogo dei filtri per affinare le righe con finestre temporali, filtri di colonna e limite righe (max 3000).
• Porta un’associazione su aggregata quando vuoi valori calcolati invece dei record — vedi Aggregazione e Downsampling.
• Usa la notazione di percorso JSON per esplorare colonne JSON non strutturate.