Sdílet prostřednictvím

Referenční příručka syntaxe YAML

Definice zobrazení metrik se řídí standardní syntaxí notace YAML. Tato stránka vysvětluje, jak definovat zobrazení metriky.

Další informace o specifikacích YAML najdete v dokumentaci ke specifikaci YAML 1.2.2 .

Přehled YAML

Definice YAML pro zobrazení metrik obsahuje následující pole nejvyšší úrovně:

  • version: Výchozí hodnota 1.1je . Toto je verze specifikace zobrazení metriky. Viz protokol změn specifikace verze.
  • source: Zdrojová data pro zobrazení metrik. Může se jednat o prostředek podobný tabulce nebo dotaz SQL.
  • joins: Volitelné. Jsou podporována spojení hvězdicového schématu a snowflake schématu.
  • filter: Volitelné. Logický výraz SQL, který se vztahuje na všechny dotazy; odpovídající klauzuli WHERE .
  • comment: Volitelné. Popis zobrazení metriky
  • dimensions: Pole definic dimenzí, včetně názvu a výrazu dimenze.
  • measures: Pole sloupců agregačních výrazů.

Odkazy na názvy sloupců

Při odkazování na názvy sloupců, které obsahují mezery nebo speciální znaky ve výrazech YAML, uzavřete název sloupce do zpětných apostrofů, aby se mezera nebo znak eskapoval. Pokud výraz začíná zpětným apostrofem a používá se přímo jako hodnota YAML, uzavřete celý výraz do dvojitých uvozovek. Platné hodnoty YAML nemohou začínat znakem zpětného apostrofu.

Příklady formátování

V následujících příkladech se dozvíte, jak správně formátovat YAML v běžných scénářích.

Odkaz na název sloupce

Následující tabulka ukazuje, jak formátovat názvy sloupců podle znaků, které obsahují.

Případ Názvy zdrojových sloupců Referenční výrazy Poznámky
Žádné mezery revenue expr: "revenue"
expr: 'revenue'
expr: revenue		 U názvu sloupce používejte dvojité uvozovky, jednoduché uvozovky nebo žádné uvozovky.
S mezerami First Name expr: "`First Name`" Použijte zpětné uvozovky k úniku mezer. Uzavřete celý výraz do dvojitých uvozovek.
Název sloupce s mezerami ve výrazu SQL First Name a Last Name expr: CONCAT(`First Name`, , `Last Name`) Pokud výraz nezačíná zpětnými apostrofy, dvojité uvozovky nejsou nutné.
Do názvu zdrojového sloupce jsou zahrnuté uvozovky. "name" expr: '`"name"`' Pomocí zpětných apostrofů unikněte dvojitým uvozovkám v názvu sloupce. Tento výraz uzavřete do jednoduchých uvozovek v definici YAML.

Použití výrazů s dvojtečkami

Případ Expression Poznámky
Výrazy s dvojtečkami expr: "CASE WHEN Zákaznická úroveň = 'Enterprise: Premium' THEN 1 ELSE 0 END" Umístěte celý výraz do dvojitých uvozovek pro správnou interpretaci

Poznámka:

YAML interpretuje necitované dvojtečky jako oddělovače klíč-hodnota. Vždy používejte dvojité uvozovky kolem výrazů, které obsahují dvojtečky.

Odsazení více řádků

Případ Expression Poznámky
Odsazení více řádků expr: \|
CASE WHEN
revenue > 100 THEN 'High'
ELSE 'Low'
END		 Odsadit výraz pod prvním řádkem

Poznámka:

| Pro víceřádkové výrazy použijte skalár bloku zaexpr:. Všechny řádky musí být odsazené aspoň dvě mezery za klíč expr, aby byly správně parsovány.

Definování dimenze

Následující příklad ukazuje, jak definovat dimenze:

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

Definování míry

Následující příklad ukazuje, jak definovat míry:

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

Mapování CREATE VIEW názvů sloupců pomocí YAML

Když vytváříte zobrazení metriky s použitím CREATE VIEW s column_list, systém mapuje sloupce definované v YAML (míry a dimenze) na column_list podle pozice, nikoli podle názvu.

Toto se řídí standardním chováním SQL, jak je znázorněno v následujícím příkladu:

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

V tomto příkladu a se mapují na col1a b mapují na col2, bez ohledu na jejich původní názvy.

Upgrade YAML na verzi 1.1

Aktualizace pohledu metrik na specifikaci YAML verze 1.1 vyžaduje opatrnost, jelikož komentáře se zpracovávají jinak než v předchozích verzích.

Typy komentářů

  • Komentáře YAML (#): Vložené nebo jednořádkové komentáře napsané přímo v souboru YAML pomocí symbolu #.
  • Komentáře k katalogu Unity: Komentáře uložené v katalogu Unity pro zobrazení metrik nebo jeho sloupce (dimenze a míry). Ty jsou oddělené od komentářů YAML.

Důležité informace o upgradu

Zvolte cestu upgradu, která odpovídá způsobu zpracování komentářů v zobrazení metriky. Následující možnosti popisují dostupné přístupy a poskytují příklady.

Možnost 1: Zachování komentářů YAML pomocí poznámkových bloků nebo editoru SQL

Pokud zobrazení metrik obsahuje komentáře YAML (#), které chcete zachovat, postupujte takto:

  1. ALTER VIEW Použijte příkaz v poznámkovém bloku nebo editoru SQL.

  2. Zkopírujte původní definici YAML do $$.. $$ section after AS. Změňte hodnotu verze na 1.1.

  3. Uložte zobrazení metriky.

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

Výstraha

Při spuštění ALTER VIEW se odeberou komentáře katalogu Unity, pokud nejsou explicitně zahrnuty do comment polí definice YAML. Pokud chcete zachovat komentáře zobrazené v katalogu Unity, podívejte se na možnost 2.

Možnost 2: Zachování komentářů katalogu Unity

Poznámka:

Následující pokyny platí jenom při použití ALTER VIEW příkazu v poznámkovém bloku nebo editoru SQL. Pokud upgradujete zobrazení metrik na verzi 1.1 pomocí uživatelského rozhraní editoru YAML, komentáře katalogu Unity se zachovají automaticky.

  1. Zkopírujte všechny komentáře katalogu Unity do příslušných comment polí v definici YAML. Změňte hodnotu verze na 1.1.

  2. Uložte zobrazení metriky.

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

Protokol změn specifikace verze

Verze 1.1 (vyžaduje Databricks Runtime 17.2 nebo novější)

Verze 0.1 (vyžaduje Databricks Runtime 16.4 až 17.1)

  • Počáteční verze specifikace YAML pro zobrazení metrik
  • Last updated on