Praca z parametrami pulpitu nawigacyjnego

Artykuł
12/17/2024

W tym artykule wyjaśniono, jak używać parametrów na pulpitach nawigacyjnych sztucznej inteligencji/analizy biznesowej. Jeśli zamiast tego chcesz dowiedzieć się więcej o filtrach pól, zobacz Filtruj według pól.

Parametry pulpitu nawigacyjnego AI/BI umożliwiają zastępowanie różnych wartości zapytaniami zestawu danych w czasie wykonywania. Dzięki temu można filtrować dane według kryteriów, takich jak daty i kategorie produktów, zanim dane są agregowane w zapytaniu SQL, co prowadzi do bardziej wydajnego wykonywania zapytań i precyzyjnej analizy. Parametry mogą być używane z widżetami filtrów, aby pulpity nawigacyjne były interaktywne lub z widżetami wizualizacji, aby ułatwić ponowne użycie zestawów danych.

Autorzy pulpitów nawigacyjnych lub edytorzy dodają parametry do zestawów danych i połączą je z co najmniej jednym widżetem na kanwie pulpitu nawigacyjnego. W przypadku parametrów statycznych ustawionych w widżetach wizualizacji wartości są ustawiane przez autorów lub edytorów. W przypadku parametrów używanych w widżetach filtrów osoby przeglądające pulpit nawigacyjny mogą wchodzić w interakcje z danymi, wybierając wartości w widżetach filtru w czasie wykonywania. Ta interakcja ponownie uruchamia skojarzone zapytania i wyświetla wizualizacje na podstawie filtrowanych danych.

Parametry bezpośrednio modyfikują zapytanie, co może być zaawansowane. Filtry pól zestawu danych mogą również oferować interakcyjność pulpitu nawigacyjnego, więcej funkcji i lepszą wydajność z dużymi zestawami danych niż parametry. Zobacz Używanie filtrów.

Dodawanie parametru do zapytania

Aby dodać parametr do zestawu danych pulpitu nawigacyjnego pulpitu nawigacyjnego, musisz mieć co najmniej uprawnienia CAN EDIT na pulpicie nawigacyjnym. Parametry można dodawać bezpośrednio do zapytań zestawu danych na karcie Dane .

Plik GIF przedstawia przykład poniższych kroków.

Aby dodać parametr do zapytania:

Umieść kursor, w którym chcesz umieścić parametr w zapytaniu.
Kliknij pozycję Dodaj parametr , aby wstawić nowy parametr.

Spowoduje to utworzenie nowego parametru o domyślnej nazwie parameter. Aby zmienić nazwę domyślną, zastąp ją w edytorze zapytań. Parametry można również dodać, wpisując tę składnię w edytorze zapytań.

Edytowanie parametru zapytania

Aby edytować parametr:

Kliknij obok nazwy parametru. Zostanie wyświetlone okno dialogowe Szczegóły parametru i zawiera następujące opcje konfiguracji:
- Słowo kluczowe: słowo kluczowe reprezentujące parametr w zapytaniu. Można to zmienić tylko przez bezpośrednie zaktualizowanie tekstu w zapytaniu.
- Nazwa wyświetlana: nazwa w edytorze filtrów. Domyślnie tytuł jest taki sam jak słowo kluczowe.
- Typ: Obsługiwane typy obejmują ciąg, datę, datę i godzinę, numeryczne.
  - Domyślnym typem jest Ciąg.
  - Typ danych liczbowych umożliwia określenie między liczbami dziesiętnych i całkowitych. Domyślnym typem liczbowym jest Liczba dziesiętna.
- Zezwalaj na wiele zaznaczeń: zaznacz pole wyboru, aby umożliwić użytkownikom wybieranie wielu parametrów w czasie wykonywania.
  
  Uwaga
  
  Ten wybór może wymagać dodatkowej zmiany w zapytaniu. Zobacz Zezwalaj na wiele wyborów.
Kliknij inną część interfejsu użytkownika, aby zamknąć okno dialogowe.

Ustawianie domyślnej wartości parametru

Aby zapytanie było uruchamiane, wybierz wartość domyślną parametru, wpisując ją w polu tekstowym pod nazwą parametru. Uruchom zapytanie, aby wyświetlić podgląd wyników zapytania z zastosowaną wartością parametru. Uruchomienie zapytania umożliwia również zapisanie wartości domyślnej. Po ustawieniu tego parametru przy użyciu widżetu filtru na kanwie zostanie użyta wartość domyślna, chyba że nowa wartość domyślna zostanie określona w widżecie filtru. Zobacz Używanie filtrów.

Zezwalaj na wiele wyborów

Zapytania, które zezwalają na wiele wyborów, muszą zawierać ARRAY_CONTAINS funkcję w zapytaniu.

W poniższym przykładzie pokazano zapytanie SQL, które umożliwia wybranie wielu wartości do wstawienia do zapytania w czasie wykonywania. Klauzula WHERE ARRAY_CONTAINS używa funkcji . Ta funkcja przyjmuje słowo kluczowe parametru i nazwę kolumny jako argumenty. Po uruchomieniu zapytania zwraca wszystkie wiersze zawierające wybrane wartości parametrów.

SELECT
  *
FROM
  samples.tpch.lineitem
WHERE array_contains(:parameter, l_quantity)

Aby ustawić wartości domyślne, wpisz je w polu tekstowym pod nazwą wyświetlaną. Wybierz bieżącą wartość przed wprowadzeniem następnego.

Wartości domyślne są ustawiane w edytorze. Wiele wartości jest zaznaczonych i rozdzielonych spacją.

Stosowanie parametrów zakresu dat

Możesz użyć parametrów, aby zdefiniować zakres i zwrócić tylko wyniki w tym zakresie. Po wybraniu jednego z następujących typów parametrów należy utworzyć dwa parametry wyznaczone przez .min i .max sufiksy:

Zakres dat
Zakres daty i godziny

W poniższym przykładzie pokazano zapytanie SQL, które tworzy parametr zakresu dat o nazwie date_param.

SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min and :date_param.max

Aby utworzyć parametr zakresu dat:

Kliknij pozycję Dodaj parametr.
Kliknij obok nazwy parametru. Wprowadź słowo kluczowe i nazwę wyświetlaną. Nie dołączaj .min ani .max sufiksów.
Wybierz zakres dat lub zakres daty i godziny jako typ.
Wstaw klauzulę WHERE , która definiuje zakres w zapytaniu. Aby zdefiniować zakres, użyj BETWEEN klauzuli z wartościami .min i .max . Na przykład:
```
 WHERE date_col BETWEEN :date_param.min AND :date_param.max
```
Wprowadź domyślne wartości daty i uruchom zapytanie, aby je przetestować. Użyj ikony kalendarza, aby wybrać wstępnie ustawione opcje, takie jak ostatni tydzień lub ostatni miesiąc.

Parametry oparte na zapytaniach

Parametry oparte na zapytaniach umożliwiają autorom zdefiniowanie dynamicznej lub statycznej listy wartości, które osoby przeglądające mogą wybrać podczas ustawiania parametrów podczas eksplorowania danych na pulpicie nawigacyjnym. Są one definiowane przez połączenie filtru pola i filtru parametrów w jednym widżecie filtru.

Aby utworzyć parametr oparty na zapytaniach, autor pulpitu nawigacyjnego wykonuje następujące kroki:

Utwórz zestaw danych, którego zestaw wyników jest ograniczony do listy możliwych wartości parametrów.
Utwórz zapytanie zestawu danych, które używa parametru.
Skonfiguruj widżet filtru na kanwie filtru, który filtruje pole i używa parametru.
- Konfiguracje pól należy ustawić tak, aby używało pola z żądaną listą kwalifikujących się wartości parametrów.
- Konfiguracja parametrów powinna być ustawiona, aby wybrać wartość parametru.

Uwaga

Jeśli zestaw danych używany w parametrach opartych na zapytaniach jest również używany w innych wizualizacjach na pulpicie nawigacyjnym, wybór filtru przeglądarki modyfikuje wszystkie połączone zapytania. Aby tego uniknąć, autorzy powinni utworzyć dedykowany zestaw danych dla parametrów opartych na zapytaniach, które nie są używane w żadnych innych wizualizacjach na pulpicie nawigacyjnym.

Zobacz Używanie parametrów opartych na zapytaniach, aby zapoznać się z samouczkiem krok po kroku, który pokazuje, jak dodać parametr i wizualizację opartą na zapytaniach.

Tworzenie dynamicznej listy parametrów

Aby utworzyć dynamiczny zestaw danych, który wypełnia listę rozwijaną używaną przez osoby przeglądające do wybierania wartości parametrów, napisz zapytanie SQL zwracające jedno pole i zawierające wszystkie wartości w tym polu. Każda nowa wartość w tym polu jest automatycznie dodawana jako wybór parametru. Przykładowe zapytanie SQL jest następujące:

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

Tworzenie listy parametrów statycznych

Możesz utworzyć statyczny zestaw danych, który zawiera tylko wartości zakodowane na stałe w zestawie danych. Przykładowe zapytanie wygląda następująco:

SELECT
  *
FROM
  (
    VALUES
      ('MACHINERY'),
      ('BUILDING'),
      ('FURNITURE'),
      ('HOUSEHOLD'),
      ('AUTOMOBILE')
  ) AS data(available_choices)

Usuwanie parametru zapytania

Aby usunąć parametr, usuń go z zapytania.

Parametry statycznego widżetu są konfigurowane bezpośrednio w widżecie wizualizacji, co pozwala autorom indywidualnie sparametryzować widżety wizualizacji, które współużytkują ten sam zestaw danych. Dzięki temu ten sam zestaw danych może prezentować różne widoki na kanwie.

Przykład w tej sekcji jest oparty na zestawie danych, który wysyła zapytanie do samples.nyctaxi.trips tabeli. Podane zapytanie zwraca odległość każdej podróży i kategoryzuje dzień odbioru jako Weekday lub Weekend. Parametr zapytania filtruje wyniki na podstawie tego, czy odbiór miał miejsce w dni powszednie, czy w weekend.

Tekst zapytania znajduje się w poniższym bloku kodu, ale instrukcje w tej sekcji są ograniczone do konfigurowania skojarzonych wizualizacji skonfigurowanych z parametrami statycznego widżetu. Aby uzyskać instrukcje dotyczące konfigurowania zestawu danych z parametrami, zobacz Dodawanie parametru do zapytania.


  WITH DayType AS (
    SELECT
      CASE
        WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
        ELSE 'Weekday'
      END AS day_type,
      trip_distance
    FROM samples.nyctaxi.trips
  )
  SELECT day_type, trip_distance
  FROM DayType
  WHERE day_type = :day_type_param

Aby dodać parametr statycznego widżetu do wizualizacji:

Dodaj widżet wizualizacji do kanwy pulpitu nawigacyjnego wersji roboczej.
Po wybraniu nowego widżetu wybierz sparametryzowany zestaw danych z listy rozwijanej Zestaw danych w panelu konfiguracji.
Kliknij pozycję Pokaż filtry. W przypadku zestawów danych zawierających parametry w panelu konfiguracji zostanie wyświetlona sekcja Parametry .
Kliknij znak plus z prawej strony nagłówka Parametry i wybierz parametr z listy rozwijanej.
Domyślnie wartość parametru odzwierciedla to, co jest ustawione w zapytaniu na karcie Dane . Możesz zachować ją lub wybrać nową wartość, która ma zastąpić zestaw danych. Przejdź z dala od pola tekstowego, aby wyświetlić wizualizację z zastosowanym nowym parametrem.
Przejrzyj pulpit nawigacyjny.

Na poniższej ilustracji przedstawiono dwa widżety wizualizacji. Każda z nich jest konfigurowana jako histogram ze statycznym parametrem widżetu. Wykres po lewej stronie przedstawia rozkład odległości podróży dla podróży rozpoczynających się w dni robocze, podczas gdy wykres po prawej stronie pokazuje te same dane dla weekendów. Obie wizualizacje są oparte na tym samym zestawie danych.

Porównywanie danych przy użyciu warunku filtru

Można dodać warunek filtru, który umożliwia porównywanie agregacji w części danych z agregacjami zastosowanymi do całego zestawu danych.

Poniższy przykład rozszerza poprzednie zapytanie, aby uwzględnić warunek filtru, w którym określona wartość parametru to All, która nie jest wyświetlana w danych. Pierwsza część warunku filtru działa tak samo jak w poprzednim przykładzie, filtrowanie wyników, w których day_type wartość to Weekday lub Weekend. Druga część warunku filtru sprawdza, czy sam parametr jest ustawiony na określoną wartość, w tym przypadku All, która nie jest wyświetlana w danych. Po ustawieniu wartości domyślnej dla tego parametru w edytorze zestawów danych skutecznie pomijasz filtr, gdy ani Weekday Weekend nie są przekazywane jako wartości.


WITH DayType AS (
  SELECT
    CASE
      WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
      ELSE 'Weekday'
    END AS day_type,
    trip_distance
  FROM
    samples.nyctaxi.trips
)
SELECT
  day_type,
  trip_distance
FROM
  DayType
WHERE
  day_type = :day_type_param
  OR :day_type_param = 'All'

Tego zestawu danych można użyć do skonfigurowania trzech widżetów wizualizacji z ustawionym day_type_param odpowiednio wartością Alli Weekday Weekend . Następnie osoby przeglądające pulpit nawigacyjny mogą porównać każdy zestaw danych filtrowany według typu dnia do całego zestawu danych.

Poniższy plik GIF pokazuje, jak szybko utworzyć trzy wykresy z zestawu danych utworzonego za pomocą tego zapytania.

Pierwszy wykres jest skonfigurowany do wyświetlania zestawu danych Trip Distances by Day Type (Odległości podróży według typu dnia) z wartością parametru ustawioną na Wartość Dzień powszedni.
Sklonuj wykres, aby zachować wszystkie zastosowane konfiguracje.
Aby wyświetlić dane dotyczące podróży wykonanych w weekend, dostosuj parametr statyczny do weekendu.
Sklonuj nowy wykres, aby zachować wszystkie wcześniej zastosowane konfiguracje.
Ustaw parametr na nowym wykresie na Wartość Wszystkie , aby wyświetlić łączną liczbę podróży według odległości dla podróży weekendowych i dni powszednich.

Plik GIF opisany w poprzednim tekście.

Pokaż parametry na pulpicie nawigacyjnym

Dodanie filtru do kanwy pulpitu nawigacyjnego umożliwia przeglądającym wybieranie i modyfikowanie wartości parametrów w celu interaktywnego eksplorowania i analizowania danych. Jeśli nie uwidaczniasz parametru na pulpicie nawigacyjnym, osoby przeglądające zobaczą tylko wyniki zapytania, które używają domyślnej wartości parametru ustawionej w zapytaniu.

Aby dodać parametr do pulpitu nawigacyjnego:

Kliknij pozycję Dodaj filtr (pole/parametr).
Kliknij przycisk obok pozycji Parametry w panelu konfiguracji.
Kliknij nazwę parametru, który ma być używany przez przeglądarkę z tym widżetem.

Praca z widżetami filtru i parametrami statycznymi

Parametry są stałymi wartościami zastępowanymi w zapytaniu w czasie wykonywania. Jeśli co najmniej dwa odwołania do tego samego parametru są ustawione z różnymi wartościami podczas aktualizacji pulpitu nawigacyjnego, widżety wizualizacji wyświetlają błąd wskazujący, który parametr ma wartości powodujące konflikt. Taka sytuacja może wystąpić, gdy wiele widżetów filtrów używa tego samego parametru lub gdy parametr statyczny powoduje konflikt z widżetem filtru, który umożliwia wybór przeglądarki.

Możesz użyć wzorca takiego jak w poniższym przykładzie, aby ustawić wartości rezerwowe dla różnych parametrów w tym samym zapytaniu.


CASE WHEN :static_param != 'All' THEN :static_param ELSE :dash_param END

W tym przykładzie :static_param odwołuje się do parametru statycznego, który powinien być ustawiony na wartość "Wszystkie" zarówno w widżecie wizualizacji, jak i edytorze zestawów danych. Parametr :dash_param jest wartością dynamiczną kontrolowaną przez widżet filtru na kanwie pulpitu nawigacyjnego. Ta instrukcja sprawdza wartość podaną jako parametr statyczny. Jeśli żadna z nich nie zostanie ustawiona, zostanie przywrócona wartość parametru pulpitu nawigacyjnego wybranego przez przeglądarkę.

Uwzględnij parametry w adresie URL

Ustawienia parametrów są przechowywane w adresie URL, co umożliwia użytkownikom dodawanie zakładek do przechowywania stanu pulpitu nawigacyjnego, w tym wstępnie ustawionych filtrów i parametrów, lub udostępnianie go innym osobom w celu spójnego stosowania tych samych filtrów i parametrów.

Parametry pulpitu nawigacyjnego a parametry zapytania mustache

Parametry pulpitu nawigacyjnego używają tej samej składni co nazwane znaczniki parametrów. Zobacz Nazwane znaczniki parametrów. Pulpity nawigacyjne nie obsługują parametrów stylu wąsów.

Przykłady składni

Typowe zastosowania parametrów obejmują wstawianie dat, liczb, tekstu, obiektów bazy danych i wartości z ciągów JSON. Przykłady, które pokazują, jak używać parametrów w tych przypadkach, zobacz Nazwane przykłady składni parametrów

Ważne

Włączenie osób przeglądających uzyskiwanie dostępu do danych za pośrednictwem wyborów parametrów, takich jak nazwy tabel lub katalogów, może prowadzić do przypadkowego ujawnienia poufnych informacji. Jeśli publikujesz pulpit nawigacyjny przy użyciu tych opcji, usługa Azure Databricks zaleca nie osadzanie poświadczeń na opublikowanym pulpicie nawigacyjnym.

Udostępnij za pośrednictwem