Yaml-syntaxreferens för måttvy

Den här sidan förklarar den fullständiga YAML-grammatiken för måttvyer. Måttvydefinitioner följer yaml-standardsyntaxen för notering.

Lägsta versionskrav för körning och YAML-specifikation för varje funktion finns i Tillgänglighet för måttvyfunktioner.

Mer information om YAML-specifikationer finns i dokumentationen för YAML Specification 1.2.2 .

YAML-översikt

YAML-definitionen för en måttvy innehåller följande fält på den översta nivån:

Källa

Fältet source anger datakällan för måttvyn. Du kan använda en tabellliknande tillgång, till exempel tabeller, vyer och måttvyer, eller en SQL-fråga som källa. Sammansättning gäller för olika måttvyer. När du använder en måttvy som källa kan du referera till dess dimensioner och mått i den nya måttvyn. Se Komponerbarhet.

Tabellliknande tillgångskälla

Referera till en tabellliknande tillgång med dess tredelade namn:

source: catalog.schema.source_table

SQL-frågekälla

Om du vill använda en SQL-fråga skriver du frågetexten direkt i YAML:

source: SELECT * FROM samples.tpch.orders o
  LEFT JOIN samples.tpch.customer c
  ON o.o_custkey = c.c_custkey

Filter

Ett filter i YAML-definitionen gäller för alla frågor som refererar till måttvyn. Skriv filter som booleska SQL-uttryck.

# Single condition filter
filter: o_orderdate > '2024-01-01'

# Multiple conditions with AND
filter: o_orderdate > '2024-01-01' AND o_orderstatus = 'F'

# Multiple conditions with OR
filter: o_orderpriority = '1-URGENT' OR o_orderpriority = '2-HIGH'

# Complex filter with IN clause
filter: o_orderstatus IN ('F', 'P') AND o_orderdate >= '2024-01-01'

# Filter with NOT
filter: o_orderstatus != 'O' AND o_totalprice > 1000.00

# Filter with LIKE pattern matching
filter: o_comment LIKE '%express%' AND o_orderdate > '2024-01-01'

Ansluter sig

Kopplingar i måttvyer stöder både direktkopplingar från en faktatabell till dimensionstabeller (stjärnschema) och flerhoppskopplingar mellan normaliserade dimensionstabeller (snowflake-scheman). Du kan också ansluta till en SQL-fråga med hjälp av en SELECT -instruktion. Se Använda en SQL-fråga som källa.

Varje kopplingsdefinition innehåller följande fält:

Star-schemakopplingar

I ett stjärnschema är source faktatabellen, som kopplas till en eller flera dimensionstabeller med hjälp av en LEFT OUTER JOIN. Måttvyer kopplar ihop de fakta- och dimensionstabeller som behövs för den specifika frågan, baserat på de valda kolumnerna.

Ange kopplingskolumner med antingen en ON sats eller en USING sats:

• ON-sats: Använder ett booleskt uttryck för att definiera kopplingsvillkoret.
• USING-sats: Visar kolumner med samma namn i både den överordnade tabellen och den anslutna tabellen.

Sammanfogningen bör följa en många-till-en-relation. I fall av många-till-många väljs den första matchande raden från den anslutna dimensionstabellen.

version: 1.1
source: samples.tpch.lineitem

joins:
  - name: orders
    source: samples.tpch.orders
    on: source.l_orderkey = orders.o_orderkey

  - name: part
    source: samples.tpch.part
    on: source.l_partkey = part.p_partkey

dimensions:
  - name: Order Status
    expr: orders.o_orderstatus

  - name: Part Name
    expr: part.p_name

measures:
  - name: Total Revenue
    expr: SUM(l_extendedprice * (1 - l_discount))

  - name: Line Item Count
    expr: COUNT(1)

Snowflake-schemaanslutningar

Ett snowflake-schema utökar ett star-schema genom att normalisera dimensionstabeller och ansluta dem till underdimensioner. Detta skapar en kopplingsstruktur på flera nivåer. Se Tillgänglighet för måttvyfunktioner för lägsta körningskrav.

Om du vill definiera ett snowflake-schema kapslas joins du i en överordnad kopplingsdefinition:

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    'on': o_custkey = c_custkey
    joins:
      - name: nation
        source: samples.tpch.nation
        'on': c_nationkey = n_nationkey

dimensions:
  - name: customer_nation
    expr: customer.nation.n_name

Mått

Dimensioner är kolumner som används i SELECT, WHERE och GROUP BY-villkor vid frågetillfället. Varje uttryck måste returnera ett skalärt värde. Dimensioner kan referera till kolumner från källdata eller tidigare definierade dimensioner i måttvyn.

Varje dimensionsdefinition innehåller följande fält:

Exempel:

dimensions:
  # Basic dimension
  - name: order_date
    expr: o_orderdate
    comment: 'Date the order was placed'
    display_name: 'Order Date'

  # Dimension with SQL expression
  - name: order_month
    expr: DATE_TRUNC('MONTH', o_orderdate)
    display_name: 'Order Month'

  # Dimension with synonyms
  - name: order_status
    expr: CASE
      WHEN o_orderstatus = 'O' THEN 'Open'
      WHEN o_orderstatus = 'P' THEN 'Processing'
      WHEN o_orderstatus = 'F' THEN 'Fulfilled'
      END
    display_name: 'Order Status'
    synonyms: ['status', 'fulfillment status']

Åtgärder

Mått är uttryck som ger resultat utan en fördefinierad aggregeringsnivå. De måste uttryckas med hjälp av aggregerade funktioner. Om du vill referera till ett mått i en fråga använder du MEASURE funktionen. Mått kan referera till basfält i källdata, tidigare definierade dimensioner eller tidigare definierade mått.

Varje måttdefinition innehåller följande fält:

Se Mängdfunktioner för en lista över aggregerade funktioner.

Exempel:

measures:
  # Simple count measure
  - name: order_count
    expr: COUNT(1)
    display_name: 'Order Count'

  # Sum aggregation measure with synonyms
  - name: total_revenue
    expr: SUM(o_totalprice)
    comment: 'Gross revenue from all orders'
    display_name: 'Total Revenue'
    synonyms: ['revenue', 'total sales']

  # Distinct count measure
  - name: unique_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: 'Unique Customers'

  # Calculated measure combining multiple aggregations
  - name: avg_order_value
    expr: SUM(o_totalprice) / COUNT(DISTINCT o_orderkey)
    display_name: 'Avg Order Value'
    synonyms: ['AOV', 'average order']

  # Filtered measure with WHERE condition
  - name: open_order_revenue
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus = 'O')
    display_name: 'Open Order Revenue'
    synonyms: ['backlog', 'outstanding revenue']

Fönstermått

Fältet window definierar fönster, kumulativa eller halvaddiiva aggregeringar för mått. Detaljerad information om fönstermått och användningsfall finns i Fönstermått.

Varje fönsterspecifikation innehåller följande fält:

Exempel på fönstermått

I följande exempel beräknas ett rullande 7-dagars antal unika kunder:

version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate

measures:
  - name: rolling_7day_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: '7-Day Rolling Customers'
    window:
      - order: order_date
        range: trailing 7 day
        semiadditive: last

Materialisering

Fältet materialization konfigurerar automatisk frågeacceleration med materialiserade vyer. Detaljerad information om hur materialisering fungerar, krav och metodtips finns i Materialisering för måttvyer.

Fältet materialization innehåller följande fält på den översta nivån:

Varje post i materialized_views innehåller följande fält:

Materialiseringsexempel

I följande exempel definieras en måttvy med flera materialiseringar:

version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate
  - name: order_status
    expr: o_orderstatus

measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
  - name: order_count
    expr: COUNT(1)

materialization:
  schedule: every 6 hours
  mode: relaxed
  materialized_views:
    - name: baseline
      type: unaggregated

    - name: daily_status_metrics
      type: aggregated
      dimensions:
        - order_date
        - order_status
      measures:
        - total_revenue
        - order_count

Referenser till kolumnnamn

När du refererar till kolumnnamn som innehåller blanksteg eller specialtecken i YAML-uttryck, omslut kolumnnamnet med backticks för att exkludera blanksteget eller tecknet. Om uttrycket börjar med en backtick och används direkt som ett YAML-värde omsluter du hela uttrycket med dubbla citattecken. Giltiga YAML-värden kan inte börja med en backtick.

Formateringsexempel

Använd följande exempel för att lära dig hur du formaterar YAML korrekt i vanliga scenarier.

Referera till ett kolumnnamn

I följande tabell visas hur du formaterar kolumnnamn beroende på vilka tecken de innehåller.

Använda uttryck med kolon

Indrag med flera rader

Uppgradera din YAML till 1.1

Uppgradering av en måttvy till YAML-specifikation version 1.1 kräver försiktighet, eftersom kommentarer hanteras på ett annat sätt än i tidigare versioner.

Typer av kommentarer

• YAML-kommentarer (#): Infogade eller enradskommentarer som skrivits direkt i YAML-filen med hjälp av #-symbolen.
• Unity Catalog-kommentarer: Kommentarer som lagras i Unity Catalog för måttvyn eller dess kolumner (dimensioner och mått). Dessa är separata från YAML-kommentarer.

Uppgraderingsöverväganden

Välj den uppgraderingsväg som matchar hur du vill hantera kommentarer i din måttvy. Följande alternativ beskriver de tillgängliga metoderna och ger exempel.

Alternativ 1: Bevara YAML-kommentarer med hjälp av notebook-filer eller SQL-redigeraren

Om din måttvy innehåller YAML-kommentarer (#) som du vill behålla använder du följande steg:

1. ALTER VIEW Använd kommandot i en notebook- eller SQL-redigerare.
2. Kopiera den ursprungliga YAML-definitionen till avsnittet $$..$$ efter AS. Ändra värdet version för till 1.1.
3. Spara måttvyn.

ALTER VIEW metric_view_name AS
$$
# The notebook preserves inline comments
version: 1.1
source: samples.tpch.orders
dimensions:
- name: order_date # The notebook preserves inline comments
  expr: o_orderdate
measures:
# The notebook preserves commented out definitions
# - name: total_orders
#   expr: COUNT(o_orderid)
- name: total_revenue
  expr: SUM(o_totalprice)
$$

Alternativ 2: Bevara kommentarer i Unity-katalogen

1. Kopiera alla Unity Catalog-kommentarer till lämpliga comment fält i YAML-definitionen. Ändra värdet version för till 1.1.
2. Spara måttvyn.

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

För YAML-specifikationsversionshistorik och lägsta körningskrav för varje funktion, se Tillgänglighet för måttvyfunktioner.