Udostępnij przez

Odniesienie do składni YAML

Definicje widoku metryki są zgodne ze standardową składnią notacji YAML. Na tej stronie wyjaśniono, jak zdefiniować widok metryki.

Zobacz dokumentację specyfikacji YAML 1.2.2 , aby dowiedzieć się więcej na temat specyfikacji YAML.

Omówienie kodu YAML

Definicja YAML widoku metryki zawiera następujące pola najwyższego poziomu:

  • version: Wartość domyślna to 1.1. Jest to wersja specyfikacji widoku metryki. Zobacz Dziennik zmian specyfikacji wersji.
  • source: dane źródłowe dla widoku metryk. Może to być zasób podobny do tabeli lub zapytanie SQL.
  • joins: Opcjonalne. Schemat gwiazdy i połączenia schematu płatka śniegu są obsługiwane.
  • filter: Opcjonalne. Wyrażenie logiczne SQL, które ma zastosowanie do wszystkich zapytań; równoważne klauzuli WHERE .
  • comment: Opcjonalne. Opis widoku metryki.
  • dimensions: tablica definicji wymiarów, w tym nazwa wymiaru i wyrażenie.
  • measures: tablica kolumn wyrażeń agregujących.

Odwołania do nazw kolumn

W przypadku odwoływania się do nazw kolumn zawierających spacje lub znaki specjalne w wyrażeniach YAML należy ująć nazwę kolumny w backticks, aby uniknąć spacji lub znaku. Jeśli wyrażenie rozpoczyna się od backtick i jest używane bezpośrednio jako wartość YAML, owiń całe wyrażenie w cudzysłowach podwójnych. Prawidłowe wartości YAML nie mogą rozpoczynać się od backtick.

Przykłady formatowania

Skorzystaj z poniższych przykładów, aby dowiedzieć się, jak poprawnie sformatować kod YAML w typowych scenariuszach.

Odwołanie do nazwy kolumny

W poniższej tabeli przedstawiono sposób formatowania nazw kolumn w zależności od znaków, które zawierają.

Przypadek Nazwy kolumn źródłowych Wyrażenia referencyjne Notatki
Brak spacji revenue expr: "revenue"
expr: 'revenue'
expr: revenue		 Użyj cudzysłowów podwójnych, pojedynczych lub bez cudzysłowów wokół nazwy kolumny.
Z spacjami First Name expr: "`First Name`" Użyj backticks, aby uniknąć spacji. Umieść całe wyrażenie w cudzysłowach podwójnych.
Nazwa kolumny z spacjami w wyrażeniu SQL First Name i Last Name expr: CONCAT(`First Name`, , `Last Name`) Jeśli wyrażenie nie zaczyna się od apostrofu, cudzysłowy podwójne nie są konieczne.
Cudzysłowy są uwzględniane w nazwie kolumny źródłowej "name" expr: '`"name"`' Użyj backticksów, aby uniknąć podwójnego cudzysłowu w nazwie kolumny. Ujmij to wyrażenie w pojedynczych cudzysłowach w definicji YAML.

Używanie wyrażeń z dwukropkami

Przypadek Expression Notatki
Wyrażenia z dwukropkami expr: "CASE WHEN Poziom klienta = 'Enterprise: Premium' THEN 1 ELSE 0 END" Ujmij całe wyrażenie w podwójne cudzysłowy dla poprawnej interpretacji

Uwaga / Notatka

YAML interpretuje nieoznakowane dwukropki jako separatory par klucz-wartość. Zawsze używaj podwójnych cudzysłowów wokół wyrażeń zawierających dwukropki.

Wcięcie wielowierszowe

Przypadek Expression Notatki
Wcięcie wielowierszowe expr: \|
CASE WHEN
revenue > 100 THEN 'High'
ELSE 'Low'
END		 Wcięcie wyrażenia pod pierwszym wierszem

Uwaga / Notatka

Użyj skalaru bloku | dla wyrażeń wielowierszowych po expr:. Wszystkie wiersze muszą być wcięte co najmniej dwie spacje poza kluczem expr w celu poprawnego parsowania.

Definiowanie wymiaru

W poniższym przykładzie pokazano, jak zdefiniować wymiary:

dimensions:

  # Column name
  - name: Order date
    expr: o_orderdate

  # SQL expression
  - name: Order month
    expr: DATE_TRUNC('MONTH', `Order date`)

  # Referring to a column with a space in the name
  - name: Month of order
    expr: `Order month`

  # Multi-line expression
  - name: Order status
    expr: CASE
            WHEN o_orderstatus = 'O' THEN 'Open'
            WHEN o_orderstatus = 'P' THEN 'Processing'
            WHEN o_orderstatus = 'F' THEN 'Fulfilled'
          END

Definiowanie miary

W poniższym przykładzie pokazano, jak definiować miary:

measures:

  # Basic aggregation
  - name: Total revenue
    expr: SUM(o_totalprice)

  # Basic aggregation with ratio
  - name: Total revenue per customer
    expr: SUM(`Total revenue`) / COUNT(DISTINCT o_custkey)

  # Measure-level filter
  - name: Total revenue for open orders
    expr: COUNT(o_totalprice) FILTER (WHERE o_orderstatus='O')

  # Measure-level filter with multiple aggregate functions
  # filter needs to be specified for each aggregate function in the expression
  - name: Total revenue per customer for open orders
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus='O')/COUNT(DISTINCT o_custkey) FILTER (WHERE o_orderstatus='O')

Mapowanie nazw kolumn w CREATE VIEW przy użyciu YAML

Podczas tworzenia widoku metryki przy użyciu CREATE VIEW z column_list, system mapuje kolumny zdefiniowane przez YAML (miary i wymiary) na column_list według pozycji, a nie według nazwy.

Jest to zgodne ze standardowym zachowaniem sql, jak pokazano w poniższym przykładzie:

CREATE VIEW v (col1, col2) AS SELECT a, b FROM table;

W tym przykładzie a mapuje na col1, i b mapuje na col2, niezależnie od ich oryginalnych nazw.

Uaktualnianie kodu YAML do wersji 1.1

Uaktualnienie widoku metryki do specyfikacji YAML w wersji 1.1 wymaga ostrożności, ponieważ komentarze są obsługiwane inaczej niż we wcześniejszych wersjach.

Typy komentarzy

  • Komentarze YAML (#): Komentarze wbudowane w jednej linii lub jednowierszowe, napisane bezpośrednio w pliku YAML za pomocą symbolu #.
  • Komentarze Unity Catalog: komentarze przechowywane w Unity Catalog dla widoku metryk lub jego kolumn (wymiary i miary). Są one oddzielone od komentarzy YAML.

Zagadnienia dotyczące uaktualniania

Wybierz metodę uaktualnienia, która odpowiada sposobowi, w jaki chcesz zarządzać komentarzami w widoku metryk. W poniższych opcjach opisano dostępne podejścia i podano przykłady.

Opcja 1. Zachowywanie komentarzy YAML przy użyciu notesów lub edytora SQL

Jeśli widok metryki zawiera komentarze YAML (#), które chcesz zachować, wykonaj następujące kroki:

  1. ALTER VIEW Użyj polecenia w notesie lub edytorze SQL.

  2. Skopiuj oryginalną definicję YAML do sekcji $$..$$ po AS. Zmień wartość wersji na 1.1.

  3. Zapisz widok metryki.

ALTER VIEW metric_view_name AS
$$
# Inline comments are preserved in the notebook
version: 1.1
source: samples.tpch.orders
dimensions:
- name: order_date # Inline comments are preserved in the notebook
  expr: o_orderdate
measures:
# Commented out definition is preserved
# - name: total_orders
#   expr: COUNT(o_orderid)
- name: total_revenue
  expr: SUM(o_totalprice)
$$

Ostrzeżenie

Uruchomienie ALTER VIEW usuwa komentarze Unity Catalog, chyba że są jawnie uwzględnione w comment polach definicji YAML. Jeśli chcesz zachować komentarze wyświetlane w katalogu Unity, zobacz opcję 2.

Opcja 2. Zachowaj komentarze Unity Catalog

Uwaga / Notatka

Poniższe wskazówki mają zastosowanie tylko w przypadku używania ALTER VIEW polecenia w notesie lub edytorze SQL. Jeśli zaktualizujesz widok wskaźników do wersji 1.1 przy użyciu interfejsu użytkownika edytora YAML, komentarze Unity Catalog zostaną zachowane automatycznie.

  1. Skopiuj wszystkie komentarze Unity Catalog do odpowiednich pól w definicji YAML. Zmień wartość wersji na 1.1.

  2. Zapisz widok metryki.

ALTER VIEW metric_view_name AS
$$
version: 1.1
source: samples.tpch.orders
comment: "Metric view of order (Updated comment)"


dimensions:
- name: order_date
  expr: o_orderdate
  comment: "Date of order - Copied from Unity Catalog"


measures:
- name: total_revenue
  expr: SUM(o_totalprice)
  comment: "Total revenue"
$$

Dziennik zmian specyfikacji wersji

Wersja 1.1 (wymaga środowiska Databricks Runtime 17.2 lub nowszego)

Wersja 0.1 (wymaga środowiska Databricks Runtime 16.4 do 17.1)

  • Początkowa wersja specyfikacji YAML widoku metrycznego.
  • Last updated on