Używanie parametrów z widokami metryk

Parametry umożliwiają przekazywanie wartości do widoku metryki podczas wykonywania zapytań. Użyj parametrów, aby wielokrotnie używać jednej definicji widoku metryki dla różnych danych wejściowych, takich jak stopa dyskontowa lub zakres dat. Odwołuj się do parametru w dowolnym miejscu, w jakim jest prawidłowe wyrażenie SQL stałe, na przykład w filtrach, wyrażeniach pól i miar, źródle i sprzężeniach. Możesz także odnieść się do parametru całkowitoliczbowego jako wartości miary range okna lub offset, więc wywołujący przesyła rozmiar okna w czasie zapytania. Przekaż wartość jako argument podczas wykonywania zapytania względem widoku.

Parametry zmniejszają duplikację. Zamiast utrzymywać oddzielny widok metryki dla każdego wariantu, należy zdefiniować logikę raz i pozwolić każdemu obiektowi wywołującego podać własne wartości. Parametr może zawierać wartość domyślną, więc wywołujące, które nie przekazują argumentu, wracają do wartości domyślnej.

Możesz przekazać wartości parametrów z zapytania SQL lub pulpitu nawigacyjnego AI/BI. Na pulpicie nawigacyjnym połącz parametr z widżetem filtru, aby umożliwić widzom wybranie wartości w czasie wykonywania. Zobacz Używanie zapytania sparametryzowanego na pulpicie nawigacyjnym.

Wymagania

  • Aby utworzyć widok metryk definiujący parametry, potrzebne są uprawnienia CREATE TABLE i USE SCHEMA do schematu oraz uprawnienie USE CATALOG do katalogu nadrzędnego. Aby uzyskać pełną listę uprawnień wymaganych do utworzenia widoku metryki, zobacz Tworzenie widoku metryki.
  • Aby wykonać zapytanie dotyczące widoku metryki definiującego parametry, potrzebujesz magazynu SQL lub innego zasobu obliczeniowego z uruchomionym środowiskiem Databricks Runtime 18.2 lub nowszym. Aby uzyskać więcej wymagań dotyczących wersji, zobacz Dostępność funkcji widoku metryk.

Limitations

Następujące ograniczenia dotyczą widoków metryk, które definiują parametry:

  • Nie można zmaterializować widoku metryki, który definiuje parametry.
  • Wartości domyślne mają ograniczenia. Wartość domyślna musi być rzutowalna do zadeklarowanego typu danych parametru i nie może odwoływać się do innego parametru ani zawierać podzapytania. Jeśli ustawisz wartość domyślną dla jednego parametru, każdy z poniższych parametrów również musi mieć wartość domyślną. Zobacz Parametry.

Definiuj parametry

Parametry można zdefiniować w edytorze z małą ilością kodu w Eksploratorze wykazu lub bezpośrednio w języku YAML. Po utworzeniu parametru odwołuj się do niego za pomocą jego nazwy wszędzie tam, gdzie dozwolone jest stałe wyrażenie SQL, na przykład w filtrach, wyrażeniach pól i miar, źródle oraz połączeniach. Możesz także odnieść się do parametru całkowitego jako wartości miary range okna lub offset. Zobacz Wymiary okna.

Aby zdefiniować parametry w języku YAML, dodaj blok najwyższego poziomu parameters do definicji widoku metryki. Aby uzyskać pełne odwołanie do pola i przykład YAML, zobacz Parametry.

Poniższe kroki wykorzystują edytor typu low-code w Eksploratorze katalogu oraz tabelę samples.tpch.orders, dostępną w każdym obszarze roboczym, aby utworzyć widok metryki z parametrem discount i dwiema miarami. Jedna miara stosuje parametr, a druga oblicza niediscountowaną sumę, aby można było porównać te dwa.

Krok 1: Utwórz widok metryki

Utwórz widok metryki do przechowywania parametru i miar.

  1. Kliknij ikonę Dane.Wykaz na pasku bocznym obszaru roboczego, a następnie użyj paska wyszukiwania, aby znaleźć samples.tpch.orders i kliknąć nazwę tabeli.
  2. Kliknij pozycję Utwórz>Widok metryki.
  3. W oknie dialogowym Tworzenie widoku metryki wprowadź nazwę, a następnie wybierz katalog i schemat, aby utworzyć widok metryki. Kliknij pozycję Utwórz.

Edytor otwiera się na karcie UI. Pełny przewodnik po edytorze widoku metryki znajdziesz w sekcji Tworzenie widoku metryki.

Krok 2. Dodawanie parametru

discount Dodaj parametr z typem liczbowym i wartością domyślną.

  1. W nagłówku edytora kliknij pozycję Dodaj parametr.

  2. W oknie dialogowym Szczegóły parametru :

    1. Wprowadź discount dla Nazwa.
    2. Wybierz pozycję Numeryczne z listy rozwijanej Typ .
    3. Wybierz pozycję Double z wyświetlonej listy rozwijanej Typ liczbowy.

    Przycisk Dodaj parametr i okno dialogowe Szczegóły parametru z rabatem ustawionym na typ liczbowy i Podwójny typ liczbowy.

  3. Kliknij przycisk z dala od okna dialogowego, aby go zamknąć, a następnie wprowadź 0.15 jako wartość domyślną rabatu.

    Parametr rabatu z wartością domyślną 0,15.

Parametr zostanie wyświetlony w nagłówku edytora po jego utworzeniu. Ustawiona tutaj wartość jest wartością domyślną, która ma zastosowanie, gdy zapytanie pomija argument.

Krok 3. Dodawanie miary używającej parametru

Odwołuj się do parametru według nazwy w wyrażeniu miary. Ta miara stosuje rabat do każdej sumy zamówień.

  1. Kliknij kartę Miary w górnej części edytora.

  2. Kliknij pozycję + Dodaj.

  3. Wprowadź Discounted Sales jako nazwę miary.

  4. Kliknij pozycję Niestandardowe, a następnie wprowadź następujące wyrażenie:

    SUM((1 - discount) * source.o_totalprice)
    

Krok 4. Dodawanie innej miary

Dodaj drugą miarę dla sumy całkowitej bez rabatu.

  1. Kliknij pozycję + Dodaj.
  2. Wprowadź Total Sales jako nazwę miary.
  3. W konstruktorze wybierz source.o_totalprice i agregację Suma, aby utworzyć SUM(source.o_totalprice).

Krok 5: Zapisz widok metryki

Kliknij Zapisz. Aby wysłać zapytanie do widoku metryki i przekazać wartość parametru discount , zobacz Query a metric view with parameters (Wykonywanie zapytań w widoku metryki z parametrami).

Wykonaj zapytanie dotyczące widoku metryk z parametrami

Aby wysłać zapytanie do widoku metryki definiującego parametry, wywołaj widok metryki jako funkcję wartości tabeli i przekaż parametry jako argumenty. Argumenty można przekazać według nazwy lub pozycji albo pominąć, aby użyć wartości domyślnych.

Przekazywanie argumentów według nazwy

Aby przekazać argument przez nazwę, użyj operatora =>. Poniższy przykład przekazuje wartość discount równą 0.15

SELECT product, MEASURE(discountedSales)
FROM catalog.schema.metric_view(discount => 0.15)
GROUP BY product;

Przekazywanie argumentów według pozycji

Aby przekazać argumenty po pozycji, podaj wartości w kolejności, w jakiej zdefiniowano parametry. Poniższy przykład przekazuje tę samą wartość discount wynoszącą 0.15:

SELECT product, MEASURE(discountedSales)
FROM catalog.schema.metric_view(0.15)
GROUP BY product;

Użyj domyślnych wartości parametrów

Aby użyć domyślnych wartości parametrów podczas wywoływania widoku metryki, pomiń argumenty. Następujące zapytania są równoważne i używają wszystkich wartości domyślnych:

SELECT product, MEASURE(discountedSales) FROM catalog.schema.metric_view() GROUP BY product;
SELECT product, MEASURE(discountedSales) FROM catalog.schema.metric_view GROUP BY product;

Wyświetl parametry zdefiniowane przez widok metryk

Aby wyświetlić parametry zdefiniowane przez widok metryki, wyświetl jego definicję YAML, która zawiera parameters blok. Zobacz Definicja widoku metryk i metadane.

Używanie zapytania sparametryzowanego na pulpicie nawigacyjnym

Za pomocą dowolnego z tych zapytań można zdefiniować zestaw danych na pulpicie nawigacyjnym sztucznej inteligencji/analizy biznesowej. Odwołaj się do widoku metryki w zestawie danych SQL i przekaż parametr jako argument w wywołaniu funkcji wartości tabeli. Aby umożliwić użytkownikom pulpitu nawigacyjnego wybór wartości w czasie działania, przekaż parametr pulpitu nawigacyjnego jako argument i połącz go z widżetem filtrowania. Zobacz Przekazywanie parametrów do widoku metryki.

Dodatkowe zasoby