Parametry zapytań

Parametr zapytania umożliwia podstawianie wartości do zapytania w czasie wykonywania. Każdy ciąg między podwójnymi nawiasami klamrowymi {{ }} jest traktowany jako parametr zapytania. Widżet jest wyświetlany powyżej okienka wyników, w którym ustawiono wartość parametru. Parametry zapytania są bardziej elastyczne niż filtry zapytań i powinny być używane tylko w przypadkach, gdy filtry zapytań nie są wystarczające.

Dodawanie parametru zapytania

1. Wpisz Cmd + I. Parametr zostanie wstawiony do daszka tekstowego, a zostanie wyświetlone okno dialogowe Dodawanie parametru.
   • Słowo kluczowe: słowo kluczowe reprezentujące parametr w zapytaniu.
   • Tytuł: tytuł wyświetlany nad widżetem. Domyślnie tytuł jest taki sam jak słowo kluczowe.
   • Typ: Obsługiwane typy to tekst, liczba, data, data i godzina, data i godzina (z sekundami), lista rozwijana i lista rozwijana oparta na zapytaniach. Wartość domyślna to Text.
2. Wprowadź słowo kluczowe, opcjonalnie przesłoń tytuł i wybierz typ parametru.
3. Kliknij pozycję Dodaj parametr.
4. W widżecie parametru ustaw wartość parametru.
5. Kliknij pozycję Zastosuj zmiany.
6. Kliknij przycisk Zapisz.

Alternatywnie wpisz podwójne nawiasy klamrowe {{ }} i kliknij ikonę koła zębatego w pobliżu widżetu parametru, aby edytować ustawienia.

Aby ponownie uruchomić zapytanie z inną wartością parametru, wprowadź wartość w widżecie i kliknij przycisk Zastosuj zmiany.

Edytowanie parametru zapytania

Aby edytować parametr, kliknij ikonę koła zębatego obok widżetu parametru. Aby uniemożliwić użytkownikom, którzy nie są właścicielami zapytania zmiany parametru, kliknij pozycję Pokaż tylko wyniki. Zostanie <Keyword> wyświetlone okno dialogowe parametru.

Usuwanie parametru zapytania

Aby usunąć parametr zapytania, usuń parametr z zapytania. Widżet parametru zniknie i możesz ponownie napisać zapytanie przy użyciu wartości statycznych.

Zmienianie kolejności parametrów

Aby zmienić kolejność wyświetlania parametrów, możesz kliknąć i przeciągnąć każdy parametr do żądanej pozycji.

Typy parametrów zapytania

• Tekst
• Liczba
• Lista rozwijana
• Lista rozwijana oparta na zapytaniach
• Data i godzina

Text

Przyjmuje ciąg jako dane wejściowe. Znaki ukośnika odwrotnego, pojedynczego i podwójnego cudzysłowu są ucieczki, a usługa Azure Databricks dodaje znaki cudzysłowu do tego parametru. Na przykład ciąg podobny mr's Li"s do ciągu jest przekształcany do 'mr\'s Li\"s' przykładu użycia tego elementu

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

Liczba

Przyjmuje liczbę jako dane wejściowe. Przykładem użycia tego elementu może być

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

Lista rozwijana

Aby ograniczyć zakres możliwych wartości parametrów podczas uruchamiania zapytania, użyj typu parametru Lista rozwijana. Przykładem może być SELECT * FROM users WHERE name='{{ dropdown_param }}'. Po wybraniu z panelu ustawień parametrów zostanie wyświetlone pole tekstowe, w którym wprowadzasz dozwolone wartości, każda wartość oddzielona nową linią. Listy rozwijane to parametry tekstowe. Aby użyć dat lub dat i godzin na liście rozwijanej, wprowadź je w formacie wymaganym przez źródło danych. Ciągi nie są usuwane. Możesz wybrać jedną wartość lub listę rozwijaną z wieloma wartościami.

• Pojedyncza wartość: wymagane są pojedyncze cudzysłowy wokół parametru.
• Wiele wartości: przełącz opcję Zezwalaj na wiele wartości . Na liście rozwijanej Cudzysłów wybierz, czy parametry mają pozostać wprowadzone (bez cudzysłowów) lub opakowować parametry za pomocą pojedynczych lub podwójnych cudzysłowów. Nie musisz dodawać cudzysłowów wokół parametru, jeśli wybierzesz znaki cudzysłowu.

WHERE Zmień klauzulę, aby użyć słowa kluczowego IN w zapytaniu.

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

Widżet wielokrotnego wyboru parametru umożliwia przekazanie wielu wartości do bazy danych. W przypadku wybrania opcji Podwójny znak cudzysłowu dla parametru Cudzysłowu zapytanie odzwierciedla następujący format: WHERE IN ("value1", "value2", "value3")

Lista rozwijana oparta na zapytaniach

Pobiera wynik zapytania jako dane wejściowe. Ma to samo zachowanie co parametr Lista rozwijana. Musisz zapisać zapytanie listy rozwijanej SQL usługi Databricks, aby użyć go jako danych wejściowych w innym zapytaniu.

1. Kliknij pozycję Lista rozwijana oparta na zapytaniach w obszarze Typ w panelu ustawień.
2. Kliknij pole Zapytanie i wybierz zapytanie. Jeśli zapytanie docelowe zwraca dużą liczbę rekordów, wydajność będzie spadać.

Jeśli zapytanie docelowe zwraca więcej niż jedną kolumnę, usługa SQL usługi Databricks używa pierwszej kolumny. Jeśli zapytanie docelowe zwraca name kolumny i value kolumny, usługa Sql usługi Databricks wypełnia widżet wyboru parametrów kolumną name , ale wykonuje zapytanie ze skojarzonym elementem value.

Załóżmy na przykład, że poniższe zapytanie zwraca dane w tabeli.

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

wartość	name
1001	John Smith
1002	Jane Doe
1003	Tabele Bobby

Gdy usługa Azure Databricks uruchamia zapytanie, wartość przekazana do bazy danych to 1001, 1002 lub 1003.

Data i godzina

Usługa Azure Databricks oferuje kilka opcji sparametryzowania wartości daty i znacznika czasu, w tym opcje upraszczające parametryzację zakresów czasu. Wybierz spośród trzech opcji o różnej precyzji:

Opcja	Dokładność	Typ
Data	dzień	DATE
Data i godzina	min.	TIMESTAMP
Data i godzina (z sekundami)	Drugi	TIMESTAMP

Podczas wybierania opcji parametru Zakres należy utworzyć dwa parametry wyznaczone przez .start i .end sufiksy. Wszystkie opcje przekazują parametry do zapytania jako literały ciągu; Usługa Azure Databricks wymaga opakowowania wartości daty i godziny w pojedynczych cudzysłowach ('). Na przykład:

-- 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 daty używają interfejsu wybierania kalendarza i domyślnie do bieżącej daty i godziny.

Uwaga

Parametr Zakres dat zwraca tylko poprawne wyniki dla kolumn DATE typu. W przypadku TIMESTAMP kolumn użyj jednej z opcji Zakres dat i godzin.

Dynamiczne wartości daty i zakresu dat

Po dodaniu parametru daty lub zakresu dat do zapytania widżet wyboru wyświetla niebieską ikonę błyskawicy. Kliknij go, aby wyświetlić wartości dynamiczne, takie jak today, , yesterdaythis week, last week, last monthlub last year. Te wartości są aktualizowane dynamicznie.

Ważne

Dynamiczne daty i zakresy dat nie są zgodne z zaplanowanymi zapytaniami.

Używanie parametrów zapytania na pulpitach nawigacyjnych

Opcjonalnie zapytania mogą używać parametrów lub wartości statycznych. Gdy wizualizacja oparta na zapytaniu sparametryzowanym zostanie dodana do pulpitu nawigacyjnego, można skonfigurować wizualizację tak, aby korzystała z jednej z następujących opcji:

• Parametr widżetu

  Parametry widżetu są specyficzne dla pojedynczej wizualizacji na pulpicie nawigacyjnym, są wyświetlane w panelu wizualizacji, a określone wartości parametrów dotyczą tylko zapytania bazowego wizualizacji.

• Parametr pulpitu nawigacyjnego

  Parametry pulpitu nawigacyjnego mogą być stosowane do wielu wizualizacji. Po dodaniu wizualizacji na podstawie sparametryzowanego zapytania do pulpitu nawigacyjnego parametr zostanie domyślnie dodany jako parametr pulpitu nawigacyjnego. Parametry pulpitu nawigacyjnego są skonfigurowane dla co najmniej jednej wizualizacji na pulpicie nawigacyjnym i są wyświetlane w górnej części pulpitu nawigacyjnego. Wartości parametrów określone dla parametru pulpitu nawigacyjnego mają zastosowanie do wizualizacji ponownie korzystających z tego konkretnego parametru pulpitu nawigacyjnego. Pulpit nawigacyjny może mieć wiele parametrów, z których każdy może być stosowany do niektórych wizualizacji, a nie innych.

• Wartość statyczna

  Wartości statyczne są używane zamiast parametru, który reaguje na zmiany. Wartości statyczne umożliwiają kodowanie wartości zamiast parametru i spowoduje, że parametr "zniknie" z pulpitu nawigacyjnego lub widżetu, w którym wcześniej się pojawił.

Po dodaniu wizualizacji zawierającej sparametryzowane zapytanie można wybrać tytuł i źródło parametru w zapytaniu wizualizacji, klikając odpowiednią ikonę ołówka. Możesz również wybrać słowo kluczowe i wartość domyślną. Zobacz Właściwości parametru.

Po dodaniu wizualizacji do pulpitu nawigacyjnego uzyskaj dostęp do interfejsu mapowania parametrów, klikając pionowy wielokropek w prawym górnym rogu widżetu pulpitu nawigacyjnego, a następnie klikając pozycję Zmień ustawienia widżetu.

Właściwości parametru

• Tytuł: nazwa wyświetlana wyświetlana wyświetlana obok selektora wartości na pulpicie nawigacyjnym. Domyślnie jest to słowo kluczowe parametru . Aby go edytować, kliknij ikonę ołówka . Tytuły nie są wyświetlane dla statycznych parametrów pulpitu nawigacyjnego, ponieważ selektor wartości jest ukryty. Jeśli wybierzesz wartość statyczną jako źródło wartości, pole Tytuł będzie wyszarane.

• Słowo kluczowe: literał ciągu dla tego parametru w zapytaniu źródłowym. Jest to przydatne do debugowania, jeśli pulpit nawigacyjny nie zwraca oczekiwanych wyników.

• Wartość domyślna: wartość używana, jeśli nie określono żadnej innego wartości. Aby zmienić to z ekranu zapytania, uruchom zapytanie z żądaną wartością parametru i kliknij przycisk Zapisz .

• Źródło wartości: źródło wartości parametru. Kliknij ikonę ołówka, aby wybrać źródło.

  • Nowy parametr pulpitu nawigacyjnego: utwórz nowy parametr na poziomie pulpitu nawigacyjnego. Dzięki temu można ustawić wartość parametru w jednym miejscu na pulpicie nawigacyjnym i zamapować ją na wiele wizualizacji.
  • Istniejący parametr pulpitu nawigacyjnego: mapuj parametr na istniejący parametr pulpitu nawigacyjnego. Musisz określić, który wcześniej istniejący parametr pulpitu nawigacyjnego.
  • Parametr widżetu: wyświetla selektor wartości wewnątrz widżetu pulpitu nawigacyjnego. Jest to przydatne w przypadku jednorazowych parametrów, które nie są udostępniane między widżetami.
  • Wartość statyczna: wybierz wartość statyczną dla widżetu, niezależnie od wartości używanych w innych widżetach. Statycznie mapowane wartości parametrów nie wyświetlają selektora wartości w dowolnym miejscu na pulpicie nawigacyjnym, co jest bardziej kompaktowe. Dzięki temu można korzystać z elastyczności parametrów zapytania bez zaśmiecania interfejsu użytkownika na pulpicie nawigacyjnym, gdy niektóre parametry nie powinny się często zmieniać.

  

Często zadawane pytania

• Czy można wielokrotnie używać tego samego parametru w jednym zapytaniu?
• Czy mogę użyć wielu parametrów w jednym zapytaniu?

Czy można wielokrotnie używać tego samego parametru w jednym zapytaniu?

Tak. Użyj tego samego identyfikatora w nawiasach klamrowych. W tym przykładzie użyto parametru {{org_id}} dwa razy.

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

Czy mogę użyć wielu parametrów w jednym zapytaniu?

Tak. Użyj unikatowej nazwy dla każdego parametru. W tym przykładzie użyto dwóch parametrów: {{org_id}} i {{start_date}}.

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