Naslaginformatie over YAML-syntaxis voor metrische weergave

Definities van metrische weergave gebruiken standaard YAML-syntaxis om de bron te declareren, samenvoegingen, velden, metingen, filters, venstermetingen en materialisatie. In de volgende secties wordt de volledige grammatica voor elk document beschreven.

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.

YAML bewerken in de editor voor de metrische weergave

U kunt de YAML die op deze pagina wordt beschreven, rechtstreeks in de editor voor de metrische weergave schrijven en bewerken. Open in Catalog Explorer een metrische weergave en klik op de <> knop om de definitie te bewerken. Als u YAML wilt genereren op basis van een beschrijving in natuurlijke taal, opent u Genie Code vanuit de editor. Zie Een metrische weergave maken voor de volledige editor.

YAML-velden op het hoogste niveau

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

Veld	Type	Description
version	String	Required. De versie van de YAML-specificatie van de metrische weergave die door de definitie wordt gebruikt, zoals 1.1. Dit is de versie van de specificatieindeling, niet een revisienummer dat u aan uw eigen definitie toewijst. Gebruik een van de ondersteunde specificatieversies. Zie versies van YAML-specificatie.
comment	String	Optional. Beschrijving van de metrische weergave.
source	String	Required. De brongegevens voor de metrische weergave. Dit kan elke tabelachtige Unity Catalog-asset zijn, inclusief een metrische weergave of een SQL-query. Zie bron.
parameters	Array	Optional. Benoemde waarden die bellers doorgeven wanneer ze een query uitvoeren op de metrische weergave als een tabelwaardefunctie. Zie Parameters.
filter	String	Optional. Een Booleaanse SQL-expressie die van toepassing is op alle query's. Zie Filter.
joins	Array	Optional. Stervormig schema en snowflake schema joins. Zie Joins.
fields	Array	Voorwaardelijk. Velddefinities, waaronder naam, expressie en optionele semantische metagegevens. Vereist als er geen measures zijn opgegeven. Zie Velden. Het dimensions trefwoord wordt geaccepteerd als synoniem voor achterwaartse compatibiliteit.
measures	Array	Voorwaardelijk. Metingdefinities, waaronder naam, aggregatie-expressie en optionele semantische metagegevens. Vereist als er geen fields zijn opgegeven. Zie Metingen.
materialization	Object	Optional. Configuratie voor het versnellen van query's met gerealiseerde weergaven. Bevat vernieuwingsschema's en gerealiseerde weergavedefinities. Zie Materialisatie.

Bron

In source het veld wordt de gegevensbron voor de metrische weergave opgegeven. Ondersteunde bronnen zijn tabellen, weergaven, metrische weergaven en SQL-query's. Composability is van toepassing op metrische weergaven. Wanneer u een metrische weergave als bron gebruikt, kunt u verwijzen naar de velden 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

Note

Wanneer u een SQL-query als bron gebruikt met een JOIN component, stelt u beperkingen voor primaire en refererende sleutels in voor onderliggende tabellen en gebruikt u de RELY optie voor optimale queryprestaties. Zie Primaire sleutel, refererende sleutel en unieke beperkingen declareren enQueryoptimalisatie met behulp van primaire sleutel en unieke beperkingen voor meer informatie.

Parameters

Het parameters blok definieert benoemde waarden die bellers doorgeven wanneer ze een query uitvoeren op de metrische weergave als een tabelwaardefunctie. Zie Parameters gebruiken met metrische weergaven voor wanneer en hoe u parameters gebruikt, waaronder het uitvoeren van query's op een geparameteriseerde metrische weergave.

Elke parameterdefinitie bevat de volgende velden:

Veld	Type	Description
name	String	Required. De parameternaam. Verwijs naar de parameter met deze naam in veld- en metingexpressies en geef deze door als een benoemd argument wanneer u een query uitvoert op de metrische weergave.
data_type	String	Required. Het SQL-gegevenstype van de parameter, zoals double, intof stringdate.
default	Varies	Optional. De waarde die wordt gebruikt wanneer een aanroeper de parameter niet doorgeeft. De standaardwaarde moet worden geconverteerd naar data_typeen kan niet verwijzen naar een andere parameter of een subquery bevatten. Als u een standaardwaarde instelt voor één parameter, moet elke volgende parameter ook een standaardwaarde hebben.

In het volgende voorbeeld wordt een discount parameter gedefinieerd en ernaar verwezen in een metingexpressie:

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)

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'

Joins

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.

Note

Gekoppelde tabellen kunnen geen typekolommen bevatten MAP . Zie MAP om waarden uit typekolommen uit te pakken.

Elke joindefinitie bevat de volgende velden:

Veld	Type	Description
name	String	Required. Alias voor de gekoppelde tabel of SQL-query. Gebruik deze alias wanneer u verwijst naar kolommen uit de gekoppelde tabel in velden of metingen.
source	String	Required. Driedelige naam van de tabel die moet worden samengevoegd. Kan ook een SQL-query zijn.
on	String	Voorwaardelijk. Booleaanse expressie die de joinvoorwaarde definieert. Vereist wanneer using niet is opgegeven.
using	Array	Voorwaardelijk. Lijst met kolomnamen die aanwezig zijn in zowel de bovenliggende tabel als de gekoppelde tabel. Vereist wanneer on niet is opgegeven.
cardinality	String	Optional. Wordt standaard ingesteld op many_to_one. De relatie tussen de bron en de gekoppelde tabel. Ingesteld op one_to_many het aggregeren van een tabel met meerdere overeenkomende rijen per bronrij als een afzonderlijke feitenbron. Bekijk een-op-veel-joins.
joins	Array	Optional. Een lijst met geneste joindefinities voor het modelleren van snowflake-schema's. Zie beschikbaarheid van de functie voor metrische gegevens voor minimale runtimevereisten.
rely	Toewijzen	Optional. Belooft de join waarop de analyzer kan vertrouwen om efficiëntere queryplannen te produceren. Zie Joins optimaliseren met rely.

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: Maakt gebruik van een Booleaanse expressie om de joinvoorwaarde te definiëren.
• USING component: Bevat kolommen met dezelfde naam in zowel de bovenliggende tabel als de gekoppelde tabel.

De join moet gebaseerd zijn op een many-to-one-relatie. 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

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)

Note

De source naamruimte verwijst naar kolommen uit de bron van de metrische weergave, terwijl een join name verwijst naar kolommen uit die gekoppelde tabel. In , source.l_orderkey = orders.o_orderkeysource verwijst bijvoorbeeld naar lineitem en orders verwijst naar de gekoppelde tabel. Als er geen voorvoegsel wordt opgegeven in een on component, wordt de verwijzing standaard ingesteld op de gekoppelde tabel.

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

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

Een-op-veel-joins

In cardinality het veld wordt de relatie tussen de bron en een gekoppelde tabel ingesteld. De standaardinstelling, many_to_onebehandelt de gekoppelde tabel als een dimensiezoekactie. Ingesteld cardinality: one_to_many om de gekoppelde tabel te behandelen als een feitenbron die de engine onafhankelijk samenvoegt op het broninterval, zodat één bronrij overeenkomt met meerdere rijen in de gekoppelde tabel. Voor een-op-veel-joins is Databricks Runtime 18.1 of hoger en YAML-specificatieversie 1.1 vereist. Bekijk de beschikbaarheid van functies in de metrische weergave.

De volgende regels zijn van toepassing op een-op-veel-joins:

• Een een-op-veel-kolom kan niet worden gebruikt in een fields definitie, omdat een veld moet worden omgezet in één waarde per bronrij.
• Eén aggregatiefunctie moet verwijzen naar kolommen uit één bron. U kunt rekenkundige bewerkingen toepassen op de resultaten van afzonderlijke aggregaties, zoals count(orders.order_id) / count(*).
• Alle afstammelingen van een een-op-veel-join moeten ook zijn one_to_many. Joins op het hoogste niveau kunnen kardinaliteiten combineren.
• Verwijs naar een kolom in een geneste join met het volledige puntpad via de joinnamen, zoals orders.order_items.item_id.

Note

Wanneer een metrische weergave gebruikmaakt van een one_to_many join, komen de materialisaties alleen in aanmerking voor exacte overeenkomst. Samengevouwen overeenkomst is niet beschikbaar. Zie Samengevouwen overeenkomst.

Het volgende voorbeeld wordt samengevoegd orders met een customers bron, cardinality: one_to_many zodat ordermetingen aggregeren zonder klantrijen te dupliceren:

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)

Zie Join-kardinaliteit voor conceptuele details en geneste en gekoppelde joinvoorbeelden.

Joins optimaliseren met rely

Gebruik het rely veld op een join om garanties te declareren over de relatie die de queryanalyse gebruikt bij het plannen van query's. Met deze garanties kan de engine query's efficiënter plannen en de gescande gegevens verminderen, met name wanneer velden uit de gekoppelde tabel worden verwezen in filters.

De rely kaart ondersteunt de volgende velden:

Veld	Type	Description
at_most_one_match	Booleaanse	Optional. Wordt standaard ingesteld op false. Wanneer true, declareert dat ten hoogste één rij in de gekoppelde tabel overeenkomt met elke rij in de bron (een veel-op-een-relatie die niet uitwaaiert).

Warning

Alleen instellen at_most_one_match: true wanneer de join veel-op-een is. Deze relatie wordt tijdens runtime niet gevalideerd. Als meerdere rijen in de gekoppelde tabel overeenkomen met één bronrij, retourneren metingen (zoals SUM en COUNT) onjuiste resultaten.

In het volgende voorbeeld wordt at_most_one_match een veel-op-een-join van orders naar customer. Query's die filteren of groeperen op klantkenmerken hebben het meeste voordeel:

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)

Velden

Note

fields en dimensions equivalente trefwoorden zijn in een definitie van een metrische weergave. fields is de voorkeursterm en wordt in deze documentatie gebruikt. De Editor met weinig code van Catalog Explorer labelt deze kolommen Velden, maar de YAML die wordt gegenereerd, maakt gebruik van het dimensions trefwoord. Bestaande metrische weergaven die gebruikmaken dimensions van blijven werken en beide trefwoorden worden geaccepteerd voor nieuwe of bijgewerkte definities.

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

Een veld kan een van de volgende zijn:

• Een categorische of groeperingskolom, zoals een regio, status of afdeling.
• Een niet-samengevoegde numerieke kolom, zoals een leeftijd, prijs of hoeveelheid. Numerieke velden kunnen tijdens het uitvoeren van query's worden samengevoegd met behulp van SQL-functies zoals SUM of AVG.

Elke velddefinitie bevat de volgende eigenschappen:

Property	Type	Description
name	String	Vereist voor expliciete kolomexpressies. De kolomalias voor het veld. Laat deze weg voor expressies met jokertekens, waarbij Azure Databricks namen van de bron afleidt. Zie velden en metingen voor bulksgewijs importeren met jokertekens.
expr	String	Required. Een SQL-expressie die kan verwijzen naar kolommen uit de brongegevens of een eerder gedefinieerd veld. Dit kan een jokerteken zijn om alle kolommen uit de bron of een gekoppelde tabel te importeren. Zie velden en metingen voor bulksgewijs importeren met jokertekens.
comment	String	Optional. Beschrijving van het veld. Wordt weergegeven in Unity Catalog en documentatiehulpprogramma's.
display_name	String	Optional. Label dat wordt weergegeven in hulpmiddelen voor visualisaties. Beperkt tot 255 tekens. Vereist YAML-specificatie 1.1. Bekijk de beschikbaarheid van functies in de metrische weergave.
format	Toewijzen	Optional. Indelingsspecificatie voor hoe waarden worden weergegeven. Vereist YAML-specificatie 1.1. Zie Opmaakspecificaties.
synonyms	Array	Optional. Alternatieve namen voor AI- en BI-hulpprogramma's om het veld te ontdekken. Maximaal 10 synoniemen, elk beperkt tot 255 tekens. Vereist YAML-specificatie 1.1. Zie Synoniemen.

Warning

Tekenreeksachtige metrische-weergavevelden zijn altijd STRING, zelfs wanneer de bronkolom CHAR of VARCHAR is. Omdat CHAR(n) ruimteopvulling verloren gaat, kunnen vergelijkingen verschillende resultaten retourneren. Zo komt column = 'COLLEGE' bijvoorbeeld overeen met een waarde van CHAR(10) in de brontabel (die met spaties is opgevuld), maar niet in het veld in de metriekweergave.

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

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 basiskolommen in de brongegevens, eerder gedefinieerde velden of eerder gedefinieerde metingen.

Elke metingdefinitie bevat de volgende velden:

Veld	Type	Description
name	String	Vereist voor expliciete metingexpressies. De alias voor de meting. Laat deze weg voor expressies met jokertekens, waarbij Azure Databricks namen van de bron afleidt. Zie velden en metingen voor bulksgewijs importeren met jokertekens.
expr	String	Required. Een SQL-expressie met een of meer statistische functies. Dit kan een jokerteken zijn om alle metingen te importeren uit een bron van een metrische weergave. Zie velden en metingen voor bulksgewijs importeren met jokertekens.
comment	String	Optional. Beschrijving van de meting. Wordt weergegeven in Unity Catalog en documentatiehulpprogramma's.
display_name	String	Optional. Label dat wordt weergegeven in hulpmiddelen voor visualisaties. Beperkt tot 255 tekens. Vereist YAML-specificatie 1.1. Bekijk de beschikbaarheid van functies in de metrische weergave.
format	Toewijzen	Optional. Indelingsspecificatie voor hoe waarden worden weergegeven. Vereist YAML-specificatie 1.1. Zie Opmaakspecificaties.
synonyms	Array	Optional. Alternatieve namen voor AI- en BI-hulpprogramma's om de meting te detecteren. Maximaal 10 synoniemen, elk beperkt tot 255 tekens. Vereist YAML-specificatie 1.1. Bekijk de beschikbaarheid van functies in de metrische weergave.
window	Array	Optional. Vensterspecificaties voor gevensterde, cumulatieve of semi-aangrenzende aggregaties. Wanneer deze niet is opgegeven, gedraagt de meting zich als een standaardaggregaties. Zie Vensterafmetingen.

Zie Statistische functies voor een lijst met statistische functies.

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

Velden en metingen bulksgewijs importeren met jokertekens

Van toepassing op: Databricks Runtime 18.2 en hoger met YAML-specificatie 1.1

In een fields of measures definitie kunt u een jokerteken (*) in het expr veld gebruiken om alle kolommen uit de bron of een gekoppelde tabel te importeren zonder dat u deze hoeft te vermelden. Dit is handig als u wilt dat een metrische weergave elke kolom uit een upstream-asset beschikbaar maakt, vergelijkbaar met SELECT * in een standaardweergave. Azure Databricks breidt het jokerteken uit naar concrete kolommen wanneer u de metrische weergave maakt of vervangt en wordt elke kolomnaam afgeleid van de naam van de bronkolom.

Net als expliciete kolomdefinities worden jokertekenexpressies uitgevouwen wanneer u de metrische weergave maakt. Als u later kolommen wilt ophalen die aan de bron zijn toegevoegd, maakt u de metrische weergave opnieuw met CREATE OR REPLACE of ALTER.

Jokertekens ondersteunen de volgende formulieren:

Syntax	Description
source.*	Importeer alle kolommen uit de bron van de metrische weergave.
<join>.*	Importeer alle kolommen uit een gekoppelde tabel, waarnaar wordt verwezen door de naam van de join. Geneste joins maken gebruik van het volledige puntpad, zoals customer.nation.*.
<target>.* EXCEPT (col1, col2, ...)	Importeer alle kolommen uit het doel, met uitzondering van de kolommen die worden vermeld.
<target>.<struct>.*	Vouw de velden van een STRUCT kolom uit in afzonderlijke kolommen.

De volgende regels zijn van toepassing op expressies met jokertekens:

• Laat het name veld weg. Azure Databricks kolomnamen afleiden van de bron, dus name is dit niet toegestaan voor een expressie met jokertekens.
• Semantische metagegevens zijn niet toegestaan voor een jokertekenexpressie. Niet instellencomment, display_nameof formatsynonyms op een jokerteken. Als u metagegevens wilt toevoegen aan een specifieke kolom, sluit u deze uit van het jokerteken met EXCEPT en definieert u deze expliciet.
• In een measures definitie importeert een jokerteken alleen metingen uit een bron van een metrische weergave. Basistabellen hebben geen metingen, dus een jokerteken wordt uitgebreid tot geen metingen wanneer de bron een basistabel is.
• U kunt in een latere fields expressie measures niet verwijzen naar een kolom die met jokertekens is geïmporteerd. Verwijs in plaats daarvan naar de bronkolom met het volledige pad.

Naamconflicten oplossen

Wanneer u kolommen uit meer dan één bron importeert met een jokerteken, botsen kolommen die een naam (zoals id of date) delen en een fout veroorzaken wanneer u de definitie opslaat. Als u een botsing wilt oplossen, sluit u de kolom uit van elk jokerteken met EXCEPTen definieert u deze expliciet met een unieke naam:

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

Voorbeeld van jokerteken

De volgende definitie importeert alle kolommen uit de bron en uit een gekoppelde tabel, sluit twee kolommen uit en definieert één kolom expliciet om metagegevens toe te voegen:

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'

Venstermetingen

Belangrijk

Deze functie is experimenteel.

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:

Veld	Type	Description
order	String	Required. Het veld dat de volgorde van het venster bepaalt. (1)
range	String	Required. De omvang van het venster. Zie Ondersteunde range waarden.
semiadditive	String	Required. Aggregatiemethode. Ondersteunde waarden: first of last.
offset	String	Optional. Vereist Databricks Runtime 18.1 en YAML-specificatie versie 1.1 of hoger. Hiermee verschuift u het vensterkader achteruit of vooruit langs het order veld met een vast interval. De waarde is van het formulier<n> <period>, waarbij n een ondertekend geheel getal is (negatief kijkt naar achteren, positief kijkt vooruit) en period is een vanday, days, month, , monthsof year.years Voorbeelden: -12 month, 1 year, -3 days, 7 day. Het order veld moet een datum- of tijdstempelkolom zijn. offset heeft geen effect op range: all. Als het verschoven frame buiten de beschikbare gegevens valt, wordt de meting geëvalueerd.NULL Zie Hoe offset het vensterkader wordt verplaatst voor gebruiks- en werkvoorbeelden.

(1) Het veld waarnaar wordt verwezen, moet deterministisch zijn. Niet-deterministische expressies zoals rand(), uuid()of current_timestamp() produceren onvoorspelbare venstervolgorde en kunnen leiden tot onjuiste aggregatieresultaten.

Ondersteunde range waarden

• current: Rijen waar de volgordewaarde van het venster gelijk is aan de waarde van de ankerrij.
• cumulative: Alle rijen waar de volgordewaarde van het venster kleiner is dan of gelijk is aan de waarde van de ankerrij.
• trailing <value> <unit> [inclusive | exclusive]: Rijen van de ankerrij die achteruitgaan door de opgegeven tijdseenheden, bijvoorbeeld trailing 7 day. Voor de optionele inclusive of exclusive modifier is Databricks Runtime 18.1 en YAML-specificatie versie 1.1 of hoger vereist en wordt bepaald of de ankerrij is opgenomen in het venster. De standaardwaarde is exclusive. Zie De ankerrij opnemen of uitsluiten.
• leading <value> <unit> [inclusive | exclusive]: Rijen van de ankerrij vooruitgaand door de opgegeven tijdseenheden, bijvoorbeeld leading 3 month. Voor de optionele inclusive of exclusive modifier is Databricks Runtime 18.1 en YAML-specificatie versie 1.1 of hoger vereist en wordt bepaald of de ankerrij is opgenomen in het venster. De standaardwaarde is exclusive. Zie De ankerrij opnemen of uitsluiten.
• all: Alle rijen, ongeacht de volgordewaarde van het venster.

Voorbeeld van venstermeting

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

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

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.

Note

U kunt een metrische weergave die parameters definieert, niet materialiseren.

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

Veld	Type	Description
schedule	String	Optional. Vernieuwingsschema. Gebruikt dezelfde syntaxis als de planningscomponent voor gerealiseerde weergaven. Als u dit weglaat, worden materialisaties alleen handmatig vernieuwd. Zie Handmatig vernieuwen als u een handmatige vernieuwing wilt activeren. De TRIGGER ON UPDATE component wordt niet ondersteund.
mode	String	Required. Moet worden ingesteld op relaxed.
materialized_views	Array	Required. Lijst met gerealiseerde weergaven om te materialiseren. Voor elke vermelding zijn de hieronder beschreven velden vereist.

Elke vermelding bevat materialized_views de volgende velden:

Veld	Type	Description
name	String	Required. De naam van de materialisatie.
type	String	Required. Type materialisatie. Ondersteunde waarden: aggregated (vereist dimensions, measuresof beide) of unaggregated. Er is slechts één unaggregated vermelding toegestaan per metrische weergave. Niet-samengevoegde vermeldingen gebruiken de dimensions velden measures niet.
dimensions	Array	Voorwaardelijk. Lijst met veldnamen die moeten worden gerealiseerd, met behulp van het dimensions trefwoord, zelfs als uw definitie op het hoogste niveau gebruikmaakt fieldsvan . Vereist als type dat het is aggregated en er geen measures zijn opgegeven.
measures	Array	Voorwaardelijk. Lijst met metingsnamen die moeten worden gerealiseerd. Vereist als type dat het is aggregated en er geen dimensions zijn opgegeven.
cluster_by	Object	Optional. Clusteringkolommen voor de materialisatie, equivalent aan de CLUSTER BY component in een gerealiseerde weergave. Geef cols op met een lijst met kolomnamen of stel deze in auto: true om Databricks de clusterkolommen automatisch te laten kiezen.
partition_by	Array	Optional. Lijst met kolommen voor het partitioneren van de materialisatie op basis van de PARTITION BY component in een gerealiseerde weergave.

Note

Het materialisatieblok gebruikt het dimensions: trefwoord in plaats fields:van . Gebruik dimensions: deze optie bij het weergeven van velden om te materialiseren, zelfs als uw definitie op het hoogste niveau gebruikmaakt fields:van .

Voorbeeld van materialisatie

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

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

Kolomnaamverwijzingen

Wanneer u verwijst naar kolomnamen die spaties of speciale tekens in YAML-expressies bevatten, plaatst u de kolomnaam in backticks. 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 voorbeelden ziet u hoe u kolomverwijzingen opmaken, afhankelijk van de tekens die ze bevatten.

Geen spaties

Bronkolom: revenue

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

Gebruik dubbele aanhalingstekens, enkele aanhalingstekens of geen aanhalingstekens rond de kolomnaam.

Kolomnaam met spaties

Bronkolom: `First Name`

expr: '`First Name`'

Gebruik backticks om spaties te ontsnappen. Plaats de volledige expressie tussen dubbele aanhalingstekens.

Kolomnamen met spaties in een SQL-expressie

Bronkolommen: `First Name`, `Last Name`

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

Als de expressie niet begint met een backtick, zijn dubbele aanhalingstekens niet vereist.

Kolomnaam met aanhalingstekens

Bronkolom: "name"

expr: '`"name"`'

Gebruik backticks om de dubbele aanhalingstekens in de kolomnaam te ontsnappen. Plaats de expressie tussen enkele aanhalingstekens.

Expressies met dubbele punten

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

Note

YAML interpreteert niet-aanhalingstekens als scheidingstekens voor sleutelwaarden. Gebruik altijd dubbele aanhalingstekens rond expressies die dubbele punten bevatten.

Expressies met meerdere regels

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

Note

Gebruik het | scalaire blok na expr: voor expressies met meerdere regels. Alle regels moeten ten minste twee spaties na de expr toets worden ingesprongen voor de juiste parsing.

Upgrade uitvoeren naar YAML 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 single-line opmerkingen die rechtstreeks in het YAML-bestand zijn geschreven.
• Opmerkingen bij Unity Catalog: Opmerkingen die zijn opgeslagen in Unity Catalog voor de metrische weergave of de bijbehorende kolommen. Deze zijn gescheiden van YAML-opmerkingen.

Overwegingen bij de upgrade

Selecteer het upgradepad dat overeenkomt met de manier waarop u opmerkingen in de metrische weergave wilt verwerken.

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

Warning

Het uitvoeren van ALTER VIEW verwijdert Unity Catalog-opmerkingen, tenzij ze expliciet worden opgenomen in de comment velden van de YAML-definitie. Zie Optie 2 als u opmerkingen wilt behouden die worden weergegeven in De Unity-catalogus.

Optie 2: Opmerkingen bij Unity Catalog behouden

Note

De volgende richtlijnen zijn alleen van toepassing wanneer u de ALTER VIEW opdracht gebruikt in een notebook of SQL-editor. Als u de metrische weergave bijwerkt naar versie 1.1 met behulp van de GEBRUIKERSinterface van de YAML-editor, behoudt de GEBRUIKERSinterface van de YAML-editor automatisch de opmerkingen van uw Unity Catalog.

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

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

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