Informations de référence sur la syntaxe YAML de l’affichage des métriques

Les définitions d’affichage des métriques 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 pour chacune d’elles.

Pour connaître les exigences minimales en matière de version du runtime et de la spécification YAML pour chaque fonctionnalité, consultez la disponibilité des fonctionnalités d’affichage des métriques.

Consultez la documentation de la spécification YAML 1.2.2 pour en savoir plus sur les spécifications YAML.

Modifier YAML dans l’éditeur d’affichage des métriques

Vous pouvez écrire et modifier le YAML décrit dans cette page directement dans l’éditeur d’affichage des métriques. Dans l’Explorateur de catalogues, ouvrez une vue métrique et cliquez sur le <> bouton pour modifier la définition. Pour générer yaML à partir d’une description du langage naturel à la place, ouvrez Génie Code à partir de l’éditeur. Pour obtenir la procédure pas à pas de l’éditeur complet, consultez Créer une vue de métrique.

Champs YAML de niveau supérieur

La définition YAML pour une vue de métrique comprend les champs de niveau supérieur suivants :

Champ	Type	Description
version	String	Obligatoire. Version de la spécification YAML de la vue de métrique utilisée par la définition, par 1.1exemple . Il s’agit de la version du format de spécification, et non d’un numéro de révision que vous affectez à votre propre définition. Utilisez l’une des versions de spécification prises en charge. Consultez les versions de spécification YAML.
comment	String	Optional. Description de l’affichage des métriques.
source	String	Obligatoire. Données sources de la vue de métrique. Il peut s’agir de n’importe quelle ressource de catalogue Unity semblable à une table, y compris une vue de métrique ou une requête SQL. Voir Source.
parameters	Array	Optional. Valeurs nommées que les appelants passent lorsqu’ils interrogent la vue de métrique en tant que fonction table. Voir Paramètres.
filter	String	Optional. Expression booléenne SQL qui s’applique à toutes les requêtes. Voir Filtre.
joins	Array	Optional. Schéma en étoile et jointures de schéma flocons. Voir Jointures.
fields	Array	Conditionnel. Définitions de champs, notamment le nom, l’expression et les métadonnées sémantiques facultatives. Obligatoire si aucun n’est measures spécifié. Voir Champs. Le dimensions mot clé est accepté comme synonyme de compatibilité descendante.
measures	Array	Conditionnel. Définitions de mesure, notamment le nom, l’expression d’agrégation et les métadonnées sémantiques facultatives. Obligatoire si aucun n’est fields spécifié. Voir Mesures.
materialization	Object	Optional. Configuration pour accélérer les requêtes avec des vues matérialisées. Inclut la planification d’actualisation et les définitions de vue matérialisées. Voir Matérialisation.

Source

Le source champ spécifie la source de données de la vue métrique. Les sources prises en charge incluent des tables, des vues, des vues de métriques et des requêtes SQL. La composabilité s’applique aux vues de métriques. Lorsque vous utilisez une vue de métrique comme source, vous pouvez référencer ses champs et ses mesures dans la nouvelle vue de métrique. Consultez Composabilité.

Source de ressource de type table

Référencez une ressource de type table à l’aide de son nom en trois parties :

source: catalog.schema.source_table

Source de requête SQL

Pour utiliser une requête SQL, écrivez le texte de la requête directement dans yaML :

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

Note

Lorsque vous utilisez une requête SQL comme source avec une JOIN clause, définissez des contraintes de clé primaire et étrangère sur des tables sous-jacentes et utilisez l’option pour optimiser les RELY performances des requêtes. Pour plus d’informations, consultez Déclarer la clé primaire, la clé étrangère et les contraintes uniques etl’optimisation des requêtes à l’aide de la clé primaire et des contraintes uniques.

Paramètres

Le parameters bloc définit des valeurs nommées que les appelants passent lorsqu’ils interrogent la vue de métrique en tant que fonction table. Pour savoir quand et comment utiliser des paramètres, notamment l’interrogation d’une vue de métrique paramétrée, consultez Utiliser des paramètres avec des vues de métriques.

Chaque définition de paramètre inclut les champs suivants :

Champ	Type	Description
name	String	Obligatoire. Nom du paramètre. Référencez le paramètre par ce nom dans les expressions de champ et de mesure, puis transmettez-le en tant qu’argument nommé lorsque vous interrogez la vue de métrique.
data_type	String	Obligatoire. Type de données SQL du paramètre, tel que double, , intstring, ou date.
default	Varie	Optional. Valeur utilisée lorsqu’un appelant ne transmet pas le paramètre. La valeur par défaut doit être castable data_typeet elle ne peut pas référencer un autre paramètre ou contenir une sous-requête. Si vous définissez une valeur par défaut pour un paramètre, chaque paramètre qui suit doit également avoir une valeur par défaut.

L’exemple suivant définit un discount paramètre 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)

Filter

Un filtre dans la définition YAML s’applique à toutes les requêtes qui référencent la vue de métrique. Écrire des filtres en tant qu’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'

Joins

Les jointures dans les vues de métriques prennent en charge les jointures directes d’une table de faits à des tables de dimension (schéma en étoile) et des jointures à plusieurs tronçons entre des tables de dimension normalisées (schémas flocons de neige). Vous pouvez également vous joindre à une requête SQL à l’aide d’une SELECT instruction. Consultez Utiliser une requête SQL comme source.

Note

Les tables jointes ne peuvent pas inclure de MAP colonnes de type. Pour décompresser des valeurs à partir de colonnes de MAP type, consultez Explosion des éléments imbriqués à partir d’une carte ou d’un tableau.

Chaque définition de jointure inclut les champs suivants :

Champ	Type	Description
name	String	Obligatoire. Alias pour la table jointe ou la requête SQL. Utilisez cet alias lors du référencement de colonnes à partir de la table jointe dans des champs ou des mesures.
source	String	Obligatoire. Nom en trois parties de la table à joindre. Il peut également s’agir d’une requête SQL.
on	String	Conditionnel. Expression booléenne définissant la condition de jointure. Requis si using n'est pas spécifié.
using	Array	Conditionnel. Liste des noms de colonnes présents dans la table parente et la table jointe. Requis si on n'est pas spécifié.
cardinality	String	Optional. La valeur par défaut est many_to_one. Relation entre la source et la table jointe. Définissez la valeur pour one_to_many agréger une table qui a plusieurs lignes correspondantes par ligne source en tant que source de faits distincte. Consultez les jointures un-à-plusieurs.
joins	Array	Optional. Liste des définitions de jointure imbriquées pour la modélisation de schéma flocon. Consultez la disponibilité des fonctionnalités d’affichage des métriques pour connaître la configuration minimale requise pour le runtime.
rely	Map	Optional. Promesses concernant la jointure sur laquelle l’analyseur peut compter pour produire des plans de requête plus efficaces. Consultez Optimiser les jointures avec rely.

Jointures de schéma en étoile

Dans un schéma en étoile, source est la table des faits et est reliée à une ou plusieurs tables de dimension à l’aide d’un LEFT OUTER JOIN. Les vues de métriques rejoignent les tables de faits et de dimension nécessaires pour la requête spécifique, en fonction des colonnes sélectionnées.

Spécifiez des colonnes de jointure à l’aide d’une clause ou d’une ONUSING clause :

• ON clause : utilise une expression booléenne pour définir la condition de jointure.
• USING clause : répertorie les colonnes portant le même nom dans la table parente et la table jointe.

La jointure doit suivre une relation plusieurs-à-un. Dans les cas de relations de plusieurs-à-plusieurs, la première ligne correspondante de la table de dimension 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)

Note

L’espace source de noms référence les colonnes de la source de la vue de métrique, tandis que les name jointures font référence à des colonnes de cette table jointe. Par exemple, dans source.l_orderkey = orders.o_orderkey, source fait référence à lineitem la table jointe et orders fait référence à la table jointe. Si aucun préfixe n’est fourni dans une on clause, la référence correspond par défaut à la table jointe.

Jointures de schéma Snowflake

Un schéma flocon é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 la disponibilité des fonctionnalités d’affichage des métriques pour connaître la configuration minimale requise pour le runtime.

Pour définir un schéma 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 cardinality champ définit la relation entre la source et une table jointe. La valeur par défaut, many_to_onetraite la table jointe comme une recherche de dimension. Définissez cardinality: one_to_many pour traiter la table jointe comme une source de faits que le moteur agrège indépendamment au niveau du grain source, ce qui permet à une seule ligne source de correspondre à plusieurs lignes de la table jointe. Les jointures un-à-plusieurs nécessitent Databricks Runtime 18.1 ou version ultérieure et la spécification YAML version 1.1. Consultez la disponibilité des fonctionnalités d’affichage des métriques.

Les règles suivantes s’appliquent aux jointures un-à-plusieurs :

• Une colonne un-à-plusieurs ne peut pas être utilisée dans une fields définition, car un champ doit être résolu en une seule valeur par ligne source.
• Une fonction d’agrégation unique doit référencer des colonnes d’une source. Vous pouvez appliquer l’arithmétique dans 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 frères de niveau supérieur peuvent combiner des cardinalités.
• Référencez une colonne dans une jointure imbriquée avec son chemin d’accès complet par le biais des noms de jointure, tels que orders.order_items.item_id.

Note

Lorsqu’une vue de métrique utilise une one_to_many jointure, ses matérialisations se qualifient uniquement pour une correspondance exacte. La correspondance de cumul n’est pas disponible. Voir la correspondance de cumul.

L’exemple suivant joint à une orders source pour customers que les mesures de commande soient agrégées cardinality: one_to_many sans dupliquer les lignes client :

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 d’informations conceptuelles et des exemples de jointure imbriquée et frère, consultez La cardinalité de jointure.

Optimiser les jointures avec rely

Utilisez le rely champ d’une jointure pour déclarer des garanties sur la relation utilisée par l’analyseur de requête lors de la planification des requêtes. Ces garanties permettent au moteur de planifier les requêtes 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 rely carte prend en charge les champs suivants :

Champ	Type	Description
at_most_one_match	Boolean	Optional. La valeur par défaut est false. Lorsque true, déclare qu’au plus une ligne de la table jointe correspond à chaque ligne de la source (une relation plusieurs-à-un qui ne se déclenche pas).

Avertissement

Définissez at_most_one_match: true uniquement lorsque la jointure est plusieurs-à-un. Cette relation n’est pas validée au moment de l’exécution. Si plusieurs lignes de la table jointe correspondent à une seule ligne source, les mesures (telles que SUM et COUNT) retournent des résultats incorrects.

L’exemple suivant active at_most_one_match une jointure plusieurs-à-un ordersà partir de customer . Les requêtes qui filtrent ou regroupent par attributs client bénéficient le plus :

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

Note

fields et dimensions sont des mots clés équivalents dans une définition d’affichage de métrique. fields est le terme préféré et est utilisé dans cette documentation. L’éditeur de faible code de l’Explorateur de catalogue étiquette ces colonnes Champs, mais le YAML qu’il génère utilise le dimensions mot clé. Les vues de métrique 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 d’affichage de métrique utilisées dans SELECT, WHEREet GROUP BY des clauses au moment de la requête. Chaque expression doit retourner une valeur scalaire. Les champs peuvent référencer des colonnes à partir des données sources ou des champs définis précédemment dans la vue métrique.

Un champ peut être :

• Colonne catégorielle ou de regroupement, telle qu’une région, un état ou un service.
• 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 SUM ou AVG.

Chaque définition de champ inclut les propriétés suivantes :

Property	Type	Description
name	String	Obligatoire pour les expressions de colonne explicites. Alias de colonne pour le champ. Omettez-le pour les expressions génériques, où Azure Databricks dérive les noms de la source. Consultez les champs et les mesures d’importation en bloc avec des caractères génériques.
expr	String	Obligatoire. Expression SQL qui peut référencer des colonnes à partir des données sources ou d’un champ défini précédemment. Il peut s’agir d’un caractère générique pour importer toutes les colonnes à partir de la source ou d’une table jointe. Consultez les champs et les mesures d’importation en bloc avec des caractères génériques.
comment	String	Optional. Description du champ. Apparaît dans le catalogue Unity et les outils de documentation.
display_name	String	Optional. Étiquette qui apparaît dans les outils de visualisation. Limitées à 255 caractères. Nécessite la spécification YAML 1.1. Consultez la disponibilité des fonctionnalités d’affichage des métriques.
format	Map	Optional. Spécification de format pour la façon dont les valeurs sont affichées. Nécessite la spécification YAML 1.1. Consultez les spécifications de format.
synonyms	Array	Optional. Autres noms pour les outils IA et BI pour découvrir le champ. Jusqu’à 10 synonymes, chacun limité à 255 caractères. Nécessite la spécification YAML 1.1. Voir Synonymes.

Avertissement

Les champs d’affichage de métrique de type chaîne sont toujours STRING, même lorsque la colonne source est CHAR ou VARCHAR. Étant donné que CHAR(n) le remplissage d’espace est perdu, les comparaisons peuvent retourner des résultats différents. Par exemple, column = 'COLLEGE' correspond à une CHAR(10) valeur dans la table source (qui est remplie d’espacement), mais pas dans le champ d’affichage des métriques.

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

Mesures

Les mesures sont des expressions qui produisent des résultats sans niveau prédéfinis d’agrégation. Ils doivent être exprimés à l’aide de fonctions d’agrégation. Pour référencer une mesure dans une requête, utilisez la MEASURE fonction. Les mesures peuvent référencer des colonnes de base dans les données sources, les champs définis précédemment ou les mesures définies précédemment.

Chaque définition de mesure inclut les champs suivants :

Champ	Type	Description
name	String	Obligatoire pour les expressions de mesure explicites. Alias de la mesure. Omettez-le pour les expressions génériques, où Azure Databricks dérive les noms de la source. Consultez les champs et les mesures d’importation en bloc avec des caractères génériques.
expr	String	Obligatoire. Expression SQL contenant une ou plusieurs fonctions d’agrégation. Il peut s’agir d’un caractère générique pour importer toutes les mesures à partir d’une source d’affichage des métriques. Consultez les champs et les mesures d’importation en bloc avec des caractères génériques.
comment	String	Optional. Description de la mesure. Apparaît dans le catalogue Unity et les outils de documentation.
display_name	String	Optional. Étiquette qui apparaît dans les outils de visualisation. Limitées à 255 caractères. Nécessite la spécification YAML 1.1. Consultez la disponibilité des fonctionnalités d’affichage des métriques.
format	Map	Optional. Spécification de format pour la façon dont les valeurs sont affichées. Nécessite la spécification YAML 1.1. Consultez les spécifications de format.
synonyms	Array	Optional. Autres noms pour les outils IA et BI pour découvrir la mesure. Jusqu’à 10 synonymes, chacun limité à 255 caractères. Nécessite la spécification YAML 1.1. Consultez la disponibilité des fonctionnalités d’affichage des métriques.
window	Array	Optional. Spécifications de fenêtre pour les agrégations fenêtrés, cumulatives ou semi-additives. Lorsqu’elle n’est pas spécifiée, la mesure se comporte comme un agrégat standard. Voir Dimensions de la fenêtre.

Consultez les fonctions d’agrégation pour obtenir la liste des fonctions d’agrégation.

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

Importer en bloc 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 fields ou measures une définition, vous pouvez utiliser un caractère générique (*) dans le expr champ pour importer toutes les colonnes à partir de la source ou d’une table jointe sans lister chacune d’elles. Cela est utile lorsque vous souhaitez qu’une vue de métrique expose chaque colonne à partir d’une ressource en amont, comme SELECT * dans une vue standard. Azure Databricks étend le caractère générique aux colonnes concrètes lorsque vous créez ou remplacez la vue de métrique et dérive chaque nom de colonne du nom de colonne source.

Comme les définitions de colonnes explicites, les expressions génériques sont développées lorsque vous créez l’affichage des métriques. Pour récupérer des colonnes ajoutées à la source ultérieurement, recréez l’affichage de métrique avec CREATE OR REPLACE ou ALTER.

Les caractères génériques prennent en charge les formulaires suivants :

Syntax	Description
source.*	Importez toutes les colonnes à partir de la source de l’affichage des métriques.
<join>.*	Importez toutes les colonnes d’une table jointe, référencées par son nom de jointure. Les jointures imbriquées utilisent le chemin d’accès complet, par customer.nation.*exemple .
<target>.* EXCEPT (col1, col2, ...)	Importez toutes les colonnes de la cible, à l’exception de celles répertoriées.
<target>.<struct>.*	Développez les champs d’une STRUCT colonne en colonnes distinctes.

Les règles suivantes s’appliquent aux expressions génériques :

• Omettez le name champ. Azure Databricks dérive les noms de colonnes de la source. name Il n'est donc pas autorisé sur une expression générique.
• Les métadonnées sémantiques ne sont pas autorisées sur une expression générique. Ne définissez commentpas , display_nameou formatsynonyms sur un caractère générique. Pour ajouter des métadonnées à une colonne spécifique, excluez-la du caractère générique et EXCEPT définissez-la explicitement.
• Dans une measures définition, un caractère générique importe des mesures uniquement à partir d’une source d’affichage des métriques. Les tables de base n’ont aucune mesure. Par conséquent, 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ères génériques par son nom dérivé dans une expression ou fields une version ultérieuremeasures. Référencez plutôt la colonne source avec son chemin d’accès complet.

Résoudre les collisions de noms

Lorsque vous importez des colonnes à partir de plusieurs sources avec un caractère générique, les colonnes qui partagent un nom (par exemple id ) dateentrent 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 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 explicitement une colonne 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 fenêtre

Important

Cette fonctionnalité est expérimentale.

Le window champ définit des agrégations fenêtrés, cumulatives ou semi-additives pour les mesures. Pour plus d’informations sur les mesures de fenêtre et les cas d’usage, consultez Les mesures de fenêtre.

Chaque spécification de fenêtre comprend les champs suivants :

Champ	Type	Description
order	String	Obligatoire. Champ qui détermine l’ordre de la fenêtre. (1)
range	String	Obligatoire. Étendue de la fenêtre. Consultez les valeurs prises en chargerange.
semiadditive	String	Obligatoire. Méthode d’agrégation. Valeurs prises en charge : first ou last.
offset	String	Optional. Nécessite databricks Runtime 18.1 et la spécification YAML version 1.1 ou ultérieure. Déplace le cadre de la fenêtre vers l’arrière ou vers l’avant le long du order champ par un intervalle fixe. La valeur est de la forme <n> <period>, où n est un entier signé (négatif regarde vers l’arrière, positif vers l’avant) et period est l’un des day, , days, month, months, year, ou years. Exemples : -12 month, 1 year, -3 days, 7 day. Le order champ doit être une colonne de date ou d’horodatage. offset n’a aucun effet sur range: all. Si le cadre décalé se trouve en dehors des données disponibles, la mesure est évaluée à NULL. Pour obtenir des exemples d’utilisation et de travail, consultez Comment offset décaler le cadre de la fenêtre.

(1) Le champ référencé doit être déterministe. Les expressions non déterministes telles que rand(), uuid()ou current_timestamp() produisent un ordre de fenêtre imprévisible et peuvent entraîner des résultats d’agrégation incorrects.

Valeurs de range prises en charge

• current: lignes où la valeur de classement de la fenêtre est égale à la valeur de la ligne d’ancrage.
• cumulative: toutes les lignes où la valeur de classement des fenêtres est inférieure ou égale à la valeur de la ligne d’ancrage.
• trailing <value> <unit> [inclusive | exclusive]: lignes de la ligne d’ancrage descendante par les unités de temps spécifiées, par exemple trailing 7 day. Le modificateur facultatif inclusiveexclusive nécessite Databricks Runtime 18.1 et la spécification YAML version 1.1 ou ultérieure, et contrôle si la ligne d’ancrage est incluse dans la fenêtre. La valeur par défaut est exclusive. Voir Inclure ou exclure la ligne d’ancrage.
• leading <value> <unit> [inclusive | exclusive]: lignes de la ligne d’ancrage en avance par les unités de temps spécifiées, par exemple leading 3 month. Le modificateur facultatif inclusiveexclusive nécessite Databricks Runtime 18.1 et la spécification YAML version 1.1 ou ultérieure, et contrôle si la ligne d’ancrage est incluse dans la fenêtre. La valeur par défaut est exclusive. Voir Inclure ou exclure la ligne d’ancrage.
• all: toutes les lignes, quelle que soit la valeur de classement de la fenêtre.

Exemple de mesure de fenêtre

L’exemple suivant calcule un nombre de 7 jours propagé 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

Le materialization champ configure l’accélération automatique des requêtes à l’aide de vues matérialisées. Pour plus d’informations sur le fonctionnement de la matérialisation, les exigences et les meilleures pratiques, consultez Matérialisation pour les vues de métriques.

Note

Vous ne pouvez pas matérialiser une vue de métrique qui définit des paramètres.

Le materialization champ inclut les champs de niveau supérieur suivants :

Champ	Type	Description
schedule	String	Optional. Planification d’actualisation. Utilise la même syntaxe que la clause schedule sur les vues matérialisées. En cas d’omission, les matérialisations sont actualisées uniquement manuellement. Pour déclencher une actualisation manuelle, consultez Actualisation manuelle. La clause TRIGGER ON UPDATE n'est pas prise en charge.
mode	String	Obligatoire. Cette propriété doit être définie sur relaxed.
materialized_views	Array	Obligatoire. Liste des vues matérialisées à matérialiser. Chaque entrée nécessite les champs décrits ci-dessous.

Chaque entrée materialized_views inclut les champs suivants :

Champ	Type	Description
name	String	Obligatoire. Nom de la matérialisation.
type	String	Obligatoire. Type de matérialisation. Valeurs prises en charge : aggregated (nécessite dimensions, ou measuresles deux) ou unaggregated. unaggregated Une seule entrée est autorisée par vue de métrique. Les entrées non agrégées n’utilisent pas les champs ou measures les dimensions champs.
dimensions	Array	Conditionnel. Liste des noms de champs à matérialiser, en utilisant le dimensions mot clé même si votre définition de niveau supérieur utilise fields. Obligatoire si type c’est aggregated le cas et non measures spécifié.
measures	Array	Conditionnel. Liste des noms de mesures à matérialiser. Obligatoire si type c’est aggregated le cas et non dimensions spécifié.
cluster_by	Object	Optional. Colonnes de clustering pour la matérialisation, équivalentes à la CLUSTER BY clause sur une vue matérialisée. Spécifiez avec une liste de noms de colonnes ou définissez colsauto: true pour permettre à Databricks de choisir automatiquement les colonnes de clustering.
partition_by	Array	Optional. Liste de colonnes à partitionner la matérialisation par, équivalente à la PARTITION BY clause d’une vue matérialisée.

Note

Le bloc de matérialisation utilise le dimensions: mot clé plutôt que fields:. Utilisez cette option dimensions: lors de la description des champs pour 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: 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

Références de nom de colonne

Lorsque vous référencez des noms de colonnes qui contiennent des espaces ou des caractères spéciaux dans des expressions YAML, placez le nom de colonne dans les backticks. Si l’expression commence par un accent grave et sert directement de valeur YAML, mettez l’expression entière entre guillemets doubles. Les valeurs YAML valides ne peuvent pas commencer par un accent grave.

Exemples de mise en forme

Utilisez les exemples suivants pour apprendre à mettre en forme YAML correctement dans les scénarios courants.

Référencer un nom de colonne

Les exemples suivants montrent comment mettre en forme des références de colonne en fonction des caractères qu’ils contiennent.

Aucun espace

Colonne source : revenue

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

Utilisez des guillemets doubles, des guillemets simples ou pas de guillemets autour du nom de la colonne.

Nom de colonne avec des espaces

Colonne source : `First Name`

expr: '`First Name`'

Utilisez des accents graves comme caractères d’échappement des espaces. Placez l’expression entière entre guillemets doubles.

Noms de colonnes avec des espaces dans une expression SQL

Colonnes sources : `First Name`, `Last Name`

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

Si l’expression ne commence pas par un backtick, les guillemets doubles ne sont pas obligatoires.

Nom de colonne contenant des guillemets

Colonne source : "name"

expr: '`"name"`'

Utilisez des backticks pour échapper les guillemets doubles dans le nom de la colonne. Placez l’expression entre guillemets simples.

Expressions avec deux-points

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

Note

YAML interprète les deux-points sans guillemets comme des séparateurs clé-valeur. Utilisez toujours des guillemets doubles autour des expressions qui incluent des points-virgules.

Expressions multilignes

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

Note

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 une analyse correcte.

Mise à niveau vers YAML 1.1

La mise à niveau d’une vue de métrique vers la version 1.1 de la spécification YAML nécessite des soins, car les commentaires sont gérés différemment des versions antérieures.

Types de commentaires

• Commentaires YAML (#) : commentaires inline ou monolignes écrits directement dans le fichier YAML.
• Commentaires du catalogue Unity : commentaires stockés dans le catalogue Unity pour l’affichage des métriques ou ses colonnes. Elles sont distinctes des commentaires YAML.

Considérations relatives à la mise à niveau

Sélectionnez le chemin de mise à niveau qui correspond à la façon dont vous souhaitez gérer les commentaires dans votre vue de métrique.

Option 1 : Conserver les commentaires YAML à l’aide de notebooks ou de l’éditeur SQL

Si votre vue de métrique contient des commentaires YAML (#) que vous souhaitez conserver, procédez comme suit :

1. Utilisez la ALTER VIEW commande dans un bloc-notes ou un éditeur SQL.
2. Copiez la définition YAML d’origine dans la $$..$$ section après AS. Remplacez la valeur de version par 1.1.
3. Enregistrez la vue des métriques.

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

Avertissement

L’exécution ALTER VIEW supprime les commentaires du catalogue Unity, sauf s’ils sont explicitement inclus dans les comment champs de la définition YAML. Pour conserver les commentaires affichés dans le catalogue Unity, consultez l’option 2.

Option 2 : Conserver les commentaires du catalogue Unity

Note

Les instructions suivantes s’appliquent uniquement lors de l’utilisation de la ALTER VIEW commande dans un notebook ou un éditeur SQL. Si vous mettez à niveau votre vue 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 du catalogue Unity.

1. Copiez tous les commentaires du catalogue Unity dans les champs appropriés comment de votre définition YAML. Remplacez la valeur de version par 1.1.
2. Enregistrez la vue des métriques.

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 connaître l’historique des versions de spécification YAML et les exigences minimales du runtime pour chaque fonctionnalité, consultez la disponibilité des fonctionnalités d’affichage des métriques.