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 de vue métrique

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, voir Déclarer la clé primaire, la clé étrangère et les contraintes uniques et Optimiser les requêtes avec RELY une 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 joint.
  • USING clause : Liste les colonnes portant le même nom à la fois dans la table mère et dans 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 joints 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)

Domaines

Note

fields et dimensions sont des mots-clés équivalents dans une définition de vue métrique. fields est le terme privilégié et est utilisé dans toute 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 Optionnel sur Databricks Runtime 19 et supérieur. Alias de colonne pour le champ. Si omis, Azure Databricks dérive le nom de expr. Voir Dériver les noms des colonnes à partir d’expressions. Pour les expressions imprévisibles, name ce n’est pas autorisé. 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 Optionnel sur Databricks Runtime 19 et supérieur. Alias de la mesure. Si omis, Azure Databricks dérive le nom de expr. Voir Dériver les noms des colonnes à partir d’expressions. Pour les expressions imprévisibles, name ce n’est pas autorisé. 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']

Dériver les noms de colonnes à partir d’expressions

S’applique à : Databricks SQL et Databricks Runtime 19 et supérieurs

Si vous omettez name une définition de champ ou de mesure, Azure Databricks dérive le nom de la colonne à exprpartir de . Pour les expressions complexes, utilisez un nom explicite pour faciliter la requête de la colonne. Par exemple, ajouter name: total_revenue à la définition de la mesure pour la requête comme MEASURE(total_revenue) au lieu de MEASURE(`SUM(o_totalprice)`).

Les règles suivantes déterminent le nom :

  • Une référence directe à une colonne utilise son identifiant final. Par exemple, source.o_orderstatus produit o_orderstatus.
  • Un CAST élément juste autour d’une référence de colonne conserve cet identifiant. Par exemple, CAST(source.o_totalprice AS BIGINT) produit o_totalprice.
  • D’autres expressions utilisent un nom dérivé de l’expression. Par exemple, SUM(o_totalprice) produit SUM(o_totalprice). Le nom préserve la fonction et les majuscules d’identification et supprime les espaces blancs entre les jetons d’expression. Par exemple, SUM(a + b) produit SUM(a+b).

Contrairement aux noms importés par wildcard, les noms dérivés peuvent être référencés dans des expressions de champs ou de mesures ultérieures. On se référe à un corps comme o_orderstatus et à une mesure comme MEASURE(`SUM(o_totalprice)`).

La définition suivante omet les noms d’un champ et d’une mesure :

version: 1.1
source: samples.tpch.orders

fields:
  - expr: source.o_orderstatus

measures:
  - expr: SUM(o_totalprice)

Si vous créez une vue métrique nommée orders_metrics avec cette définition, utilisez DESCRIBE TABLE pour inspecter ses noms de colonnes :

DESCRIBE TABLE orders_metrics;

Incluez des noms dérivés qui contiennent de la ponctuation dans les backticks lorsque vous les interrogez :

SELECT o_orderstatus, MEASURE(`SUM(o_totalprice)`)
FROM orders_metrics
GROUP BY o_orderstatus;

Les noms doivent être uniques selon les champs et mesures, en ignorant les cas. Si des noms dérivés entrent en collision, spécifier des noms explicites et uniques. Un vide name explicitement est invalide.

Champs et mesures d’importation en masse avec 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

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. La valeur numérique dans une trailing plage ou leading peut être un paramètre entier au lieu d’un littéral, donc un appelant transmet la taille de la fenêtre au moment de la requête. Voir « Passer une taille de fenêtre » comme paramètre.
semiadditive String Optionnel sur Databricks Runtime 19 et supérieur. Méthode d’agrégation. Valeurs prises en charge : first ou last. La valeur par défaut est last.
offset Chaîne ou entier Optional. Nécessite la spécification YAML version 1.1 ou supérieure. Il déplace le cadre de la fenêtre vers l’avant ou l’arrière sur le order champ d’une quantité fixe. Une valeur négative regarde en arrière et une valeur positive regarde vers l’avenir. offset Prend en charge deux formes. Un décalage daté a la forme <n> <period>, où period est l’un des day, days, month, months, year, ou years, par exemple -12 month ou 1 year. Un décalage daté nécessite que le order champ soit une colonne de date ou d’horodatage et nécessite Databricks Runtime 18.1 ou supérieur. Un décalage numérique est un entier sans unité signé, tel que -1 ou 3, qui avance le référentiel de ce nombre de positions sur une colonne entière order consécutive. Un décalage numérique nécessite Databricks d’exécution 19 ou plus. 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. L’entier signé peut être un paramètre entier au lieu d’un littéral, donc un appelant transmet le décalage au moment de la requête. Le signe doit faire partie de la valeur du paramètre, et non être écrit avant le nom du paramètre. Voir « Passer une taille de fenêtre » comme paramètre. Pour des exemples datés, voir Comment offset décale le cadre de la fenêtre. Pour des exemples d’index numérique, voir Mesures de fenêtre sur une colonne d’index numérique.

(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 d’ordre des fenêtres est égale à la valeur de la ligne d’ancre.
  • cumulative: Toutes les lignes où la valeur d’ordre de la fenêtre est inférieure ou égale à la valeur de la ligne d’ancre.
  • trailing <value> [<unit>] [inclusive | exclusive]: Lignes de la ligne d’ancrage reculant par le montant spécifié, par trailing 7 dayexemple . 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 allant vers l’avant par le montant spécifié, par leading 3 monthexemple . 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 d’ordre de la fenêtre.

<unit>est l’une des day: , monthdays, months, year, ou years, et nécessite que le order champ soit une colonne de date ou d’horodatage. Ne <unit> pas écrire un intervalle sans unité tel que trailing 3 ou leading 2, qui avance de ce nombre de positions sur une colonne entière order consécutive au lieu d’une unité de temps. Une plage sans unité nécessite un Databrick d’exécution 19 ou plus. Voir Mesures de fenêtre dans une colonne d’index numérique.

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

Passer une taille de fenêtre comme paramètre

Au lieu de coder durement la valeur numérique dans un trailing ou leadingrange dans un offset, vous pouvez référencer un paramètre, de sorte qu’un appelant transmet la taille de la fenêtre lorsqu’il interroge la vue métrique. Cela nécessite un entrepôt SQL ou une autre ressource de calcul exécutant Databricks Runtime 18.2 ou supérieur.

Les règles suivantes s’appliquent à un paramètre utilisé comme taille de fenêtre :

  • Les paramètres data_type doivent être intitulés, tels que int, smallint, ou bigint.
  • La valeur doit être un nom de paramètre nu, et non une expression. Par exemple, utilisez trailing window_size day et non trailing window_size + 1 day. Vous ne pouvez pas non plus écrire un signe avant le nom du paramètre, comme -window_size dans un offsetfichier . Pour passer un décalage négatif, placez le signe dans la valeur du paramètre.
  • Le paramètre ne peut pas être nommé d’après un mot-clé fenêtre, tel qu’un type de plage (trailing, leading), un point (day, month, year), un mot-clé d’inclusivité (inclusive, exclusive), ou offset.
  • L’unité reste littérale. Vous ne pouvez paramétrer que la magnitude numérique, pas la période.

L’exemple suivant définit un window_size paramètre et le référencent dans une trailing plage, de sorte que chaque appelant choisit le nombre de jours dans la fenêtre roulante :

version: 1.1
source: samples.tpch.orders

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

fields:
  - name: order_date
    expr: o_orderdate

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

Pour interroger une vue métrique qui définit des paramètres, voir Interroger une vue métrique avec des paramètres.

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 dimensions les measures 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 PARTITIONED BY clause d’une vue matérialisée. On ne peut pas utiliser partition_by et cluster_by retrouver la même matérialisation.
refresh_policy String Optional. Nécessite la version 1.1 de la spécification YAML et Databricks Runtime 18 LTS ou supérieure. Contrôle si la matérialisation se rafraîchit progressivement. Valeurs prises en charge : auto (par défaut), incremental, incremental strict, et full. Les valeurs ne sont pas sensibles à la majuscule. Écrivez incremental strict avec un espace. Les valeurs se comportent comme la REFRESH POLICY clause sur une vue matérialisée. Voir la politique de rafraîchissement. Avec incremental ou incremental strict, créer ou modifier la vue métrique échoue avec METRIC_VIEW_MATERIALIZATION_NOT_INCREMENTALIZABLE si la matérialisation ne peut pas se rafraîchir progressivement.

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

materialization:
  schedule: every 6 hours
  mode: relaxed

  materialized_views:
    - name: baseline
      type: unaggregated
      refresh_policy: incremental strict
      # 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

Références de noms 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 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 multi-lignes

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.

Mettre à 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 en ligne ou à ligne unique écrits directement dans le fichier YAML.
  • Commentaires du catalogue Unity : commentaires stockés dans le catalogue Unity pour la vue métrique ou ses colonnes. Elles sont distinctes des commentaires YAML.

Considérations de 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.