Použití pojmenovaných značek parametrů

Pojmenované značky parametrů umožňují vložit hodnoty proměnných do dotazů SQL za běhu. Místo pevně zakódovaných hodnot definujete zadané zástupné symboly, které uživatelé vyplní při spuštění dotazu. To zlepšuje opakované použití dotazů, zabraňuje injektáži SQL a usnadňuje vytváření flexibilních interaktivních dotazů.

Pojmenované značky parametrů fungují v následujících povrchech Databricks:

• Editor SQL (nový a starší verze)
• Notebooks
• Editor datových sad řídicích panelů AI/BI
• Genie Prostory

Přidejte značku pojmenovaného parametru

Vložte parametr zadáním dvojtečky následované názvem parametru, například :parameter_name. Když do dotazu přidáte pojmenovanou značku parametru, zobrazí se widget, kde můžete nastavit typ a hodnotu parametru. Viz Práce s widgety parametrů.

Tento příklad převede pevně zakódovaný dotaz na použití pojmenovaného parametru.

Počáteční dotaz:

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

1. Odstraňte 5 z WHERE klauzule.
2. Zadejte :fare_parameter na jeho místě. Poslední řádek by měl číst fare_amount < :fare_parameter.
3. Klikněte na ikonu ozubeného kola u widgetu parametrů.
4. Nastavte typ na desetinné číslo.
5. Do widgetu parametrů zadejte hodnotu a klikněte na Použít změny.
6. Klikněte na Uložit.

Typy parametrů

Nastavte typ parametru na panelu nastavení parametrů. Typ určuje, jak Databricks interpretuje a zpracovává hodnotu za běhu.

Typ	Description
Řetězec	Volný text. Zpětné lomítko, jednoduché a dvojité uvozovky se zpracovávají automaticky unikáním. Databricks přidá kolem hodnoty uvozovky.
Celé číslo	Celá číselná hodnota
Decimal	Číselná hodnota, která podporuje desetinné hodnoty
Rande	Hodnota datumu. Používá kalendářový výběr a nastavuje se na aktuální datum.
Časová značka	Hodnota data a času Používá výběr kalendáře a výchozí nastavení na aktuální datum a čas.

Příklady syntaxe pojmenovaných parametrů

Následující příklady ukazují běžné vzory pro pojmenované značky parametrů.

Vložit datum

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

Vložení čísla

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

Vložení názvu pole

IDENTIFIER Funkce slouží k předání názvu sloupce jako parametru. Hodnota parametru by měla být název sloupce z tabulky použité v dotazu.

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

Vložení databázových objektů

IDENTIFIER Funkce s více parametry slouží k určení katalogu, schématu a tabulky za běhu.

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

Vizklauzule .

Zřetězení více parametrů

Slouží format_string ke kombinování parametrů do jednoho formátovaného řetězce. Vizte funkce format_string.

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

Práce s řetězci JSON

from_json Pomocí funkce extrahujte hodnotu z řetězce JSON pomocí parametru jako klíče. Nahrazení a jako hodnotu pro :param vrátí 1.

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

Vytvoření intervalu

Slouží CAST k převodu hodnoty parametru na INTERVAL typ pro výpočty založené na čase. Viz Typ intervalu.

SELECT CAST(:param AS INTERVAL MINUTE)

Přidejte rozsah datumu pomocí .min a .max

Parametry data a časového razítka podporují prvek rozhraní pro výběr rozsahu. Použijte .min a .max pro přístup ke začátku a konci rozsahu.

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

Nastavte typ parametru na Date nebo Timestamp a typ widgetu na Range.

Přidání rozsahu dat pomocí dvou parametrů

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

Parametrizovat granularitu seskupování

Slouží DATE_TRUNC k agregaci výsledků na úrovni členitosti vybrané uživatelem. Předejte DAY, MONTH nebo YEAR jako hodnotu parametru.

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

Předání více hodnot ve formě řetězce

Použijte ARRAY_CONTAINS, SPLITa TRANSFORM k filtrování na čárkami oddělený seznam hodnot předaných jako jeden řetězcový parametr. SPLIT parsuje řetězec oddělený čárkami do pole. TRANSFORM ořízne prázdné znaky z každého prvku. ARRAY_CONTAINS zkontroluje, zda se hodnota tabulky zobrazí ve výsledném poli.

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

Poznámka:

Tento příklad funguje pro řetězcové hodnoty. Chcete-li použít jiné datové typy, obalte operaci TRANSFORM pomocí CAST pro konverzi prvků na požadovaný typ.

Referenční informace k migraci syntaxe

Tuto tabulku použijte při převodu dotazů ze syntaxe mustache na pojmenované značky parametrů. Pro více informací o původní syntaxi viz Syntaxe parametru Mustache.

Případ použití	Syntaxe mustache	Syntaxe pojmenovaných parametrů
Filtrovat podle data	WHERE date_field < '{{date_param}}'	WHERE date_field < :date_param
Filtrovat podle čísla	WHERE price < {{max_price}}	WHERE price < :max_price
Porovnávání řetězců	WHERE region = '{{region_param}}'	WHERE region = :region_param
Určit tabulku	SELECT * FROM {{table_name}}	SELECT * FROM IDENTIFIER(:table) — používat úplný tříúrovňový obor názvů
Určení katalogu, schématu a tabulky	SELECT * FROM {{catalog}}.{{schema}}.{{table}}	SELECT * FROM IDENTIFIER(:catalog \|\| '.' \|\| :schema \|\| '.' \|\| :table)
Formátování řetězce z více parametrů	"({{area_code}}) {{phone_number}}"	format_string("(%d) %d", :area_code, :phone_number)
Vytvoření intervalu	SELECT INTERVAL {{p}} MINUTE	SELECT CAST(format_string("INTERVAL '%s' MINUTE", :param) AS INTERVAL MINUTE)