Używanie nazwanych znaczników parametrów

Nazwane znaczniki parametrów umożliwiają wstawianie wartości zmiennych do zapytań SQL w czasie wykonywania. Zamiast kodować określone wartości, należy zdefiniować typowane symbole zastępcze, które użytkownicy wypełniają podczas uruchamiania zapytania. Poprawia to ponowne użycie zapytań, zapobiega wstrzyknięciu kodu SQL i ułatwia tworzenie elastycznych, interakcyjnych zapytań.

Znaczniki nazwanych parametrów działają na następujących powierzchniach usługi Databricks:

• Edytor SQL (nowy i starszy)
• Notebooks
• Edytor danych pulpitu nawigacyjnego AI/BI
• Miejsca genie

Dodawanie nazwanego znacznika parametru

Wstaw parametr, wpisując dwukropek, po którym następuje nazwa parametru, na przykład :parameter_name. Po dodaniu nazwanego znacznika parametru do zapytania zostanie wyświetlony widżet, w którym można ustawić typ parametru i wartość. Zobacz Praca z widżetami parametrów.

W tym przykładzie przekonwertowano zakodowane zapytanie, aby użyć nazwanego parametru.

Uruchamianie zapytania:

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

1. Usuń 5 z klauzuli WHERE .
2. Wpisz :fare_parameter w jego miejsce. Ostatni wiersz powinien brzmieć fare_amount < :fare_parameter.
3. Kliknij ikonę koła zębatego w pobliżu widżetu parametrów.
4. Ustaw typ na Dziesiętny.
5. Wprowadź wartość w widżecie parametru i kliknij przycisk Zastosuj zmiany.
6. Kliknij przycisk Zapisz.

Typy parametrów

Ustaw typ parametru w panelu ustawień parametrów. Typ określa, jak usługa Databricks interpretuje i obsługuje wartość w czasie wykonywania.

Typ	Opis
String	Tekst dowolny. Ukośnik wsteczny, pojedynczy i podwójny cudzysłów są automatycznie znakowane ukośnikiem. Usługa Databricks dodaje znaki cudzysłowu wokół wartości.
Liczba całkowita	Wartość liczbowa całkowita.
Decimal	Wartość liczbowa, która obsługuje wartości ułamkowe.
Data	Wartość daty. Używa selektora kalendarza i jest domyślnie ustawiony na bieżącą datę.
Sygnatura czasowa	Wartość daty i godziny. Używa selektora kalendarza i ustawia domyślnie bieżącą datę i godzinę.

Przykłady składni nazwanych parametrów

W poniższych przykładach przedstawiono typowe wzorce dla nazwanych znaczników parametrów.

Wstaw datę

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

Wstaw liczbę

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

Wstaw nazwę pola

IDENTIFIER Użyj funkcji , aby przekazać nazwę kolumny jako parametr. Wartość parametru powinna być nazwą kolumny z tabeli używanej w zapytaniu.

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

Wstawianie obiektów bazy danych

IDENTIFIER Użyj funkcji z wieloma parametrami, aby określić wykaz, schemat i tabelę w czasie wykonywania.

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

Zobacz klauzulę IDENTIFIER.

Łączenie wielu parametrów

Służy format_string do łączenia parametrów w jeden sformatowany ciąg. Zobacz funkcję format_string.

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

Praca z ciągami JSON

from_json Użyj funkcji , aby wyodrębnić wartość z ciągu JSON przy użyciu parametru jako klucza. Podstawienie a jako wartość :param zwraca 1.

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

Tworzenie interwału

Użyj CAST do przekształcenia wartości parametru na typ INTERVAL w obliczeniach opartych na czasie. Zobacz Typ interwału.

SELECT CAST(:param AS INTERVAL MINUTE)

Dodaj zakres dat przy użyciu .min i .max

Parametry daty i znacznika czasu obsługują widżet zakresowy. Użyj parametru .min i .max , aby uzyskać dostęp do początku i końca zakresu.

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

Ustaw typ parametru na Date lub Timestamp i typ widżetu na Zakres.

Dodawanie zakresu dat przy użyciu dwóch parametrów

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

Parametryzować szczegółowość zagregowania

Służy DATE_TRUNC do agregowania wyników na wybranym przez użytkownika poziomie szczegółowości. Przekaż DAY, MONTH lub YEAR jako wartość parametru.

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

Przekazywanie wielu wartości jako ciągu

ARRAY_CONTAINSUżyj SPLIT, iTRANSFORM, aby filtrować na rozdzielanej przecinkami liście wartości przekazanych jako pojedynczy parametr ciągu. SPLIT przekształca ciąg rozdzielony przecinkami na tablicę. TRANSFORM przycina białe znaki z każdego elementu. ARRAY_CONTAINS Sprawdza, czy wartość tabeli jest wyświetlana w wynikowej tablicy.

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

Uwaga

Ten przykład działa w przypadku wartości ciągów. Aby użyć innych typów danych, opakuj operację TRANSFORM za pomocą CAST, aby przekonwertować elementy na żądany typ.

Referencja migracji składni

Użyj tej tabeli podczas konwertowania zapytań ze składni wąsu na nazwane znaczniki parametrów. Aby uzyskać więcej informacji na temat starszej składni, zobacz Składnia parametrów mustache .

Przypadek użycia	Składnia Mustache	Nazwana składnia parametrów
Filtruj według daty	WHERE date_field < '{{date_param}}'	WHERE date_field < :date_param
Filtruj według liczby	WHERE price < {{max_price}}	WHERE price < :max_price
Porównaj ciągi	WHERE region = '{{region_param}}'	WHERE region = :region_param
Określanie tabeli	SELECT * FROM {{table_name}}	SELECT * FROM IDENTIFIER(:table) — użyj pełnej trójwymiarowej przestrzeni nazw
Określanie wykazu, schematu i tabeli	SELECT * FROM {{catalog}}.{{schema}}.{{table}}	SELECT * FROM IDENTIFIER(:catalog \|\| '.' \|\| :schema \|\| '.' \|\| :table)
Formatowanie ciągu z wielu parametrów	"({{area_code}}) {{phone_number}}"	format_string("(%d) %d", :area_code, :phone_number)
Tworzenie interwału	SELECT INTERVAL {{p}} MINUTE	SELECT CAST(format_string("INTERVAL '%s' MINUTE", :param) AS INTERVAL MINUTE)