Référence de la syntaxe YAML de la vue métrique
Les définitions de vue de métrique utilisent la syntaxe YAML standard pour déclarer la source, les jointures, les champs, les mesures, les filtres, les mesures de fenêtre et la matérialisation. Les sections suivantes documentent la grammaire complète de chacune.
Pour connaître les exigences minimales en matière de runtime et de version de spécification YAML pour chaque fonctionnalité, consultez Disponibilité des fonctionnalités de vue métrique.
Consultez la documentation sur la spécification YAML 1.2.2 pour en savoir plus sur les spécifications YAML.
Modifier le YAML dans l'éditeur d'affichage sous forme métrique
Vous pouvez écrire et modifier le YAML décrit sur cette page directement dans l'éditeur de vue de métrique. Dans l'Explorateur de catalogues, ouvrez une vue sous forme métrique et cliquez sur le bouton <> pour modifier la définition. Pour générer du YAML à partir d'une description en langage naturel, ouvrez plutôt Genie Code depuis l'éditeur. Pour une présentation complète de l’éditeur, consultez Créer une vue sous forme métrique.
Champs YAML de premier niveau
La définition YAML d'une vue de métrique comprend les champs de premier niveau suivants :
Champ | Type | Description |
|---|---|---|
| Chaîne | Obligatoire. La version de la spécification YAML de la vue métrique que la définition utilise, telle que |
| Chaîne | Facultatif. Description de la vue métrique. |
| Chaîne | Obligatoire. Les données sources pour la vue métrique. Peut être n'importe quel actif Unity Catalog de type table, y compris une vue de métrique ou une query SQL. Voir Source. |
| Tableau | Facultatif. Valeurs nommées que les appelants transmettent lorsqu'ils interrogent la vue métrique en tant que fonction à valeur de table. See parameter. |
| Chaîne | Facultatif. Une expression booléenne SQL qui s'applique à toutes les requêtes. Consultez Filtre. |
| Tableau | Facultatif. Jointures de schémas en étoile et en flocon de neige. Voir les Jointures. |
| Tableau | Conditionnel. Définitions des champs incluant le nom, l'expression et les métadonnées sémantiques facultatives. Obligatoire si aucun |
| Tableau | Conditionnel. Définitions de mesures, y compris le nom, l'expression d'agrégation et les métadonnées sémantiques facultatives. Obligatoire si aucun |
| Objet | Facultatif. Configuration pour accélérer les requêtes avec des vues matérialisées. Comprend la planification de refresh et les définitions de vues matérialisées. Voir Matérialisation. |
Source
Le champ source spécifie la source de données pour la vue métrique. Les sources prises en charge incluent les tables, les vues, les vues métriques et les queries SQL. La composabilité s'applique à toutes les vues métriques. Lorsque vous utilisez une vue métrique comme source, vous pouvez référencer ses champs et ses mesures dans la nouvelle vue métrique. Voir Composabilité.
Source d'asset de type table
Référencez un asset de type tableau en utilisant son nom en trois parties :
source: catalog.schema.source_table
Source de query SQL
Pour utiliser une requête SQL, écrivez le texte de la query directement dans le YAML :
source: SELECT * FROM samples.tpch.orders o
LEFT JOIN samples.tpch.customer c
ON o.o_custkey = c.c_custkey
Lorsque vous utilisez une query SQL comme source avec une clause JOIN, définissez des contraintes de clé primaire et de clé étrangère sur les tables sous-jacentes et utilisez l'option RELY pour des performances de query optimales. Pour plus d'informations, consultez Déclarer les contraintes de clé primaire, de clé étrangère et d'unicité et Optimisation des query à l'aide des contraintes de clé primaire et d'unicité.
parameter
Le bloc parameters définit des valeurs nommées que les appelants transmettent lorsqu'ils interrogent la vue de métriques en tant que fonction à valeur de table. Pour savoir quand et comment utiliser les paramètres, y compris pour interroger un affichage métrique paramétré, consultez Utiliser des paramètres avec les vues de métriques.
Chaque définition de paramètre comprend les champs suivants :
Champ | Type | Description |
|---|---|---|
| Chaîne | Obligatoire. Le nom du paramètre. Référencez le paramètre par ce nom dans les expressions de champ et de mesure, et passez-le comme argument nommé lorsque vous interrogez la vue d'indicateur. |
| Chaîne | Obligatoire. Le type de données SQL du paramètre, tel que |
| Varie | Facultatif. La valeur utilisée lorsqu'un appelant ne transmet pas le parameter. Le default doit être convertible en |
L'exemple suivant définit un paramètre discount et le référence dans une expression de mesure :
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)
Filtre
Un filtre dans la définition YAML s'applique à toutes les queries qui référencent la vue métrique. Rédigez les filtres sous forme d'expressions booléennes SQL.
# 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'
Jointures
Les jointures dans les vues de métriques prennent en charge les jointures directes d’une table de faits vers des tables de dimension (schéma en étoile) et les jointures multi-sauts sur des tables de dimension normalisées (schémas en flocon de neige). Vous pouvez également joindre à une requête SQL à l'aide d'une instruction SELECT. Voir Utiliser une requête SQL comme source.
Les tables jointes ne peuvent pas inclure de colonnes de type MAP. Pour décompresser les valeurs des colonnes de type MAP, consultez Exploser les éléments imbriqués d'une carte ou d'un tableau.
Chaque définition de jointure comprend les champs suivants :
Champ | Type | Description |
|---|---|---|
| Chaîne | Obligatoire. Alias pour la table jointe ou la query SQL. Utilisez cet alias lorsque vous référencez des colonnes de la table jointe dans des champs ou des mesures. |
| Chaîne | Obligatoire. Nom en trois parties de la table à joindre. Peut aussi être une requête SQL. |
| Chaîne | Conditionnel. Expression booléenne définissant la condition de jointure. Obligatoire si |
| Tableau | Conditionnel. Liste des noms de colonne présents dans la table parente et la table jointe. Obligatoire si |
| Chaîne | Facultatif. La valeur par défaut est |
| Tableau | Facultatif. Une liste de définitions de jointure imbriquées pour la modélisation de schémas en flocon de neige. Consultez Disponibilité des fonctionnalités de vue métrique pour connaître les exigences minimales d'exécution. |
| Carte | Facultatif. Promesses concernant la jointure sur lesquelles l'analyseur peut s'appuyer pour produire des plans de query plus efficaces. Consultez Optimiser les jointures avec |
Jointures de schéma en étoile
Dans un schéma en étoile, le source est la table de faits et s'associe à une ou plusieurs tables de dimensions à l'aide d'un LEFT OUTER JOIN. Les vues de métriques associent les tables de faits et de dimensions nécessaires à la query spécifique, en fonction des colonnes sélectionnées.
Spécifiez les colonnes de jointure à l'aide d'une clause ON ou d'une clause USING :
ONClause : Utilise une expression booléenne pour définir la condition de jointure.USINGclause : Répertorie les colonnes portant le même nom dans la table parente et dans la table jointe.
La jointure doit suivre une relation plusieurs-à-un. Dans les cas de relations plusieurs à plusieurs, la première ligne correspondante de la table de dimensions jointe est sélectionnée.
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)
L'espace de noms source fait référence aux colonnes de la source de la vue des métriques, tandis que le name d'une jointure fait référence aux colonnes de la table jointe. Par exemple, dans source.l_orderkey = orders.o_orderkey, source fait référence à lineitem et orders fait référence à la table jointe. Si aucun préfixe n'est fourni dans une clause on, la référence est default à la table jointe.
Jointures de schéma Snowflake
Un schéma en flocon de neige étend un schéma en étoile en normalisant les tables de dimension et en les connectant à des sous-dimensions. Cela crée une structure de jointure à plusieurs niveaux. Consultez Disponibilité des fonctionnalités de vue métrique pour connaître les exigences minimales d'exécution.
Pour définir un schéma en flocon de neige, imbriquez joins à l'intérieur d'une définition de jointure parente :
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
Jointures un à plusieurs
Le champ cardinality définit la relation entre la source et une table jointe. Le default, many_to_one, traite la table jointe comme une table de consultation de dimensions. Définissez cardinality: one_to_many pour traiter la table jointe comme une source de faits que le moteur agrège indépendamment à la granularité source, ce qui permet à une seule ligne source de correspondre à plusieurs lignes dans la table jointe. Les jointures un-à-plusieurs nécessitent Databricks Runtime 18.1 ou une version ultérieure, et la version 1.1 de la spécification YAML. Veuillez consulter Disponibilité des fonctionnalités de vue métrique.
Les règles suivantes s'appliquent aux jointures un-à-plusieurs :
- Une colonne de type un-à-plusieurs ne peut pas être utilisée dans une définition
fields, car un champ doit se résoudre en une valeur unique par ligne source. - Une seule fonction d'agrégation doit faire référence à des colonnes provenant d'une seule source. Vous pouvez appliquer des opérations arithmétiques sur les résultats d'agrégations distinctes, telles que :
count(orders.order_id) / count(*). - Tous les descendants d'une jointure un-à-plusieurs doivent également être
one_to_many. Les jointures sœurs de niveau supérieur peuvent combiner des cardinalités. - Référencez une colonne dans une jointure imbriquée avec son chemin complet via les noms de jointure, tels que
orders.order_items.item_id.
L'exemple suivant joint orders à une source customers avec cardinality: one_to_many afin que les mesures de commande s'agrègent sans dupliquer les lignes de clients :
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)
Pour plus de détails conceptuels et des exemples de jointures imbriquées et adjacentes, consultez Cardinalité de la jointure.
Optimiser les jointures avec rely
Utilisez le champ rely sur une jointure pour déclarer des garanties concernant la relation que l'analyseur de query utilise lors de la planification des queries. Ces garanties permettent au moteur de planifier les queries plus efficacement et de réduire les données analysées, en particulier lorsque les champs de la table jointe sont référencés dans les filtres.
La carte rely prend en charge les champs suivants :
Champ | Type | Description |
|---|---|---|
| Booléen | Facultatif. La valeur par défaut est |
Définissez at_most_one_match: true uniquement lorsque la jointure est plusieurs-à-un. Cette relation n'est pas validée à l'environnement d'exécution. Si plusieurs lignes de la table jointe correspondent à une seule ligne source, les mesures (telles que SUM et COUNT) renvoient des résultats incorrects.
L'exemple suivant active at_most_one_match sur une jointure de plusieurs à un de orders à customer. Les query qui filtrent ou regroupent par attributs de clients sont les plus avantagées :
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)
Champs
fields et dimensions sont des mots-clés équivalents dans une définition d’affichage sous forme métrique. fields est le terme privilégié et est utilisé dans toute cette documentation. L'éditeur low-code de l'Explorateur de catalogues intitule ces colonnes Champs , mais le YAML qu'il génère utilise le mot-clé dimensions. Les vues métriques existantes qui utilisent dimensions continuent de fonctionner, et les deux mots-clés sont acceptés sur les définitions nouvelles ou mises à jour.
Les champs sont des colonnes de vue métrique utilisés dans les clauses SELECT, WHERE et GROUP BY au moment de la query. Chaque expression doit retourner une valeur scalaire. Les champs peuvent faire référence à des colonnes des données sources ou à des champs définis précédemment dans la vue de métrique.
Un champ peut être :
- Une colonne catégorielle ou de regroupement, telle qu'une région, un statut ou un service.
- Une colonne numérique non agrégée, telle qu'un âge, un prix ou une quantité. Les champs numériques peuvent être agrégés au moment de la requête à l'aide de fonctions SQL telles que
SUMouAVG.
Chaque définition de champ comprend les propriétés suivantes :
Propriété | Type | Description |
|---|---|---|
| Chaîne | Requis pour les expressions de colonne explicites. L'alias de colonne pour le champ. Omettez-le pour les expressions génériques, où Databricks dérive les noms de la source. Veuillez consulter Importer en masse les champs et les mesures avec des caractères génériques. |
| Chaîne | Obligatoire. Une expression SQL qui peut référencer des colonnes à partir des données source ou d'un champ précédemment défini. Peut être un caractère générique pour importer toutes les colonnes de la source ou d'une table jointe. Veuillez consulter Importer en masse les champs et les mesures avec des caractères génériques. |
| Chaîne | Facultatif. Description du champ. S’affiche dans Unity Catalog et les outils de documentation. |
| Chaîne | Facultatif. Étiquette qui apparaît dans les outils de visualisation. Limité à 255 caractères. Nécessite la spécification YAML 1.1. Consultez la disponibilité de la fonctionnalité de vue métrique. |
| Carte | Facultatif. Spécification de format pour la manière dont les valeurs sont affichées. Nécessite la spécification YAML 1.1. Voir les spécifications de format. |
| Tableau | Facultatif. Noms alternatifs pour les outils d'IA et de BI afin de découvrir le domaine. Jusqu'à 10 synonymes, chacun limité à 255 caractères. Nécessite la spécification YAML 1.1. Voir Synonymes. |
Les champs de vue métrique de type chaîne sont toujours STRING, même lorsque la colonne source est CHAR ou VARCHAR. Étant donné que le remplissage d'espaces CHAR(n) est perdu, les comparaisons peuvent renvoyer des résultats différents. Par exemple, column = 'COLLEGE' correspond à une valeur CHAR(10) dans la table source (qui est complétée par des espaces) mais pas dans le champ d'affichage métrique.
Exemple :
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']
Mesures
Les mesures sont des expressions qui produisent des résultats sans niveau d'agrégation prédéterminé. Elles doivent être exprimées à l'aide de fonctions agrégées. Pour référencer une mesure dans une requête, utilisez la fonction MEASURE. Les mesures peuvent faire référence à des colonnes de base dans les données source, à des champs définis précédemment ou à des mesures définies précédemment.
Chaque définition de mesure comprend les champs suivants :
Champ | Type | Description |
|---|---|---|
| Chaîne | Requis pour les expressions de mesure explicites. L'alias pour la mesure. Omettez-le pour les expressions génériques, où Databricks dérive les noms de la source. Veuillez consulter Importer en masse les champs et les mesures avec des caractères génériques. |
| Chaîne | Obligatoire. Une expression SQL contenant une ou plusieurs fonctions d'agrégation. Peut être un caractère générique pour importer toutes les mesures d'une source de vue métrique. Veuillez consulter Importer en masse les champs et les mesures avec des caractères génériques. |
| Chaîne | Facultatif. Description de la mesure. S’affiche dans Unity Catalog et les outils de documentation. |
| Chaîne | Facultatif. Étiquette qui apparaît dans les outils de visualisation. Limité à 255 caractères. Nécessite la spécification YAML 1.1. Consultez la disponibilité de la fonctionnalité de vue métrique. |
| Carte | Facultatif. Spécification de format pour la manière dont les valeurs sont affichées. Nécessite la spécification YAML 1.1. Voir les spécifications de format. |
| Tableau | Facultatif. Noms alternatifs pour les outils d'IA et de BI afin de découvrir la mesure. Jusqu'à 10 synonymes, chacun limité à 255 caractères. Nécessite la spécification YAML 1.1. Consultez la disponibilité de la fonctionnalité de vue métrique. |
| Tableau | Facultatif. Spécifications de fenêtre pour les agrégations fenêtrées, cumulatives ou semi-additives. Lorsqu'elle n'est pas spécifiée, la mesure se comporte comme un agrégat standard. Voir les mesures de fenêtre. |
Consultez les fonctions d'agrégation pour obtenir une liste des fonctions d'agrégation.
Exemple :
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']
Importer en masse des champs et des mesures avec des caractères génériques
S’applique à : Databricks Runtime 18.2 et versions ultérieures avec la spécification YAML 1.1
Dans une définition fields ou measures, vous pouvez utiliser un caractère générique (*) dans le champ expr pour importer toutes les colonnes de la source ou d’une table jointe sans les répertorier une par une. Ceci est utile lorsque vous souhaitez qu'une vue métrique expose chaque colonne d'un asset amont, similaire à SELECT * dans une vue standard. Databricks étend le caractère générique aux colonnes concrètes lorsque vous créez ou remplacez la vue métrique, et dérive chaque nom de colonne du nom de la colonne source.
Comme les définitions de colonnes explicites, les expressions à caractères génériques sont développées lorsque vous créez la vue métrique. Pour récupérer les colonnes ajoutées ultérieurement à la source, recréez la vue métrique avec CREATE OR REPLACE ou ALTER.
Les caractères génériques prennent en charge les formes suivantes :
Syntaxe | Description |
|---|---|
| Importer toutes les colonnes à partir de la source de la vue métrique. |
| Importer toutes les colonnes d'une table jointe, référencées par son nom de jointure. Les jointures imbriquées utilisent le chemin complet en notation pointée, tel que |
| Importez toutes les colonnes de la cible, à l'exception de celles répertoriées. |
| Développez les champs d'une colonne |
Les règles suivantes s'appliquent aux expressions avec caractères génériques :
- Omettez le champ
name. Databricks dérive les noms de colonnes de la source, doncnamen'est pas autorisé sur une expression avec caractères génériques. - Les métadonnées sémantiques ne sont pas autorisées sur une expression générique. Ne définissez pas
comment,display_name,formatousynonymssur un caractère générique. Pour ajouter des métadonnées à une colonne spécifique, excluez-la du caractère générique avecEXCEPTet définissez-la explicitement. - Dans une définition
measures, un caractère générique importe des mesures uniquement depuis une source de vue métrique. Les tables de base n’ont pas de mesures, de sorte qu’un caractère générique ne s’étend à aucune mesure lorsque la source est une table de base. - Vous ne pouvez pas référencer une colonne importée par caractère générique par son nom dérivé dans une expression
fieldsoumeasuresultérieure. Référencez plutôt la colonne source avec son chemin complet.
Résoudre les conflits de noms
Lorsque vous importez des colonnes de plusieurs sources avec un caractère générique, les colonnes qui partagent un nom (comme id ou date) entrent en collision et provoquent une erreur lorsque vous enregistrez la définition. Pour résoudre une collision, excluez la colonne de chaque caractère générique avec EXCEPT, puis définissez-la explicitement avec un nom unique :
fields:
- expr: source.* EXCEPT (id)
- expr: customer.* EXCEPT (id)
- name: source_id
expr: source.id
- name: customer_id
expr: customer.id
Exemple de caractère générique
La définition suivante importe toutes les colonnes de la source et d'une table jointe, exclut deux colonnes et définit une colonne explicitement pour ajouter des métadonnées :
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'
Mesures de la fenêtre
Expérimental
Cette fonctionnalité est expérimentale.
Le champ window définit les agrégations fenêtrées, cumulatives ou semi-additives pour les mesures. Pour des informations détaillées sur les mesures de fenêtre et les cas d'utilisation, consultez Mesures de fenêtre.
Chaque spécification de fenêtre inclut les champs suivants :
Champ | Type | Description |
|---|---|---|
| Chaîne | Obligatoire. Le champ qui détermine l'ordre de la fenêtre. (1) |
| Chaîne | Obligatoire. L'étendue de la fenêtre. Consultez Valeurs |
| Chaîne | Obligatoire. Méthode d'agrégation. Valeurs prises en charge : |
| Chaîne | Facultatif. Nécessite Databricks Runtime 18,1 et la version 1,1 ou supérieure de la spécification YAML. Déplace le cadre de la fenêtre en arrière ou en avant le long du champ |
(1) Le champ référencé doit être déterministe. Les expressions non déterministes telles que rand(), uuid() ou current_timestamp() produisent un ordonnancement des fenêtres imprévisible et peuvent entraîner des résultats d'agrégation incorrects.
Valeurs range prises en charge
current: Lignes où la valeur d'ordre de la fenêtre est égale à la valeur de la ligne d'ancrage.cumulative: Toutes les lignes où la valeur d'ordre de la fenêtre est inférieure ou égale à la valeur de la ligne d'ancrage.trailing <value> <unit> [inclusive | exclusive]: Lignes à partir de la ligne d'ancrage en reculant du nombre d'unités de temps spécifié, par exempletrailing 7 day. Le modificateur optionnelinclusiveouexclusivenécessite Databricks Runtime 18.1 et la version 1.1 ou ultérieure de la spécification YAML, et contrôle si la ligne d'ancrage est incluse dans la fenêtre. The default estexclusive. Voir Inclure ou exclure la ligne d'ancrage.leading <value> <unit> [inclusive | exclusive]: Lignes de la ligne d'ancrage avançant des unités de temps spécifiées, par exempleleading 3 month. Le modificateur optionnelinclusiveouexclusivenécessite Databricks Runtime 18.1 et la version 1.1 ou ultérieure de la spécification YAML, et contrôle si la ligne d'ancrage est incluse dans la fenêtre. The default estexclusive. Voir Inclure ou exclure la ligne d'ancrage.all: Toutes les lignes, quelle que soit la valeur d'ordre de la fenêtre.
Exemple de mesure de fenêtre
L'exemple suivant calcule un nombre glissant de 7 jours de clients uniques :
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
Matérialisation
Aperçu public
Cette fonctionnalité est en aperçu public.
Le champ materialization configure l’accélération automatique des query à l’aide de vues matérialisées. Pour des informations détaillées sur le fonctionnement de la matérialisation, les exigences et les bonnes pratiques, consultez Matérialisation des vues de métriques.
Vous ne pouvez pas matérialiser une vue de métrique qui définit des parameters.
Le champ materialization comprend les champs de niveau supérieur suivants :
Champ | Type | Description |
|---|---|---|
| Chaîne | Facultatif. Calendrier de refresh. Utilise la même syntaxe que la clause de planification sur les vues matérialisées. S'il est omis, les matérialisations sont rafraîchies uniquement manuellement. La clause |
| Chaîne | Obligatoire. Doit être défini sur |
| Tableau | Obligatoire. Liste des vues matérialisées à matérialiser. Chaque entrée nécessite les champs décrits ci-dessous. |
Chaque entrée dans materialized_views comprend les champs suivants :
Champ | Type | Description |
|---|---|---|
| Chaîne | Obligatoire. Le nom de la matérialisation. |
| Chaîne | Obligatoire. Type de matérialisation. Valeurs prises en charge : |
| Tableau | Conditionnel. Liste des noms de champs à matérialiser. Requis si |
| Tableau | Conditionnel. Liste des noms de mesures à matérialiser. Requis si |
| Objet | Facultatif. Colonnes de clustering pour la matérialisation, équivalent à la |
| Tableau | Facultatif. Liste des colonnes par lesquelles partitionner la matérialisation, équivalent à la |
Le bloc de matérialisation utilise le mot-clé dimensions: plutôt que fields:. Utilisez dimensions: lorsque vous répertoriez les champs à matérialiser, même si votre définition de niveau supérieur utilise fields:.
Exemple de matérialisation
L'exemple suivant définit une vue de métrique avec plusieurs matérialisations :
version: 1.1
source: samples.tpch.orders
fields:
- 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
cluster_by:
cols:
- order_date
- order_status
partition_by:
- order_date
Références des noms de colonne
Lorsque vous référencez les noms de colonne qui contiennent des espaces ou des caractères spéciaux dans les expressions YAML, encadrez le nom de la colonne entre apostrophes inversées. Si l'expression start par une apostrophe inversée et est utilisée directement comme valeur YAML, encadrez toute l'expression entre guillemets. Les valeurs YAML valides ne peuvent pas start par une apostrophe inversée.
Exemples de mise en forme
Utilisez les exemples suivants pour apprendre à formater correctement le YAML dans les scénarios courants.
Référencer un nom de colonne
Les exemples suivants montrent comment formater les références de colonne en fonction des caractères qu'elles contiennent.
Sans espaces
Colonne source : revenue
expr: "revenue"
expr: 'revenue'
expr: revenue
Utilisez des guillemets doubles, des guillemets simples ou aucun guillemet autour du nom de la colonne.
Nom de colonne avec espaces
Colonne source : `First Name`
expr: '`First Name`'
Utilisez les accents graves pour échapper les espaces. Encadrez l'expression entière entre guillemets doubles.
Noms de colonne contenant des espaces dans une expression SQL
Colonnes source : `First Name`, `Last Name`
expr: CONCAT(`First Name`, ' ', `Last Name`)
Si l’expression ne start pas par une apostrophe inversée, les guillemets doubles ne sont pas requis.
Nom de colonne contenant des guillemets
Colonne source : "name"
expr: '`"name"`'
Utilisez des guillemets inversés pour échapper les guillemets doubles dans le nom de la colonne. Mettez l'expression entre guillemets simples.
Expressions avec des deux points
expr: "CASE WHEN `Customer Tier` = 'Enterprise: Premium' THEN 1 ELSE 0 END"
YAML interprète les deux-points non cités comme des séparateurs clé-valeur. Utilisez toujours des guillemets doubles autour des expressions qui incluent des deux points.
Expressions multilignes
expr: |
CASE WHEN
revenue > 100 THEN 'High'
ELSE 'Low'
END
Utilisez le scalaire de bloc | après expr: pour les expressions multilignes. Toutes les lignes doivent être indentées d'au moins deux espaces au-delà de la clé expr pour un bon fonctionnement de l'analyse.
Mise à niveau vers YAML 1.1
La mise à niveau d’une vue de métriques vers la version 1.1 de la spécification YAML nécessite de la prudence, car les commentaires sont traités différemment par rapport aux versions antérieures.
Types de commentaires
- Commentaires YAML (
#) : commentaires en ligne ou sur une seule ligne écrits directement dans le fichier YAML. - Commentaires Unity Catalog : Commentaires stockés dans Unity Catalog pour la vue de métriques ou ses colonnes. Ceux-ci sont distincts des commentaires YAML.
Considérations relatives à la mise à niveau
Sélectionnez le chemin de mise à niveau qui correspond à la manière dont vous souhaitez gérer les commentaires dans votre vue métrique.
Option 1 : Préservez les commentaires YAML à l'aide des notebooks ou de l'éditeur SQL
Si votre vue métrique contient des commentaires YAML (#) que vous souhaitez conserver, suivez les étapes suivantes :
- Utilisez la commande
ALTER VIEWdans un notebook ou l’éditeur SQL. - Copiez la définition YAML originale dans la section
$$..$$aprèsAS. Modifiez la valeur deversionpar1.1. - Enregistrer la vue métrique.
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)
$$
L'exécution de ALTER VIEW supprime les commentaires de Unity Catalog à moins qu'ils ne soient explicitement inclus dans les champs comment de la définition YAML. Pour conserver les commentaires affichés dans Unity Catalog, consultez l'Option 2.
Option 2 : Conserver les commentaires Unity Catalog
Les instructions suivantes s'appliquent uniquement lorsque vous utilisez la commande ALTER VIEW dans un notebook ou un éditeur SQL. Si vous mettez à niveau votre vue de métrique vers la version 1,1 à l'aide de l'interface utilisateur de l'éditeur YAML, l'interface utilisateur de l'éditeur YAML conserve automatiquement vos commentaires Unity Catalog.
- Copiez tous les commentaires Unity Catalog dans les champs
commentappropriés de votre définition YAML. Changez la valeur deversionen1.1. - Enregistrer la vue métrique.
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"
$$
Pour l'historique des versions de la spécification YAML et les exigences d'exécution minimales pour chaque fonctionnalité, consultez Disponibilité des fonctionnalités d'affichage des métriques.