Usare i parametri del dashboard

Questo articolo illustra come usare i parametri nei dashboard di intelligenza artificiale/BI. Per informazioni sui filtri dei campi, vedere Filtrare in base ai campi.

I parametri del dashboard di intelligenza artificiale/BI consentono di sostituire valori diversi nelle query del set di dati in fase di 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. I parametri possono essere usati 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 parametri ai set di dati e li connettono a uno o più widget nell'area di disegno del dashboard. Per i parametri statici impostati nei widget di visualizzazione, i valori vengono impostati dagli autori o dagli editor. Per i parametri usati nei widget di filtro, i visualizzatori del dashboard possono interagire con i dati selezionando i valori nei widget di filtro in fase di esecuzione. Questa interazione esegue nuovamente le query associate e visualizza visualizzazioni in base ai dati filtrati.

I parametri modificano direttamente la query, che può essere potente. I filtri dei campi del set di dati possono offrire anche interattività del dashboard, più funzionalità e prestazioni migliori con set di dati di grandi dimensioni rispetto ai parametri. 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 parametri direttamente alle query del set di dati nella scheda Dati .

Aggiungere un parametro di query

1. Posizionare il cursore in cui posizionare il parametro nella query.

2. Fare clic su Aggiungi parametro per aggiungere un nuovo parametro.

   Verrà creato un nuovo parametro con il nome parameterpredefinito . Per modificare il nome predefinito, sostituirlo nell'editor di query. È anche possibile aggiungere parametri digitando questa sintassi nell'editor di query.

Modificare un parametro di query

Per modificare un parametro:

1. 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.
2. Fare clic su un'altra parte dell'interfaccia utente per chiudere la finestra di dialogo.

Valore del 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 imposta questo parametro usando un widget di filtro nell'area di disegno, viene usato il valore predefinito, a meno che non venga specificato un nuovo valore predefinito nel widget di filtro. Vedere Usare i filtri.

Consente di aggiungere parametri di query.

I parametri basati su query consentono agli autori di definire un elenco di valori dinamico o statico tra cui i visualizzatori possono scegliere quando impostano i parametri 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:

1. Creare un set di dati il cui set di risultati è limitato a un elenco di possibili valori di parametro.
2. Creare una query del set di dati che usa un parametro .
3. Configurare un widget di filtro nell'area di disegno che filtra in un campo e usa un parametro.
   • Le configurazioni dei campi devono essere impostate per usare il campo con l'elenco desiderato di valori dei parametri idonei.
   • La configurazione parametri deve essere impostata per selezionare un valore di parametro.

Nota

Se un set di dati usato nei parametri basati su query viene usato anche in altre visualizzazioni in un dashboard, la selezione del filtro di un visualizzatore modifica tutte le query connesse. Per evitare questo problema, gli autori devono creare un set di dati dedicato per i parametri basati su query che non vengono usati in altre visualizzazioni nel dashboard.

Vedere Usare parametri basati su query per un'esercitazione dettagliata che illustra come aggiungere un parametro e una visualizzazione basati su query.

Creare e usare parametri dinamici

Per creare un set di dati dinamico che popola l'elenco a discesa usato dai visualizzatori per selezionare i valori dei parametri, scrivere una query SQL che restituisce un singolo campo e include tutti i valori in tale campo. Qualsiasi nuovo valore in tale campo viene aggiunto automaticamente come selezione di parametri quando il set di dati viene aggiornato. Di seguito è riportato un esempio di query SQL:

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

Creare un parametro a discesa statico

È possibile creare un set di dati statico che includa solo i valori hardcoded nel set di dati. Di seguito è riportato un esempio:

SELECT
  *
FROM
  (
    VALUES
      ('MACHINERY'),
      ('BUILDING'),
      ('FURNITURE'),
      ('HOUSEHOLD'),
      ('AUTOMOBILE')
  ) AS data(available_choices)

Tipi di filtri

I filtri Selezione valore singolo e Selezione data supportano i parametri di impostazione. Quando si impostano parametri basati su query con un filtro selezione data, le date visualizzate nei risultati della query sottostante vengono visualizzate in nero. Le date che non vengono visualizzate nei risultati della query sono grigie. Gli utenti possono scegliere date grigie anche se non sono incluse nella query sottostante.

Rimuovere un parametro di query

Per rimuovere un parametro, eliminarlo dalla query.

Parametri del widget statico

I parametri dei widget statici 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 visualizzazioni diverse nell'area di disegno.

L'esempio in questa sezione si basa su un set di dati su cui viene eseguita una query sulla samples.nyctaxi.trips tabella. 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 contenute in questa sezione sono limitate alla configurazione delle visualizzazioni associate configurate con i parametri dei widget statici. Per istruzioni su come configurare un set di dati con parametri, 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:

1. Aggiungere un widget di visualizzazione all'area di disegno bozza del dashboard.

2. Con il nuovo widget selezionato, scegliere il set di dati con parametri dall'elenco a discesa Set di dati nel pannello di configurazione.

3. Fare clic su Mostra filtri. Per i set di dati che includono parametri, viene visualizzata una sezione Parametri nel pannello di configurazione.

   

4. Fare clic sul segno più a destra dell'intestazione Parametri e scegliere un parametro dall'elenco a discesa.

5. Per impostazione predefinita, il valore del parametro rispecchia ciò che viene impostato 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.

6. Visualizzare i dashboard.

   L'immagine seguente mostra due widget di visualizzazione, ognuno è 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 in parte dei dati con le aggregazioni applicate all'intero set di dati.

Nell'esempio seguente viene estesa la query precedente per includere una condizione di filtro in cui 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 in cui day_type è Weekday o Weekend. La seconda parte della condizione di filtro controlla se il parametro stesso è impostato su un determinato valore, in questo caso All, che non viene visualizzato nei dati. Quando si imposta il valore predefinito per tale parametro nell'editor del set di dati, si ignora effettivamente il filtro quando non vengono passati né Weekday Weekend come valori.

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 l'opzione day_type_param impostata rispettivamente su AllWeekday e Weekend . I visualizzatori del dashboard possono quindi confrontare ognuno dei set di dati filtrati 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.

1. Il primo grafico è configurato per visualizzare il set di dati Trip Distances by Day Type con un valore di parametro impostato su Weekday.
2. Clonare il grafico per mantenere tutte le configurazioni applicate.
3. Per visualizzare i dati per i viaggi effettuati nel fine settimana, modificare il parametro statico in Fine settimana.
4. Clonare il nuovo grafico per mantenere tutte le configurazioni applicate in precedenza.
5. Impostare il parametro nel nuovo grafico su Tutti per visualizzare i conteggi totali delle corse per distanza per i viaggi nei fine settimana e nei giorni feriali.

Visualizzare i parametri nel dashboard

L'aggiunta di un filtro al canvas del dashboard consente ai visualizzatori di selezionare e modificare i valori dei parametri, in modo che possano esplorare e analizzare in modo interattivo i dati. Se non si espone il parametro nel dashboard, i visualizzatori visualizzano solo i risultati della query che usano il valore del parametro predefinito impostato nella query.

Per aggiungere un parametro al dashboard:

1. Fare clic su Aggiungi un filtro (campo/parametro).
2. Fare clic accanto a Parametri nel pannello di configurazione.
3. Fare clic sul nome del parametro che si desidera che il visualizzatore usi con questo widget.

Uso dei widget di filtro e dei parametri statici

I parametri sono valori fissi sostituiti in una query in fase di esecuzione. Se due o più riferimenti allo stesso parametro vengono impostati con valori diversi quando il dashboard viene aggiornato, i widget di visualizzazione visualizzano un errore che indica il parametro con valori in conflitto. 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.

Per impostare i valori di fallback per parametri diversi nella stessa query, è possibile usare un modello come quello nell'esempio seguente.

CASE WHEN :static_param != 'All' THEN :static_param ELSE :dash_param END

In questo esempio :static_param si riferisce a un parametro statico, che deve essere impostato su "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 non è impostato, utilizza un valore del parametro del dashboard selezionato dal visualizzatore.

Includere i parametri 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 e i parametri preimpostati o di condividerlo con altri utenti per un'applicazione coerente degli stessi filtri e parametri.

Parametri del dashboard e parametri di query mustache

I parametri del dashboard usano la stessa sintassi degli indicatori di parametro denominati. Vedere Marcatori di parametri denominati. I dashboard non supportano i parametri di stile Mustache.

Esempi di sintassi

Gli usi comuni per i parametri includono l'inserimento di date, numeri, testo, oggetti di database e valori da stringhe JSON. Per esempi che illustrano come usare i parametri in questi casi, vedere Esempi di sintassi dei parametri denominati

Importante

L'accesso dei visualizzatori ai dati tramite selezioni di parametri come i nomi di tabella o catalogo potrebbe causare un'esposizione accidentale di informazioni riservate. Se si pubblica un dashboard con queste opzioni, Azure Databricks consiglia di non incorporare le credenziali nel dashboard pubblicato.