Lavorare con il dashboard parameters
Questo articolo illustra come usare parameters nei dashboard di intelligenza artificiale/BI. Per informazioni sui filtri dei campi, vedere Filtrare in base ai campi.
Il dashboard di intelligenza artificiale/BI parameters consente di sostituire diverse values nelle query dei set di dati durante l'esecuzione. In questo modo è possibile filtrare i dati in base a criteri quali date e categorie di prodotti prima che i dati vengano aggregati in una query SQL, con conseguente esecuzione di query più efficienti e analisi precise. Parameters può essere usato con i widget di filtro per rendere i dashboard interattivi o con widget di visualizzazione per semplificare il riutilizzo dei set di dati.
Gli autori o gli editor del dashboard aggiungono parameters ai set di dati e li connettono a uno o più widget nell'area di disegno del dashboard. Per parametersset statici nei widget di visualizzazione, i values vengono set dagli autori o dagli editor. Per parameters usato nei widget di filtro, i visualizzatori del dashboard possono interagire con i dati selezionando values nei widget di filtro in fase di esecuzione. Questa interazione esegue nuovamente le query associate e visualizza visualizzazioni in base ai dati filtrati.
Parameters modificare direttamente la query, che può essere potente. I filtri dei campi del set di dati possono offrire anche più interattività nei dashboard, ulteriori funzionalità e prestazioni migliori con grandi set di dati rispetto a parameters. Vedere Usare i filtri.
Aggiungere un parametro di query
Per aggiungere un parametro a un set di dati del dashboard, è necessario disporre almeno delle autorizzazioni CAN EDIT nel dashboard bozza. È possibile aggiungere parameters direttamente alle query del set di dati nella scheda Data .
Aggiungere un parametro di query
Posizionare il cursore where si vuole posizionare il parametro nella query.
Fare clic su Aggiungi parametro per insert un nuovo parametro.
Verrà creato un nuovo parametro con il nome
parameter
predefinito . Per modificare il nome predefinito, sostituirlo nell'editor di query. È anche possibile aggiungere parameters digitando questa sintassi nell'editor di query.
Modificare un parametro di query
Per modificare un parametro:
Fare clic accanto al nome del parametro. Viene visualizzata una finestra di dialogo Dettagli parametro che include le opzioni di configurazione seguenti:
Parola chiave: parola chiave che rappresenta il parametro nella query. Questa operazione può essere modificata solo aggiornando direttamente il testo nella query.
Nome visualizzato: nome nell'editor di filtri. Per impostazione predefinita, il titolo corrisponde alla parola chiave .
Tipo: i tipi supportati includono String, Data, Data e ora, Numeric.
- Il tipo predefinito è stringa.
- Il tipo di dati Numeric consente di specificare tra Decimal e Integer. Il tipo numerico predefinito è Decimal.
Consenti selezioni multiple: Select la casella di controllo per permettere agli utenti di scegliere più opzioni parameters in fase di esecuzione.
Nota
Questa selezione potrebbe richiedere una modifica aggiuntiva alla query. Vedere Consenti selezioni multiple.
Fare clic su un'altra parte dell'interfaccia utente per chiudere la finestra di dialogo.
Set un valore di parametro predefinito
Per eseguire la query, scegliere un valore predefinito per il parametro digitandolo nel campo di testo sotto il nome del parametro. Eseguire la query per visualizzare in anteprima i risultati della query con il valore del parametro applicato. L'esecuzione della query salva anche il valore predefinito. Quando si set questo parametro usando un widget di filtro nell'area di disegno, il valore predefinito viene usato a meno che non venga specificato un nuovo valore predefinito nel widget di filtro. Vedere Usare i filtri.
Consenti selezioni multiple
Le query che consentono più selezioni devono includere una ARRAY_CONTAINS
funzione nella query.
L'esempio seguente illustra una query SQL che consente di select più values per insert nella query in fase di esecuzione. La WHERE
clausola usa la ARRAY_CONTAINS
funzione . Tale funzione accetta la parola chiave parameter e il nome column come argomenti. Quando viene eseguita la query, restituisce tutte le righe contenenti il parametro selezionato values.
SELECT
*
FROM
samples.tpch.lineitem
WHERE array_contains(:parameter, l_quantity)
Per predefinire valuesa set, digitare nel campo di testo sotto il nome visualizzato. Select il valore corrente prima di immetterne uno successivo.
Applica intervallo di date parameters
È possibile usare parameters per definire un intervallo e restituire solo i risultati all'interno di tale intervallo. Quando si sceglie uno dei seguenti tipi di parametro, si creano due parameters indicati come suffissi .min
e .max
.
- Intervallo date
- Intervallo di date e ora
Nell'esempio seguente viene illustrata una query SQL che crea un parametro di intervallo di date denominato date_param
.
SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min and :date_param.max
Per creare un parametro di intervallo di date:
Fare clic su Aggiungi parametro.
Fare clic accanto al nome del parametro. Immettere la parola chiave e il nome visualizzato. Non includere
.min
o.max
suffissi.Scegliere Intervallo di date o Intervallo di date e ora come Tipo.
Insert una clausola
WHERE
che definisce l'intervallo della tua query. Per definire l'intervallo, usare una clausolaBETWEEN
con.min
e.max
values. Ad esempio:WHERE date_col BETWEEN :date_param.min AND :date_param.max
Immettere la data predefinita values ed eseguire la query per testarla. Usare l'icona del calendario per scegliere opzioni predefinite come la settimana scorsa o l'ultimo mese.
parameters basata su query
Le parameters basate su query consentono agli autori di definire un list dinamico o statico di values che i visualizzatori possono scegliere quando impostano parameters durante l'esplorazione dei dati in un dashboard. Vengono definiti combinando un filtro di campo e un filtro di parametri in un singolo widget di filtro.
Per creare un parametro basato su query, l'autore del dashboard esegue la procedura seguente:
- Creare un set di dati il cui risultato set è limitato a un list di possibili parametri values.
- Creare una query del set di dati che usa un parametro .
- Configurare un widget di filtro nell'area di disegno che filtra in un campo e usa un parametro.
- Le configurazioni dei campi
devono essere per utilizzare il campo con il desiderato del parametro idoneo . - La configurazione Parameters deve essere set a select un valore di parametro.
- Le configurazioni dei campi
Nota
Se un set di dati usato nelle parameters basate su query viene usato anche in altre visualizzazioni di un dashboard, la selezione del filtro da parte di un utente modifica tutte le query collegate. Per evitare questo problema, gli autori devono creare un set di dati dedicato per i parameters basati su query che non vengono usati in altre visualizzazioni nel dashboard.
Vedi per un uso di parameters basato su query per un'esercitazione dettagliata che illustra come aggiungere un parametro e una visualizzazione basato su una query.
Creare un parametro dinamico list
Per creare un set di dati dinamico che popola l'elenco a discesa utilizzato dagli utenti per select parametro values, scrivi una query SQL che restituisce un singolo campo e include tutti i values in tale campo. Qualsiasi nuovo valore in tale campo viene aggiunto automaticamente come selezione di parametri. Di seguito è riportato un esempio di query SQL:
SELECT
DISTINCT c_mktsegment
FROM
samples.tpch.customer
Creare un parametro statico list
È possibile creare un set di dati statico che include solo values inseriti manualmente nel set di dati. Di seguito è riportato un esempio:
SELECT
*
FROM
(
VALUES
('MACHINERY'),
('BUILDING'),
('FURNITURE'),
('HOUSEHOLD'),
('AUTOMOBILE')
) AS data(available_choices)
Remove un parametro di query
Per remove un parametro, eliminarlo dalla query.
Widget statico parameters
I widget statici parameters vengono configurati direttamente in un widget di visualizzazione, consentendo agli autori di parametrizzare singolarmente i widget di visualizzazione che condividono lo stesso set di dati. Ciò consente allo stesso set di dati di presentare diversi views sullo schermo.
L'esempio in questa sezione si basa su un set di dati che interroga il samples.nyctaxi.trips
table. La query fornita restituisce la distanza di ogni viaggio e classifica il giorno di ritiro come Weekday
o Weekend
. Il parametro di query filtra i risultati in base al fatto che il ritiro si sia verificato durante un giorno feriale o un fine settimana.
Il testo della query viene fornito nel blocco di codice seguente, ma le istruzioni in questa sezione sono limitate alla configurazione delle visualizzazioni associate configurate con il widget statico parameters. Per istruzioni sulla configurazione di un set di dati con parameters, vedere Aggiungere un parametro a una query.
WITH DayType AS (
SELECT
CASE
WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
ELSE 'Weekday'
END AS day_type,
trip_distance
FROM samples.nyctaxi.trips
)
SELECT day_type, trip_distance
FROM DayType
WHERE day_type = :day_type_param
Per aggiungere un parametro widget statico a una visualizzazione:
Aggiungere un widget di visualizzazione all'area di disegno bozza del dashboard.
Con il nuovo widget selezionato, scegliere il set di dati con parametri dall'elenco a discesa Set di dati nel pannello di configurazione.
Fare clic su Mostra filtri. Per i set di dati che includono parameters, nel pannello di configurazione viene visualizzata una sezione Parameters.
Cliccare sul segno più alla destra dell'intestazione Parameters e scegliere un parametro dal menu a tendina.
Per impostazione predefinita, il valore del parametro rispecchia le
nella query nella scheda dati. È possibile mantenerlo o scegliere un nuovo valore da sostituire nel set di dati. Passare dal campo di testo per visualizzare la visualizzazione con il nuovo parametro applicato. Visualizzare i dashboard.
L'immagine seguente mostra due widget di visualizzazione. Ogni elemento viene configurato come istogramma con un parametro del widget statico. Il grafico a sinistra mostra la distribuzione delle distanze di viaggio per i viaggi a partire dai giorni feriali, mentre il grafico a destra mostra gli stessi dati per i fine settimana. Entrambe le visualizzazioni si basano sullo stesso set di dati.
Confrontare i dati usando una condizione di filtro
È possibile aggiungere una condizione di filtro che consente di confrontare le aggregazioni su una parte dei dati con le aggregazioni applicate all'intero set.
Nell'esempio seguente viene estesa la query precedente per includere una condizione di filtro where il valore del parametro specificato è All
, che non viene visualizzato nei dati. La prima parte della condizione di filtro funziona come nell'esempio precedente, filtrando i risultati where in cui il day_type
è Weekday
o Weekend
. La seconda parte della condizione di filtro verifica se il parametro stesso è set rispetto a un valore specifico, in questo caso All
, che non appare nei dati. Quando si set il valore predefinito per quel parametro nell'editor del set di dati, si ignora effettivamente il filtro quando né Weekday
né Weekend
vengono passati come values.
WITH DayType AS (
SELECT
CASE
WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
ELSE 'Weekday'
END AS day_type,
trip_distance
FROM
samples.nyctaxi.trips
)
SELECT
day_type,
trip_distance
FROM
DayType
WHERE
day_type = :day_type_param
OR :day_type_param = 'All'
È possibile usare questo set di dati per configurare tre widget di visualizzazione, con il day_type_param
set rispettivamente per All
, Weekday
e Weekend
. I visualizzatori del dashboard possono quindi confrontare ogni set di dati filtrato in base al tipo di giorno con l'intero set di dati.
La GIF seguente illustra come creare rapidamente tre grafici dal set di dati creato con questa query.
- Il primo grafico è configurato per visualizzare il set di dati Distanze di Viaggio per Tipo di Giorno con un valore di parametro set per Giorni Feriali.
- Clonare il grafico per mantenere tutte le configurazioni applicate.
- Per visualizzare i dati per i viaggi effettuati nel fine settimana, modificare il parametro statico in Fine settimana.
- Clonare il nuovo grafico per mantenere tutte le configurazioni applicate in precedenza.
- Set il parametro nel nuovo grafico per Tutti i per mostrare il numero totale delle corse in base alla distanza per i viaggi nei fine settimana e nei giorni feriali.
Mostra parameters nel dashboard
L'aggiunta di un filtro all'area di disegno del dashboard consente ai visualizzatori di select e modificare values dei parametri per esplorare e analizzare i dati in modo interattivo. Se non esponi il parametro sul dashboard, gli spettatori vedono solo i risultati della query che utilizzano il valore predefinito del parametro, cioè set, nella query.
Per aggiungere un parametro al dashboard:
- Fare clic su Aggiungi un filtro (campo/parametro).
- Fare clic sull'icona accanto a Parameters nel pannello di configurazione.
- Fare clic sul nome del parametro che si desidera che il visualizzatore usi con questo widget.
Uso di widget di filtro e parameters statici
Parameters vengono fissati e values sostituiti in una query in fase di esecuzione. Se due o più riferimenti allo stesso parametro vengono set con values diversi quando il dashboard viene aggiornato, i widget di visualizzazione visualizzano un errore che indica quale parametro presenta conflitti values. Ciò può verificarsi quando più widget di filtro usano lo stesso parametro o quando un parametro statico è in conflitto con un widget di filtro che consente la selezione del visualizzatore.
È possibile usare un modello come quello dell'esempio seguente per setvalues di fallback per parameters diverse nella stessa query.
CASE WHEN :static_param != 'All' THEN :static_param ELSE :dash_param END
In questo esempio, :static_param
fa riferimento a un parametro statico, che deve essere set a 'All' sia nel widget di visualizzazione che nell'editor del set di dati. Il parametro :dash_param
è un valore dinamico controllato da un widget di filtro nell'area di lavoro del dashboard. Questa istruzione verifica la presenza di un valore fornito come parametro statico. Se nessuno è set, si ripiega su un valore del parametro del dashboard selezionato dall'utente.
Includere parameters nell'URL
Le impostazioni dei parametri vengono archiviate nell'URL, consentendo agli utenti di aggiungere un segnalibro per mantenere lo stato del dashboard, inclusi i filtri pre-set e parameters, o di condividerlo con altri per applicare gli stessi filtri e parameters in modo coerente.
Dashboard parameters contro query Mustache parameters
Il dashboard parameters utilizza la stessa sintassi degli indicatori di parametro denominati. Vedere Marcatori di parametri denominati. I dashboard non supportano lo stile Mustache parameters.
Esempi di sintassi
Gli usi comuni per parameters includono l'inserimento di date, numeri, testo, oggetti di database e values da stringhe JSON. Per esempi che illustrano come usare parameters in questi casi, vedere gli esempi di sintassi dei parametri denominati in .
Importante
L'accesso dei visualizzatori ai dati tramite selezioni di parametri come table o catalog potrebbe causare un'esposizione accidentale di informazioni riservate. Se si pubblica un dashboard con queste opzioni, Azure Databricks consiglia di non incorporare credentials nel dashboard pubblicato.