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ą.

Używanie wyrażeń z dwukropkami

Wcięcie wielowierszowe

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)
$$

Opcja 2. Zachowaj komentarze Unity Catalog

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)

• Dodano:
  • Obsługa funkcji metadanych semantycznych. Zobacz Używanie metadanych semantycznych w widokach metryk.
  • Obsługa opcjonalnego pola YAML comment w celu opisania widoku metryk, wymiarów lub miar.

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

• Początkowa wersja specyfikacji YAML widoku metrycznego.