Yaml-syntaxreferens för måttvy

Måttvydefinitioner använder YAML-standardsyntax för att deklarera källan, kopplingar, fält, mått, filter, fönstermått och materialisering. Följande avsnitt dokumenterar den fullständiga grammatiken för var och en.

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 .

Redigera YAML i redigeringsprogrammet för måttvyn

Du kan skriva och redigera YAML som beskrivs på den här sidan direkt i redigeringsprogrammet för måttvyn. Öppna en måttvy i Katalogutforskaren <> och klicka på knappen för att redigera definitionen. Om du vill generera YAML från en beskrivning av naturligt språk i stället öppnar du Genie Code från redigeraren. En fullständig genomgång av redigeraren finns i Skapa en måttvy.

YAML-fält på översta nivån

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. Källor som stöds är tabeller, vyer, måttvyer och SQL-frågor. 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 fält 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

Parameterar

Blocket parameters definierar namngivna värden som anropare skickar när de kör frågor mot måttvyn som en tabellvärdesfunktion. Information om när och hur du använder parametrar, inklusive att köra frågor mot en parameteriserad måttvy, finns i Använda parametrar med måttvyer.

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

I följande exempel definieras en discount parameter och den refereras till i ett måttuttryck:

version: 1.1
source: main.default.sales

parameters:
  - name: discount
    data_type: double
    default: 0

fields:
  - name: product
    expr: product

measures:
  - name: discountedSales
    expr: SUM((1 - discount) * amount)

Filtrera

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'

Joins

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.

Kopplingen måste 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

fields:
  - 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

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

En-till-många-kopplingar

Fältet cardinality anger relationen mellan källan och en ansluten tabell. Standardvärdet, many_to_one, behandlar den anslutna tabellen som en dimensionssökning. Ange cardinality: one_to_many för att behandla den anslutna tabellen som en faktakälla som motorn aggregerar oberoende av vid källintervallet, vilket gör att en enda källrad matchar flera rader i den anslutna tabellen. En-till-många-kopplingar kräver Databricks Runtime 18.1 eller senare och YAML-specifikation version 1.1. Se Tillgänglighet för måttvyfunktioner.

Följande regler gäller för en-till-många-kopplingar:

• En en-till-många-kolumn kan inte användas i en fields definition, eftersom ett fält måste matcha till ett enda värde per källrad.
• En enskild aggregeringsfunktion måste referera till kolumner från en källa. Du kan använda aritmetik i resultatet av separata aggregeringar, till exempel count(orders.order_id) / count(*).
• Alla underordnade till en en-till-många-koppling måste också vara one_to_many. Syskonkopplingar på toppnivå kan blanda kardinaliteter.
• Referera till en kolumn i en kapslad koppling med dess fullständiga punktsökväg genom kopplingsnamnen, till exempel orders.order_items.item_id.

Följande exempel ansluter orders till en customers källa med cardinality: one_to_many så att ordermått aggregeras utan att duplicera kundrader:

version: 1.1
source: main.sales.customers

joins:
  - name: orders
    source: main.sales.orders
    on: orders.customer_id = source.customer_id
    cardinality: one_to_many

fields:
  - name: customer_name
    expr: customer_name

measures:
  - name: customer_count
    expr: count(*)
  - name: order_count
    expr: count(orders.order_id)
  - name: total_order_revenue
    expr: sum(orders.amount)

Konceptuell information och kapslade och syskonkopplingsexempel finns i Koppla kardinalitet.

Optimera kopplingar med rely

Använd fältet rely på en koppling för att deklarera garantier om relationen som frågeanalysatorn använder vid planering av frågor. Dessa garantier gör det möjligt för motorn att planera frågor mer effektivt och minska genomsökt data, särskilt när fält från den anslutna tabellen refereras i filter.

Kartan rely stöder följande fält:

I följande exempel aktiveras at_most_one_match en många-till-en-koppling från orders till customer. Frågor som filtrerar eller grupperar efter kundattribut har störst fördelar:

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey
    rely:
      at_most_one_match: true

fields:
  - name: Customer name
    expr: customer.c_name
  - name: Customer market segment
    expr: customer.c_mktsegment

measures:
  - name: Total revenue
    expr: SUM(o_totalprice)

Fält

Fält är måttvykolumner som används i SELECT, WHEREoch GROUP BY -satser vid frågetillfället. Varje uttryck måste returnera ett skalärt värde. Fält kan referera till kolumner från källdata eller tidigare definierade fält i måttvyn.

Ett fält kan vara antingen:

• En kategorisk kolumn eller grupperingskolumn, till exempel en region, status eller avdelning.
• En oaggregerad numerisk kolumn, till exempel en ålder, ett pris eller en kvantitet. Numeriska fält kan aggregeras vid frågetillfället med hjälp av SQL-funktioner som SUM eller AVG.

Varje fältdefinition innehåller följande egenskaper:

Example:

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

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

  # Field 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 baskolumner i källdata, tidigare definierade fält eller tidigare definierade mått.

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

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

Example:

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

Massimportera fält och mått med jokertecken

Gäller för: Databricks Runtime 18.2 och senare med YAML-specifikation 1.1

I en fields eller measures -definition kan du använda ett jokertecken (*) i expr fältet för att importera alla kolumner från källan eller en ansluten tabell utan att visa var och en. Det här är användbart när du vill att en måttvy ska exponera varje kolumn från en överordnad tillgång, ungefär som SELECT * i en standardvy. Azure Databricks expanderar jokertecknet till konkreta kolumner när du skapar eller ersätter måttvyn och härleder varje kolumnnamn från källkolumnnamnet.

Precis som explicita kolumndefinitioner expanderas jokerteckenuttryck när du skapar måttvyn. Om du vill hämta kolumner som lagts till i källan senare återskapar du måttvyn med CREATE OR REPLACE eller ALTER.

Jokertecken stöder följande formulär:

Följande regler gäller för jokerteckenuttryck:

• Utelämna fältet name . Azure Databricks härleder kolumnnamn från källan, så name tillåts inte i ett jokerteckenuttryck.
• Semantiska metadata tillåts inte i ett jokerteckenuttryck. Ange inte comment, display_name, formateller synonyms på ett jokertecken. Om du vill lägga till metadata i en specifik kolumn exkluderar du det från jokertecknet med EXCEPT och definierar det explicit.
• I en measures definition importerar ett jokertecken endast mått från en måttvykälla. Bastabeller har inga mått, så ett jokertecken expanderas till inga mått när källan är en bastabell.
• Du kan inte referera till en jokerteckenimporterad kolumn med dess härledda namn i ett senare fields uttryck eller measures uttryck. Referera till källkolumnen med dess fullständiga sökväg i stället.

Lösa namnkollisioner

När du importerar kolumner från mer än en källa med ett jokertecken, kolliderar kolumner som delar ett namn (till exempel id eller date) och orsakar ett fel när du sparar definitionen. Lös en kollision genom att exkludera kolumnen från varje jokertecken med EXCEPToch definiera den explicit med ett unikt namn:

fields:
  - expr: source.* EXCEPT (id)
  - expr: customer.* EXCEPT (id)
  - name: source_id
    expr: source.id
  - name: customer_id
    expr: customer.id

Jokerteckenexempel

Följande definition importerar alla kolumner från källan och från en ansluten tabell, exkluderar två kolumner och definierar en kolumn explicit för att lägga till metadata:

version: 1.1
source: samples.tpch.orders

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

fields:
  # Import all columns from the source
  - expr: source.*

  # Import all columns from a joined table, excluding two
  - expr: customer.nation.* EXCEPT (n_name, n_comment)

  # Define a specific column explicitly to add metadata
  - name: nation_name
    expr: customer.nation.n_name
    comment: "Customer's nation"
    display_name: 'Nation Name'

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:

(1) Det refererade fältet måste vara deterministiskt. Icke-deterministiska uttryck som rand(), uuid()eller current_timestamp() skapar oförutsägbar fönsterordning och kan leda till felaktiga aggregeringsresultat.

range värden som stöds

• current: Rader där fönsterordningsvärdet är lika med ankarradens värde.
• cumulative: Alla rader där fönsterordningsvärdet är mindre än eller lika med ankarradens värde.
• trailing <value> <unit> [inclusive | exclusive]: Rader från fästpunktsraden som går bakåt med angivna tidsenheter, till exempel trailing 7 day. Den valfria inclusive eller exclusive modifieraren kräver Databricks Runtime 18.1 och YAML-specifikation version 1.1 eller senare, och styr om fästpunktsraden ingår i fönstret. Standardvärdet är exclusive. Se Inkludera eller exkludera fästpunktsraden.
• leading <value> <unit> [inclusive | exclusive]: Rader från fästpunktsraden framöver med angivna tidsenheter, till exempel leading 3 month. Den valfria inclusive eller exclusive modifieraren kräver Databricks Runtime 18.1 och YAML-specifikation version 1.1 eller senare, och styr om fästpunktsraden ingår i fönstret. Standardvärdet är exclusive. Se Inkludera eller exkludera fästpunktsraden.
• all: Alla rader oavsett fönsterordningsvärdet.

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

fields:
  - 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

Skicka en fönsterstorlek som parameter

Istället för att hårdkoda det numeriska värdet i ett trailing eller eller leadingrange i ett offset, kan du referera till en parameter, så att en anropare skickar in fönsterstorleken när de frågar i metrikvyn. Detta kräver ett SQL-lager eller annan beräkningsresurs som kör Databricks Runtime 18.2 eller högre.

Följande regler gäller för en parameter som används som fönsterstorlek:

• Parametrarna data_type måste vara integrala, såsom int, smallint, eller bigint.
• Värdet måste vara ett rent parameternamn, inte ett uttryck. Använd till exempel trailing window_size day, inte trailing window_size + 1 day. Du kan inte heller skriva ett tecken före parameternamnet, till exempel -window_size i en offset. För att passera en negativ offset, placera tecknet inuti parameterns värde.
• Parametern kan inte namnges efter ett fönsternyckelord, såsom en intervalltyp (trailing, , leading), en punkt (day, month, ), yearett inkluderingsnyckelord (inclusive, exclusive), eller offset.
• Enheten förblir bokstavlig. Du kan parametrisera endast den numeriska magnituden, inte perioden.

Följande exempel definierar en window_size parameter och refererar till den i ett trailing intervall, så varje anropare väljer antalet dagar i det rullande fönstret:

version: 1.1
source: samples.tpch.orders

parameters:
  - name: window_size
    data_type: int
    default: 7

fields:
  - name: order_date
    expr: o_orderdate

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

För att fråga en metrikvy som definierar parametrar, se Fråga en metrikvy med parametrar.

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: prod.operations.orders_enriched_view
filter: revenue > 0
# filter, fields, and measures can't use invoker-dependent expressions: no current_user(), is_member(), etc.
# source can't have RLS, column masking, or ABAC policies

joins:
  - name: customers
    source: prod.operations.customers
    on: source.customer_id = customers.id
    # if one-to-many, all materializations below drop to exact match only

fields:
  - name: category
    expr: substring(category, 5)
  - name: order_date
    expr: order_date

measures:
  - name: total_revenue
    expr: SUM(revenue)

  - name: number_of_suppliers
    expr: COUNT(DISTINCT supplier_id)

  - name: revenue_for_open_orders
    expr: SUM(revenue) FILTER (WHERE status = 'O')

  - name: blended_margin
    expr: SUM(revenue) - SUM(cost)

  - name: rolling_7day_customers
    expr: COUNT(DISTINCT customer_id)
    window:
      - order: order_date
        range: trailing 7 day
        semiadditive: last

materialization:
  schedule: every 6 hours
  mode: relaxed

  materialized_views:
    - name: baseline
      type: unaggregated
      # only one allowed per metric view; doesn't use dimensions or measures keys
      # no benefit if source is an unfiltered direct table reference

    - name: daily_status_metrics
      type: aggregated
      dimensions:
        - order_date
        - category # avoid overly granular dimensions, such as millisecond timestamps
      measures:
        - total_revenue # rollup-eligible
        - number_of_suppliers # exact match only (non-additive)
        - revenue_for_open_orders # rollup-eligible (deterministic filter)
        - blended_margin # exact match only (multiple aggregates)
        - rolling_7day_customers # exact match only (window measure)
      cluster_by:
        cols:
          - order_date
          - category
      partition_by:
        - order_date

Referenser till kolumnnamn

När du refererar till kolumnnamn som innehåller blanksteg eller specialtecken i YAML-uttryck omger du kolumnnamnet i backticks. 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 exempel visas hur du formaterar kolumnreferenser beroende på vilka tecken de innehåller.

Inga blanksteg

Källkolumn: revenue

expr: "revenue"
expr: 'revenue'
expr: revenue

Använd dubbla citattecken, enkla citattecken eller inga citattecken runt kolumnnamnet.

Kolumnnamn med blanksteg

Källkolumn: `First Name`

expr: '`First Name`'

Använd backticks för att undkomma mellanslag. Omslut hela uttrycket med dubbla citattecken.

Kolumnnamn med blanksteg i ett SQL-uttryck

Källkolumner: `First Name`, `Last Name`

expr: CONCAT(`First Name`, ' ', `Last Name`)

Om uttrycket inte börjar med en backtick krävs inte dubbla citattecken.

Kolumnnamn som innehåller citattecken

Källkolumn: "name"

expr: '`"name"`'

Använd backticks för att undvika de dubbla citattecknarna i kolumnnamnet. Omslut uttrycket med enkla citattecken.

Uttryck med kolon

expr: "CASE WHEN `Customer Tier` = 'Enterprise: Premium' THEN 1 ELSE 0 END"

Flerradsuttryck

expr: |
  CASE WHEN
    revenue > 100 THEN 'High'
  ELSE 'Low'
  END

Uppgradera till YAML 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.
• Unity Catalog-kommentarer: Kommentarer som lagras i Unity Catalog för måttvyn eller dess kolumner. Dessa är separata från YAML-kommentarer.

Uppgraderingsöverväganden

Välj den uppgraderingssökväg som matchar hur du vill hantera kommentarer i din måttvy.

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 på version 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
fields:
- 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 på version 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)"

fields:
- 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.