Parametry dotazů

Článek
03/01/2024

Parametr dotazu umožňuje nahradit hodnoty do dotazu za běhu. Jakýkoli řetězec mezi dvojitými složenými závorkami {{ }} se považuje za parametr dotazu. Widget se zobrazí nad podoknem výsledků, kde nastavíte hodnotu parametru. Parametry dotazu jsou flexibilnější než filtry dotazů a měly by se používat jenom v případech, kdy filtry dotazů nestačí.

Přidání parametru dotazu

Zadejte Cmd + I. Parametr se vloží do textového stříšku a zobrazí se dialogové okno Přidat parametr .
- Klíčové slovo: Klíčové slovo, které představuje parametr v dotazu.
- Název: Název, který se zobrazí nad widgetem. Ve výchozím nastavení je název stejný jako klíčové slovo.
- Typ: Podporované typy jsou text, číslo, datum, datum a čas, datum a čas (s sekundami), rozevírací seznam a rozevírací seznam založený na dotazech. Výchozí hodnota je Text.
Zadejte klíčové slovo, volitelně přepište název a vyberte typ parametru.
Klikněte na Přidat parametr.
Ve widgetu parametrů nastavte hodnotu parametru.
Klikněte na Použít změny.
Klikněte na Uložit.

Případně zadejte dvojité složené závorky {{ }} a kliknutím na ikonu ozubeného kola u widgetu parametrů upravte nastavení.

Pokud chcete dotaz znovu spustit s jinou hodnotou parametru, zadejte hodnotu ve widgetu a klikněte na Použít změny.

Úprava parametru dotazu

Pokud chcete upravit parametr, klikněte na ikonu ozubeného kola vedle widgetu parametrů. Pokud chcete uživatelům, kteří dotaz nevlastní, zabránit změně parametru, klikněte na Zobrazit pouze výsledky. Zobrazí se dialogové okno parametru <Keyword> .

Odebrání parametru dotazu

Pokud chcete parametr dotazu odebrat, odstraňte ho z dotazu. Widget parametrů zmizí a dotaz můžete přepsat pomocí statických hodnot.

Změna pořadí parametrů

Pokud chcete změnit pořadí, ve kterém se zobrazují parametry, můžete kliknout a přetáhnout jednotlivé parametry na požadované místo.

Text

Přebírá řetězec jako vstup. Zpětné lomítko, jednoduché a dvojité uvozovky jsou uvozovky uvozovky a Azure Databricks přidá do tohoto parametru uvozovky. Například řetězec, jako mr's Li"s je transformován na 'mr\'s Li\"s' příklad použití, může být

SELECT * FROM users WHERE name={{ text_param }}

Počet

Přebírá jako vstup číslo. Příkladem použití může být

SELECT * FROM users WHERE age={{ number_param }}

Pokud chcete omezit rozsah možných hodnot parametrů při spuštění dotazu, použijte typ parametru Rozevírací seznam . Příkladem by bylo SELECT * FROM users WHERE name='{{ dropdown_param }}'. Když vyberete z panelu nastavení parametrů, zobrazí se textové pole, do kterého zadáte povolené hodnoty, přičemž každá hodnota je oddělená novým řádkem. Rozevírací seznamy jsou textové parametry. Pokud chcete v rozevíracím seznamu použít kalendářní data nebo data a časy, zadejte je ve formátu, který zdroj dat vyžaduje. Řetězce nejsou uchvácené. Můžete si vybrat mezi rozevíracím seznamem s jednou nebo více hodnotami.

Jedna hodnota: Jsou vyžadovány jednoduché uvozovky kolem parametru.
Více hodnot: Přepněte možnost Povolit více hodnot . V rozevíracím seznamu uvozovek zvolte, jestli chcete parametry ponechat zadané (bez uvozovek) nebo zabalit parametry jednoduchými nebo dvojitými uvozovkami. Pokud zvolíte uvozovky, nemusíte kolem parametru přidávat uvozovky.

Změňte klauzuli WHERE tak, aby používala IN klíčové slovo v dotazu.

SELECT ...
FROM   ...
WHERE field IN ( {{ Multi Select Parameter }} )

Widget s vícenásobným výběrem parametru umožňuje předat do databáze více hodnot. Pokud u parametru uvozovek vyberete možnost Dvojité uvozovky, bude váš dotaz odpovídat následujícímu formátu:WHERE IN ("value1", "value2", "value3")

Vezme výsledek dotazu jako vstup. Má stejné chování jako parametr Rozevírací seznam . Pokud ho chcete použít jako vstup v jiném dotazu, musíte uložit dotaz rozevíracího seznamu SQL Databricks.

V části Typ na panelu nastavení klikněte na rozevírací seznam Založený na dotazu.
Klikněte na pole Dotaz a vyberte dotaz. Pokud cílový dotaz vrátí velký počet záznamů, výkon se sníží.

Pokud váš cílový dotaz vrátí více než jeden sloupec, databricks SQL použije první sloupec. Pokud cílový dotaz vrátí name sloupce a value sloupce, sql Databricks naplní widget pro výběr parametrů sloupcem name , ale spustí dotaz přidruženým value.

Předpokládejme například, že následující dotaz vrátí data v tabulce.

SELECT user_uuid AS 'value', username AS 'name'
FROM users

hodnota	name
1001	John Smith
1 002	Jane Doe
1003	Bobby Tables

Když Azure Databricks spustí dotaz, hodnota předaná do databáze by byla 1001, 1002 nebo 1003.

Datum a čas

Azure Databricks nabízí několik možností parametrizace hodnot data a časového razítka, včetně možností pro zjednodušení parametrizace časových rozsahů. Vyberte ze tří možností různé přesnosti:

Možnost	Počet deset. míst	Typ
Date	den	`DATE`
Datum a čas	minuta	`TIMESTAMP`
Datum a čas (s sekundami)	Druhé	`TIMESTAMP`

Při výběru možnosti parametru Rozsah vytvoříte dva parametry určené příponou .start a .end příponami. Všechny možnosti předávají vašemu dotazu jako řetězcové literály; Azure Databricks vyžaduje, abyste hodnoty data a času zabalily do jednoduchých uvozovek ('). Příklad:

-- Date parameter
SELECT *
FROM usage_logs
WHERE date = '{{ date_param }}'

-- Date and Time Range parameter
SELECT *
FROM usage_logs
WHERE modified_time > '{{ date_range.start }}' and modified_time < '{{ date_range.end }}'

Parametry data používají rozhraní pro výběr kalendáře a výchozí nastavení aktuálního data a času.

Poznámka:

Parametr Rozsah dat vrátí pouze správné výsledky pro sloupce typu DATE . U TIMESTAMP sloupců použijte jednu z možností data a časového rozsahu.

Dynamické hodnoty data a rozsahu kalendářních dat

Když do dotazu přidáte parametr data nebo rozsahu kalendářních dat, widget výběru zobrazí modrou ikonu blesku. Kliknutím na něj zobrazíte dynamické hodnoty, jako je today, yesterday, last weekthis week, , last monthnebo last year. Tyto hodnoty se dynamicky aktualizují.

Důležité

Dynamická data a rozsahy kalendářních dat nejsou kompatibilní s naplánovanými dotazy.

Použití parametrů dotazu na řídicích panelech

Volitelně můžou dotazy používat parametry nebo statické hodnoty. Když se vizualizace založená na parametrizovaném dotazu přidá na řídicí panel, můžete vizualizaci nakonfigurovat tak, aby používala jednu z těchto hodnot:

Parametr widgetu

Parametry widgetu jsou specifické pro jednu vizualizaci na řídicím panelu, zobrazí se na panelu vizualizace a zadané hodnoty parametrů se vztahují pouze na dotaz podkladové vizualizace.
Parametr řídicího panelu

Parametry řídicího panelu se můžou vztahovat na více vizualizací. Když na řídicí panel přidáte vizualizaci založenou na parametrizovaném dotazu, parametr se ve výchozím nastavení přidá jako parametr řídicího panelu. Parametry řídicího panelu se konfigurují pro jednu nebo více vizualizací na řídicím panelu a zobrazí se v horní části řídicího panelu. Hodnoty parametrů zadané pro parametr řídicího panelu se vztahují na vizualizace, které znovu používají tento konkrétní parametr řídicího panelu. Řídicí panel může mít více parametrů, z nichž každý se může vztahovat na některé vizualizace, a ne na jiné.
Statická hodnota

Statické hodnoty se používají místo parametru, který reaguje na změny. Statické hodnoty umožňují pevně zakódovat hodnotu místo parametru a způsobí, že parametr "zmizí" z řídicího panelu nebo widgetu, kde se dříve objevil.

Když přidáte vizualizaci obsahující parametrizovaný dotaz, můžete zvolit název a zdroj parametru v dotazu vizualizace kliknutím na příslušnou ikonu tužky. Můžete také vybrat klíčové slovo a výchozí hodnotu. Viz vlastnosti parametru.

Po přidání vizualizace na řídicí panel přejděte k rozhraní mapování parametrů kliknutím na svislé tři tečky v pravém horním rohu widgetu řídicího panelu a následným kliknutím na změnit nastavení widgetu.

Vlastnosti parametru

Název: Zobrazovaný název, který se zobrazí vedle selektoru hodnot na řídicím panelu. Výchozí hodnota je klíčové slovo parametru. Pokud ho chcete upravit, klikněte na ikonu tužky . Názvy se nezobrazují pro parametry statického řídicího panelu, protože selektor hodnot je skrytý. Pokud jako zdroj hodnot vyberete statickou hodnotu, pole Název se zobrazí šedě.
Klíčové slovo: Řetězcový literál pro tento parametr v podkladovém dotazu. To je užitečné pro ladění, pokud řídicí panel nevrátí očekávané výsledky.
Výchozí hodnota: Hodnota použitá, pokud není zadána žádná jiná hodnota. Pokud to chcete změnit na obrazovce dotazu, spusťte dotaz s požadovanou hodnotou parametru a klikněte na tlačítko Uložit .
Zdroj hodnoty: Zdroj hodnoty parametru. Kliknutím na ikonu tužky vyberte zdroj.
- Nový parametr řídicího panelu: Vytvořte nový parametr na úrovni řídicího panelu. To vám umožní nastavit hodnotu parametru na jednom místě na řídicím panelu a namapovat ji na více vizualizací.
- Existující parametr řídicího panelu: Namapovat parametr na existující parametr řídicího panelu Musíte zadat, který parametr řídicího panelu už existuje.
- Parametr widgetu: Zobrazí selektor hodnot uvnitř widgetu řídicího panelu. To je užitečné pro jednorázové parametry, které nejsou sdíleny mezi widgety.
- Statická hodnota: Zvolte pro widget statickou hodnotu bez ohledu na hodnoty použité v jiných widgetech. Staticky mapované hodnoty parametrů nezobrazují selektor hodnot kdekoli na řídicím panelu, což je kompaktnější. To vám umožní využít flexibilitu parametrů dotazu bez nepotřebného uživatelského rozhraní na řídicím panelu, když se určité parametry nebudou často měnit.

Nejčastější dotazy

Můžu stejný parametr opakovaně použít v jednom dotazu?
Můžu v jednom dotazu použít více parametrů?

Můžu stejný parametr opakovaně použít v jednom dotazu?

Ano. Použijte stejný identifikátor ve složených závorkách. Tento příklad používá {{org_id}} parametr dvakrát.

SELECT {{org_id}}, count(0)
FROM queries
WHERE org_id = {{org_id}}

Můžu v jednom dotazu použít více parametrů?

Ano. Pro každý parametr použijte jedinečný název. Tento příklad používá dva parametry: {{org_id}} a {{start_date}}.

SELECT count(0)
FROM queries
WHERE org_id = {{org_id}} AND created_at > '{{start_date}}'