Che cosa sono i parametri del dashboard?

I parametri del dashboard sono un modo per rendere interattivi i dashboard, consentendo ai visualizzatori di usare selettori a valore singolo e selezione data per immettere valori specifici nelle query del set di dati in fase di esecuzione. Ad esempio, i parametri possono filtrare i dati in base a criteri come date e categorie di prodotti prima che venga aggregato in una query SQL, consentendo query più efficienti e analisi precise.

I parametri vengono aggiunti ai set di dati e connessi a uno o più widget nell'area di disegno di un dashboard da un autore o un editor del dashboard. I visualizzatori del dashboard interagiscono con i dati del dashboard selezionando i valori nei widget di filtro in fase di esecuzione. Viene rieseguita le query associate e vengono presentate visualizzazioni basate sui dati filtrati.

I parametri modificano direttamente la query, che può essere potente. I filtri dei 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 Filtri.

Aggiungere un parametro a una query

Per aggiungere un parametro a un set di dati del dashboard del dashboard, è necessario disporre almeno di autorizzazioni di modifica . È possibile aggiungere parametri direttamente alle query del set di dati nella scheda Dati .

Per aggiungere un parametro a una query:

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

2. Fare clic su Aggiungi parametro per inserire 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, Date, Date e Time, Numeric.
     • Il tipo predefinito è String.
     • 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.

Impostare un valore di parametro predefinito

È possibile impostare 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.

Parametri basati su 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 un elenco di 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 elenco di parametri statici

È possibile creare un set di dati statico che includa solo i valori hardcoded nel set di dati. Una query di esempio è la seguente:

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.

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.

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.

Esempi di sintassi dei parametri

Negli esempi seguenti vengono illustrati alcuni casi d'uso comuni per i parametri.

Inserire una data

L'esempio seguente include un parametro Date che limita i risultati della query ai record dopo una data specifica.

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  sum(o_totalprice) AS `Total Price`
FROM
  samples.tpch.orders
WHERE
  o_orderdate > :date_param
GROUP BY
  1,
  2

Inserire un numero

L'esempio seguente include un parametro Numeric che limita i risultati ai record in cui il o_total_price campo è maggiore del valore del parametro specificato.

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  o_totalprice AS Price
FROM
  samples.tpch.orders
WHERE
  o_totalprice > :num_param

Inserire un nome di campo

Nell'esempio seguente, field_param viene usato con la IDENTIFIER funzione per fornire un valore soglia per la query in fase di esecuzione. Il valore del parametro deve essere un nome di colonna della tabella usata nella query.

SELECT
  *
FROM
  samples.tpch.orders
WHERE
  IDENTIFIER(:field_param) < 10000

Inserire oggetti di database

Nell'esempio seguente vengono creati tre parametri: catalog, schemae table. I visualizzatori del dashboard possono usare i widget di filtro nell'area di disegno per selezionare i valori dei parametri.

SELECT
  *
FROM
  IDENTIFIER(:catalog || '.' || :schema || '.' || :table)

Vedere clausola IDENTIFIER.

Importante

L'abilitazione dei visualizzatori del dashboard di accedere ai dati tramite selezioni di parametri, ad esempio 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.

Concatenare più parametri

È possibile includere parametri in altre funzioni SQL. Questo esempio consente al visualizzatore di selezionare un titolo dipendente e un ID numero. La query usa la format_string funzione per concatenare le due stringhe e filtrare le righe corrispondenti. Vedere format_string funzione.

SELECT
  o_orderkey,
  o_clerk
FROM
  samples.tpch.orders
WHERE
  o_clerk LIKE format_string('%s%s', :title, :emp_number)

Parametri del dashboard e parametri di query SQL di Databricks

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 SQL di Databricks.