Usare marcatori di parametro denominati

I marcatori di parametro denominati consentono di inserire valori di variabile nelle query SQL in fase di esecuzione. Invece di inserire valori hardcoded specifici, è possibile definire segnaposto tipizzati che gli utenti riempiono quando la query viene eseguita. Ciò migliora il riutilizzo delle query, impedisce l'inserimento di SQL e semplifica la compilazione di query flessibili e interattive.

I marcatori di parametro denominati funzionano nelle superfici di Databricks seguenti:

• Editor SQL (nuovo e storico)
• Notebook
• Editor del set di dati del dashboard di IA/BI
• Spazi Genie

Aggiungere un marcatore di parametro denominato

Inserire un parametro digitando i due punti seguiti dal nome del parametro, ad esempio :parameter_name. Quando si aggiunge un marcatore di parametro denominato a una query, viene visualizzato un widget in cui è possibile impostare il tipo di parametro e il valore. Vedere Usare i widget dei parametri.

In questo esempio viene convertita una query codificata staticamente per utilizzare un parametro denominato.

Avvio della query:

SELECT
  trip_distance,
  fare_amount
FROM
  samples.nyctaxi.trips
WHERE
  fare_amount < 5

1. Eliminare 5 dalla WHERE clausola .
2. Digitare :fare_parameter al suo posto. L'ultima riga deve leggere fare_amount < :fare_parameter.
3. Fare clic sull'icona a forma di ingranaggio accanto al widget del parametro.
4. Impostare il tipo su Decimal.
5. Immettere un valore nel widget del parametro e fare clic su Applica modifiche.
6. Fare clic su Salva.

Tipi di parametro

Impostare il tipo di parametro nel pannello delle impostazioni dei parametri. Il tipo determina il modo in cui Databricks interpreta e gestisce il valore in fase di esecuzione.

Esempi di sintassi dei parametri denominati

Negli esempi seguenti vengono illustrati i modelli comuni per i marcatori di parametro denominati.

Inserire una data

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

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

Usare la IDENTIFIER funzione per passare un nome di colonna come parametro. 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

Usare la IDENTIFIER funzione con più parametri per specificare un catalogo, uno schema e una tabella in fase di esecuzione.

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

Vedere IDENTIFIER clausola.

Concatenare più parametri

Usare format_string per combinare i parametri in una singola stringa formattata. Vedi funzione format_string.

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

Lavorare con le stringhe JSON

Usare la from_json funzione per estrarre un valore da una stringa JSON usando un parametro come chiave. Sostituendo a come valore per :param restituisce 1.

SELECT from_json('{"a": 1}', 'map<string, int>') [:param]

Creare un intervallo

Utilizzare CAST per convertire un valore di parametro in un INTERVAL tipo per i calcoli basati sul tempo. Vedere Tipo di intervallo.

SELECT CAST(:param AS INTERVAL MINUTE)

Aggiungere un intervallo di date usando .min e .max

I parametri data e timestamp supportano un widget di intervallo. Usare .min e .max per accedere all'inizio e alla fine dell'intervallo.

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN :date_range.min AND :date_range.max

Impostare il tipo di parametro su Date o Timestamp e il tipo di widget su Range.

Aggiungere un intervallo di date usando due parametri

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN CAST(:date_range_min AS TIMESTAMP) AND CAST(:date_range_max AS TIMESTAMP)

Parametrizza la granularità del rollup

Usare DATE_TRUNC per aggregare i risultati a un livello di granularità selezionato dall'utente. Passare DAY, MONTHo YEAR come valore del parametro.

SELECT
  DATE_TRUNC(:date_granularity, tpep_pickup_datetime) AS date_rollup,
  COUNT(*) AS total_trips
FROM samples.nyctaxi.trips
GROUP BY date_rollup

Passare più valori sotto forma di stringa

Usare ARRAY_CONTAINS, SPLITe TRANSFORM per filtrare in base a un elenco delimitato da virgole di valori passati come singolo parametro stringa. SPLIT analizza la stringa delimitata da virgole in una matrice. TRANSFORM taglia gli spazi vuoti da ogni elemento. ARRAY_CONTAINS controlla se il valore della tabella viene visualizzato nella matrice risultante.

SELECT * FROM samples.nyctaxi.trips WHERE
  array_contains(
    TRANSFORM(SPLIT(:list_parameter, ','), s -> TRIM(s)),
    CAST(dropoff_zip AS STRING)
  )

Informazioni di riferimento sulla migrazione della sintassi

Utilizzare questa tabella per la conversione di query dalla sintassi mustache ai marcatori di parametro denominati. Per altre informazioni sulla sintassi legacy, vedere Sintassi dei parametri Mustache .