Delen via

Queryparameters

  • Artikel

Met een queryparameter kunt u waarden in een query vervangen tijdens runtime. Elke tekenreeks tussen dubbele accolades {{ }} wordt behandeld als een queryparameter. Er wordt een widget weergegeven boven het resultatenvenster waar u de parameterwaarde instelt. Queryparameters zijn flexibeler dan queryfilters en moeten alleen worden gebruikt in gevallen waarin queryfilters niet voldoende zijn.

Een queryparameter toevoegen

  1. Typ Cmd + I. De parameter wordt ingevoegd in de tekst caret en het dialoogvenster Parameter toevoegen wordt weergegeven.
    • Trefwoord: het trefwoord dat de parameter in de query vertegenwoordigt.
    • Titel: De titel die over de widget wordt weergegeven. De titel is standaard hetzelfde als het trefwoord.
    • Type: Ondersteunde typen zijn tekst, getal, datum, datum en tijd, datum en tijd (met seconden), vervolgkeuzelijst en vervolgkeuzelijst op basis van query's. De standaardwaarde is de tekst.
  2. Voer het trefwoord in, overschrijf eventueel de titel en selecteer het parametertype.
  3. Klik op Parameter toevoegen.
  4. Stel in de parameterwidget de parameterwaarde in.
  5. Klik op Wijzigingen toepassen.
  6. Klik op Opslaan.

U kunt ook dubbele accolades {{ }} typen en op het tandwielpictogram in de buurt van de parameterwidget klikken om de instellingen te bewerken.

Als u de query opnieuw wilt uitvoeren met een andere parameterwaarde, voert u de waarde in de widget in en klikt u op Wijzigingen toepassen.

Een queryparameter bewerken

Als u een parameter wilt bewerken, klikt u op het tandwielpictogram naast de parameterwidget. Als u wilt voorkomen dat gebruikers die geen eigenaar zijn van de query de parameter wijzigen, klikt u op Alleen resultaten weergeven. Het <Keyword> parameterdialoogvenster wordt weergegeven.

Een queryparameter verwijderen

Als u een queryparameter wilt verwijderen, verwijdert u de parameter uit uw query. De parameterwidget verdwijnt en u kunt uw query opnieuw schrijven met behulp van statische waarden.

De volgorde van parameters wijzigen

Als u de volgorde wilt wijzigen waarin parameters worden weergegeven, kunt u op elke parameter klikken en naar de gewenste positie slepen.

Queryparametertypen

Sms verzenden

Neemt een tekenreeks als invoer. Backslash-, enkele en dubbele aanhalingstekens worden ontsnapt en Azure Databricks voegt aanhalingstekens toe aan deze parameter. Een tekenreeks zoals mr's Li"s deze wordt omgezet in 'mr\'s Li\"s' een voorbeeld van het gebruik hiervan kan bijvoorbeeld zijn

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

Aantal

Neemt een getal als invoer. Een voorbeeld van het gebruik hiervan kan zijn

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

Als u het bereik van mogelijke parameterwaarden wilt beperken bij het uitvoeren van een query, gebruikt u het parametertype Vervolgkeuzelijst . Een voorbeeld hiervan is SELECT * FROM users WHERE name='{{ dropdown_param }}'. Wanneer u deze optie selecteert in het deelvenster parameterinstellingen, wordt er een tekstvak weergegeven waarin u de toegestane waarden invoert, elke waarde gescheiden door een nieuwe regel. Vervolgkeuzelijsten zijn tekstparameters. Als u datums of datums en tijden in de vervolgkeuzelijst wilt gebruiken, voert u deze in de indeling in die uw gegevensbron nodig heeft. De tekenreeksen worden niet ontsnapt. U kunt kiezen tussen een vervolgkeuzelijst met één waarde of meerdere waarden.

  • Enkele waarde: enkele aanhalingstekens rond de parameter zijn vereist.
  • Meerdere waarden: schakel de optie Meerdere waarden toestaan in. Kies in de vervolgkeuzelijst Offerte of u de parameters wilt laten staan zoals opgegeven (geen aanhalingstekens) of de parameters tussen enkele of dubbele aanhalingstekens laten staan. U hoeft geen aanhalingstekens toe te voegen rond de parameter als u aanhalingstekens kiest.

Wijzig uw WHERE component om het IN trefwoord in uw query te gebruiken.

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

Met de parameterwidget voor meerdere selecties kunt u meerdere waarden doorgeven aan de database. Als u de optie Dubbele aanhalingstekens voor de parameter Aanhalingsteken selecteert, geeft uw query de volgende indeling weer: WHERE IN ("value1", "value2", "value3")

Vervolgkeuzelijst op basis van query's

Neemt het resultaat van een query als invoer. Het heeft hetzelfde gedrag als de parameter vervolgkeuzelijst . U moet de Databricks SQL-vervolgkeuzelijstquery opslaan om deze als invoer in een andere query te kunnen gebruiken.

  1. Klik op vervolgkeuzelijst op basis van query's onder Type in het deelvenster Instellingen.
  2. Klik op het veld Query en selecteer een query. Als uw doelquery een groot aantal records retourneert, worden de prestaties verslechterd.

Als uw doelquery meer dan één kolom retourneert, gebruikt Databricks SQL de eerste . Als uw doelquery retourneert en kolommen retourneertname, vult Databricks SQL de widget parameterselectie in met de name kolom, maar voert u de query uit met de bijbehorendevalue.value

Stel dat de volgende query de gegevens in de tabel retourneert.

SELECT user_uuid AS 'value', username AS 'name'
FROM users
waarde naam
1001 John Smith
1002 Jane Doe
1003 Bobby Tables

Wanneer Azure Databricks de query uitvoert, is de waarde die wordt doorgegeven aan de database 1001, 1002 of 1003.

Datum en tijd

Azure Databricks heeft verschillende opties voor het parameteriseren van datum- en tijdstempelwaarden, waaronder opties om de parameterisering van tijdsbereiken te vereenvoudigen. U kunt kiezen uit drie opties met verschillende precisie:

Optie Precisie Type
Datum dagen DATE
Datum en tijd minuten TIMESTAMP
Datum en tijd (met seconden) tweede TIMESTAMP

Wanneer u een bereikparameteroptie kiest, maakt u twee parameters die zijn aangewezen door .start en .end achtervoegsels. Alle opties geven parameters door aan uw query als letterlijke tekenreeksen; Voor Azure Databricks moeten datum- en tijdwaarden tussen enkele aanhalingstekens (') worden verpakt. Voorbeeld:

-- 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 }}'

Datumparameters gebruiken een interface voor het kiezen van agenda's en gebruiken standaard de huidige datum en tijd.

Notitie

De parameter Datumbereik retourneert alleen de juiste resultaten voor kolommen van het DATE type. Gebruik TIMESTAMP voor kolommen een van de opties datum- en tijdsbereik.

Dynamische datum- en datumbereikwaarden

Wanneer u een datum- of datumbereikparameter aan uw query toevoegt, wordt in de selectiewidget een blauw bliksemschichtpictogram weergegeven. Klik erop om dynamische waarden weer te geven, zoals , , , , of last yearlast month. last weekthis weekyesterdaytoday Deze waarden worden dynamisch bijgewerkt.

Belangrijk

Dynamische datums en datumbereiken zijn niet compatibel met geplande query's.

Queryparameters gebruiken in dashboards

Optioneel kunnen query's parameters of statische waarden gebruiken. Wanneer een visualisatie op basis van een geparameteriseerde query wordt toegevoegd aan een dashboard, kan de visualisatie worden geconfigureerd voor het gebruik van een van de volgende opties:

  • Widgetparameter

    Widgetparameters zijn specifiek voor één visualisatie in een dashboard, worden weergegeven in het visualisatievenster en de opgegeven parameterwaarden zijn alleen van toepassing op de query die onder de visualisatie wordt uitgevoerd.

  • Dashboardparameter

    Dashboardparameters kunnen worden toegepast op meerdere visualisaties. Wanneer u een visualisatie toevoegt op basis van een geparameteriseerde query aan een dashboard, wordt de parameter standaard toegevoegd als een dashboardparameter. Dashboardparameters zijn geconfigureerd voor een of meer visualisaties in een dashboard en worden boven aan het dashboard weergegeven. De parameterwaarden die zijn opgegeven voor een dashboardparameter zijn van toepassing op visualisaties die die specifieke dashboardparameter hergebruiken. Een dashboard kan meerdere parameters bevatten, die elk kunnen worden toegepast op sommige visualisaties en niet op andere.

  • Statische waarde

    Statische waarden worden gebruikt in plaats van een parameter die reageert op wijzigingen. Met statische waarden kunt u een waarde in plaats van een parameter hard coden en de parameter 'verdwijnen' uit het dashboard of de widget waar deze eerder werd weergegeven.

Wanneer u een visualisatie met een geparameteriseerde query toevoegt, kunt u de titel en de bron voor de parameter in de visualisatiequery kiezen door op het desbetreffende potloodpictogram te klikken. U kunt ook het trefwoord en een standaardwaarde selecteren. Zie parametereigenschappen.

Nadat u een visualisatie aan een dashboard hebt toegevoegd, opent u de interface voor parametertoewijzing door in de rechterbovenhoek van een dashboardwidget te klikken op het menu Voor de parametertoewijzing en vervolgens op Widgetinstellingen wijzigen te klikken.

Parametereigenschappen

  • Titel: De weergavenaam die naast de waardekiezer op uw dashboard wordt weergegeven. Deze wordt standaard ingesteld op het parameterwoord. Als u het wilt bewerken, klikt u op het potloodpictogram Potloodpictogram. Titels worden niet weergegeven voor statische dashboardparameters omdat de waardekiezer verborgen is. Als u statische waarde als waardebron selecteert, wordt het veld Titel grijs weergegeven.

  • Trefwoord: de letterlijke tekenreeks voor deze parameter in de onderliggende query. Dit is handig voor foutopsporing als uw dashboard niet de verwachte resultaten retourneert.

  • Standaardwaarde: de waarde die wordt gebruikt als er geen andere waarde is opgegeven. Als u dit wilt wijzigen vanuit het queryscherm, voert u de query uit met de gewenste parameterwaarde en klikt u op de knop Opslaan .

  • Waardebron: de bron van de parameterwaarde. Klik op het potloodpictogram Potloodpictogram om een bron te kiezen.

    • Nieuwe dashboardparameter: maak een nieuwe parameter op dashboardniveau. Hiermee kunt u een parameterwaarde instellen op één plaats op uw dashboard en deze toewijzen aan meerdere visualisaties.
    • Bestaande dashboardparameter: Wijs de parameter toe aan een bestaande dashboardparameter. U moet opgeven welke bestaande dashboardparameter al bestaat.
    • Widgetparameter: Geeft een waardekiezer weer in de dashboardwidget. Dit is handig voor eenmalige parameters die niet worden gedeeld tussen widgets.
    • Statische waarde: Kies een statische waarde voor de widget, ongeacht de waarden die op andere widgets worden gebruikt. Statisch toegewezen parameterwaarden geven nergens een waardekiezer weer op het dashboard, wat compacter is. Hiermee kunt u profiteren van de flexibiliteit van queryparameters zonder dat u de gebruikersinterface op een dashboard onoverzichtelijk maakt wanneer bepaalde parameters naar verwachting niet regelmatig worden gewijzigd.

    Parametertoewijzing wijzigen

Veelgestelde vragen (FAQ)

Kan ik dezelfde parameter meerdere keren opnieuw gebruiken in één query?

Ja. Gebruik dezelfde id in de accolades. In dit voorbeeld wordt de {{org_id}} parameter twee keer gebruikt.

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

Kan ik meerdere parameters in één query gebruiken?

Ja. Gebruik een unieke naam voor elke parameter. In dit voorbeeld worden twee parameters gebruikt: {{org_id}} en {{start_date}}.

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