Naslaginformatie over YAML-syntaxis voor metrische weergave

Op deze pagina wordt de volledige YAML-grammatica voor metrische weergaven uitgelegd. Definities van metrische weergave volgen de standaard syntaxis van YAML-notatie.

Zie beschikbaarheid van metrische weergavefuncties voor minimale runtime- en YAML-specificatieversievereisten voor elke functie.

Zie de documentatie voor YAML-specificatie 1.2.2 voor meer informatie over YAML-specificaties.

OVERZICHT VAN YAML

De YAML-definitie voor een metrische weergave bevat de volgende velden op het hoogste niveau:

bron

In source het veld wordt de gegevensbron voor de metrische weergave opgegeven. U kunt een tabelachtige asset, zoals tabellen, weergaven en metrische weergaven, of een SQL-query als bron gebruiken. Composability is van toepassing op metrische weergaven. Wanneer u een metrische weergave als bron gebruikt, kunt u verwijzen naar de dimensies en metingen in de nieuwe metrische weergave. Zie Composability.

Tabelachtige assetbron

Verwijs naar een tabelachtige asset met behulp van de driedelige naam:

source: catalog.schema.source_table

SQL-querybron

Als u een SQL-query wilt gebruiken, schrijft u de querytekst rechtstreeks in de YAML:

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

Filter

Een filter in de YAML-definitie is van toepassing op alle query's die verwijzen naar de metrische weergave. Schrijf filters als SQL-booleaanse expressies.

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

[Samenvoegingen]

Joins in metrische weergaven ondersteunen zowel directe joins van een feitentabel naar dimensietabellen (stervormig schema) als multihop-joins in genormaliseerde dimensietabellen (snowflake-schema's). U kunt ook deelnemen aan een SQL-query met behulp van een SELECT instructie. Zie Een SQL-query als bron gebruiken.

Elke joindefinitie bevat de volgende velden:

Stervormige schema-joins

In een stervormig schema is de source feitentabel en wordt samengevoegd met een of meer dimensietabellen met behulp van een LEFT OUTER JOIN. Metrische weergaven voegen de feiten- en dimensietabellen toe die nodig zijn voor de specifieke query, op basis van de geselecteerde kolommen.

Kolommen voor joins opgeven met behulp van een ON component of een USING component:

• ON-component: Gebruikt een Boole-expressie om de joinvoorwaarde te definiëren.
• USING-component: bevat kolommen met dezelfde naam in zowel de bovenliggende tabel als de gekoppelde tabel.

De koppeling moet een veel-op-één-relatie volgen. In het geval van veel-op-veel wordt de eerste overeenkomende rij uit de gekoppelde dimensietabel geselecteerd.

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-schema-joins

Een snowflake-schema breidt een stervormig schema uit door dimensietabellen te normaliseren en deze te verbinden met subdimensionale waarden. Hiermee maakt u een joinstructuur met meerdere niveaus. Zie beschikbaarheid van de functie voor metrische gegevens voor minimale runtimevereisten.

Als u een snowflake-schema wilt definiëren, nestt joins u deze in een bovenliggende joindefinitie:

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

Dimensies

Dimensies zijn kolommen die worden gebruikt in SELECT, WHEREen GROUP BY componenten tijdens het uitvoeren van query's. Elke expressie moet een scalaire waarde retourneren. Dimensies kunnen verwijzen naar kolommen uit de brongegevens of eerder gedefinieerde dimensies in de metrische weergave.

Elke dimensiedefinitie bevat de volgende velden:

Voorbeeld:

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

Maatregelen

Metingen zijn expressies die resultaten produceren zonder vooraf bepaald aggregatieniveau. Ze moeten worden uitgedrukt met behulp van statistische functies. Als u wilt verwijzen naar een meting in een query, gebruikt u de MEASURE functie. Metingen kunnen verwijzen naar basisvelden in de brongegevens, eerder gedefinieerde dimensies of eerder gedefinieerde metingen.

Elke metingdefinitie bevat de volgende velden:

Zie Statistische functies voor een lijst met statistische functies.

Voorbeeld:

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

Venstermetingen

Het window veld definieert gevensterde, cumulatieve of semi-aangrenzende aggregaties voor metingen. Zie Venstermetingen voor gedetailleerde informatie over venstermetingen en gebruiksvoorbeelden.

Elke vensterspecificatie bevat de volgende velden:

Voorbeeld van venstermeting

In het volgende voorbeeld wordt een doorlopend aantal unieke klanten van zeven dagen berekend:

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

Materialisatie

Het materialization veld configureert automatische queryversnelling met behulp van gerealiseerde weergaven. Zie Materialisatie voor metrische weergaven voor gedetailleerde informatie over hoe materialisatie werkt, vereisten en best practices.

Het materialization veld bevat de volgende velden op het hoogste niveau:

Elke vermelding bevat materialized_views de volgende velden:

Voorbeeld van materialisatie

In het volgende voorbeeld wordt een metrische weergave met meerdere materialisaties gedefinieerd:

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

Kolomnaamverwijzingen

Wanneer u verwijst naar kolomnamen die spaties of speciale tekens in YAML-expressies bevatten, plaatst u de kolomnaam in backticks om te ontsnappen aan de spatie of het teken. Als de expressie begint met een backtick en rechtstreeks als YAML-waarde wordt gebruikt, plaatst u de hele expressie tussen dubbele aanhalingstekens. Geldige YAML-waarden kunnen niet beginnen met een backtick.

Voorbeelden van opmaak

Gebruik de volgende voorbeelden voor meer informatie over het correct opmaken van YAML in veelvoorkomende scenario's.

Verwijzen naar een kolomnaam

In de volgende tabel ziet u hoe u kolomnamen opmaken, afhankelijk van de tekens die ze bevatten.

Expressies gebruiken met dubbele punten

Inspringing met meerdere regels

Uw YAML upgraden naar 1.1

Voor het upgraden van een metrische weergave naar YAML-specificatieversie 1.1 is het belangrijk dat opmerkingen anders worden verwerkt dan in eerdere versies.

Typen opmerkingen

• YAML-opmerkingen (#): inline- of regelopmerkingen die rechtstreeks in het YAML-bestand zijn geschreven met behulp van het #-symbool.
• Opmerkingen bij Unity Catalog: Opmerkingen die zijn opgeslagen in Unity Catalog voor de metrische weergave of de bijbehorende kolommen (dimensies en metingen). Deze zijn gescheiden van YAML-opmerkingen.

Overwegingen bij de upgrade

Kies het upgradepad dat overeenkomt met de manier waarop u opmerkingen in de metrische weergave wilt verwerken. De volgende opties beschrijven de beschikbare benaderingen en bieden voorbeelden.

Optie 1: YAML-opmerkingen behouden met behulp van notebooks of de SQL-editor

Als uw metrische weergave YAML-opmerkingen (#) bevat die u wilt behouden, gebruikt u de volgende stappen:

1. Gebruik de ALTER VIEW opdracht in een notebook of SQL-editor.
2. Kopieer de oorspronkelijke YAML-definitie naar de $$..$$ sectie na AS. Wijzig de waarde van version in 1.1.
3. Sla de metrische weergave op.

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

Optie 2: Opmerkingen bij Unity Catalog behouden

1. Kopieer alle Unity Catalog-opmerkingen naar de juiste comment velden in uw YAML-definitie. Wijzig de waarde van version in 1.1.
2. Sla de metrische weergave op.

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

Zie voor versiegeschiedenis van YAML-specificatie en minimale runtimevereisten voor elke functie de beschikbaarheid van metrische weergavefuncties.