Spécification du modèle sémantique Cortex Analyst¶

Pourquoi utiliser des modèles sémantiques ?¶

Cortex Analyst permet aux utilisateurs d’effectuer des requêtes sur les données de Snowflake en utilisant la langue naturelle. Cependant, les utilisateurs professionnels utilisent souvent une langue incompatible avec le schéma. Alors que les utilisateurs précisent dans leurs questions des termes commerciaux spécifiques à un domaine, les données sous-jacentes sont souvent stockées à l’aide d’abréviations techniques. Par exemple, « CUST » est souvent utilisé pour les clients. Ce décalage, combiné à l’absence de contexte sémantique du schéma, fait qu’il est difficile pour Cortex Analyst de fournir des réponses précises.

Les modèles sémantiques mappent la terminologie de l’entreprise aux schémas des bases de données et ajoutent une signification contextuelle. Par exemple, lorsqu’un utilisateur demande « le revenu total du mois dernier », le modèle sémantique peut définir le « revenu » comme étant le revenu net et le « mois dernier » comme étant le mois civil précédent. Ce mappage aide Cortex Analyst à comprendre l’intention de l’utilisateur et à fournir des réponses précises.

Note

Les modèles sémantiques sont considérés des métadonnées.

Concepts clés¶

Note

Dans cette rubrique, les objets de la base de données sont appelés objets « physiques », tandis que les objets du modèle sémantique sont appelés « logiques ».

La structure et les concepts du modèle sémantique sont similaires à ceux des schémas de base de données, mais les modèles sémantiques vous permettent de fournir plus d’informations sémantiques sur vos données.

Concepts de la zone sémantique¶

La structure et les concepts qui définissent la zone sémantique logique sont similaires à ceux qui définissent la zone physique de la base de données. Les types de concepts pour une zone sémantique sont les suivants :

Logique au niveau de la table
Au niveau du modèle
Contexte supplémentaire

Concepts de modèles sémantiques montrant le modèle sémantique en haut.

Concepts logiques au niveau de la table¶

Une table logique est un concept fondamental du modèle sémantique de Snowflake. Elle représente soit une table de base de données physique, soit une vue. Elle correspond généralement à des entités commerciales (telles que des clients, des commandes ou des fournisseurs) ou à des dimensions (telles que le lieu ou le temps). chaque ligne d’une table logique représente généralement une instance unique de l’entité, par exemple l’ID d’un client.

Les tables logiques contiennent les types de colonnes suivants :

Faits (données quantitatives sur les événements commerciaux)
Dimensions (qui, quoi, où et comment)
Heure (moment où l’événement s’est produit)
Filtres associés à la table logique pour permettre de limiter les résultats de la requête à des sous-ensembles de données spécifiques.

Vous pouvez définir des métriques en utilisant des agrégations ou des combinaisons d’autres objets logiques.

Les exemples suivants utilisent le schéma TPC-H, qui comprend la table des faits LINEITEM. Pour une mise en œuvre complète de YAML, téléchargez le fichier snow_tpch.

Schéma TPC-H montrant la relation entre la table des faits LINEITEM et les tables DIMENSIONS.

Tous les exemples suivants au niveau de la table logique appartiennent à la table logique order_lineitems.

tables:
  - name: order_lineitems
    description: >
      The order line items table contains detailed information about each item within an
      order, including quantities, pricing, and dates.

    base_table:
      database: SNOWFLAKE_SAMPLE_DATA
      schema: TPCH_SF1
      table: LINEITEM
    primary_key:
      columns:
        - order_key
        - order_lineitem_number

Copy

Une dimension représente des données catégoriques qui fournissent un contexte aux faits, tels que des informations sur le produit, le client ou le lieu. Les dimensions contiennent généralement des valeurs textuelles descriptives, telles que des noms de produits ou des adresses de clients. Elles sont utilisées pour filtrer, grouper et étiqueter les faits dans les analyses et les rapports.

Une dimension temporelle fournit un contexte temporel pour l’analyse des faits sur différentes périodes. Elle permet de suivre les métriques sur des intervalles de temps spécifiques (dates, mois, années) et prend en charge des analyses telles que l’identification des tendances et les comparaisons d’une période à l’autre.

time_dimensions:
  - name: shipment_duration
    synonyms:
      - "shipping time"
      - "shipment time"
    description: The time it takes for items to be shipped.

    expr: DATEDIFF(day, lineitem.L_SHIPDATE, lineitem.L_RECEIPTDATE)
    data_type: NUMBER
    unique: false

Copy

Les faits sont des données quantitatives et mesurables qui fournissent le contexte des analyses. Les faits représentent des valeurs numériques liées aux processus commerciaux, telles que les ventes, les coûts ou les quantités. Un fait est un concept non agrégé au niveau de la ligne.

# Fact columns in the logical table.
facts:
  - name: net_revenue
    synonyms:
      - "revenue after discount"
      - "net sales"
    description: Net revenue after applying discounts.

    expr: lineitem.L_EXTENDEDPRICE * (1 - lineitem.L_DISCOUNT)
    data_type: NUMBER

Copy

Les faits peuvent être rendus privés (accessibles dans le modèle sémantique, mais pas par les utilisateurs finaux) en définissant le champ access_modifier sur private_access. Par défaut, les faits sont publics (accessibles par les utilisateurs).

Un filtre est une condition qui limite les résultats de la requête à des sous-ensembles de données spécifiques en fonction de critères tels que la période, le lieu ou la catégorie.

- name: north_america
  synonyms:
    - "NA"
    - "North America region"
  description: >
    Filter to restrict data to orders from North America.
  comments: Used for analysis focusing on North American customers.
  expr: nation.N_NAME IN ('Canada', 'Mexico', 'United States')

Copy

Une métrique est une mesure quantifiable de performance commerciale exprimée par une formule SQL. Vous pouvez utiliser les métriques comme indicateurs clés de performance (KPIs) dans les rapports et les tableaux de bord. Vous pouvez calculer deux types de métriques :

Métriques régulières valeurs agrégées (à l’aide de fonctions telles que SUM ou AVG) sur une colonne de faits.
Les métriques dérivées sont calculées à partir de métriques existantes, en utilisant des opérations arithmétiques telles que l’addition ou la division.

Définissez les métriques à leur niveau le plus granulaire pour l’agrégation à des niveaux supérieurs. Par exemple, définissez total_revenue au niveau de l’élément de ligne pour permettre l’agrégation par client, fournisseur ou région.

L’exemple suivant montre deux calculs de métriques régulières : un calcul simple et un calcul plus complexe. Ils sont définis dans une définition table, leur portée est donc limitée à cette table logique.

metrics:

    # Simple metric referencing objects from the same logical table
    - name: total_revenue
      expr: SUM(lineitem.l_extendedprice * (1 - lineitem.l_discount))

    # Complex metric referencing objects from multiple logical tables.
    # The relationships between tables have been defined below.
    - name: total_profit_margin
      description: >
                  The profit margin from orders. This metric is not additive
                  and should always be calculated directly from the base tables.
      expr: (SUM(order_lineitems.net_revenue) -
            SUM(part_suppliers.part_supplier_cost * order_lineitems.lineitem_quantity))
            / SUM(order_lineitems.net_revenue)

Copy

Astuce

Les métriques peuvent être rendues privées (accessibles dans le modèle sémantique, mais pas par les utilisateurs finaux) en définissant le champ access_modifier sur private_access. Par défaut, les métriques sont publiques (accessibles par les utilisateurs).

Références autorisées¶

Expressions for dimensions, facts, filters, or regular table-scoped metrics can reference:

Colonnes physiques de leur propre table de base
Colonnes logiques au sein d’une même table logique
Colonnes logiques provenant d’autres tables logiques du modèle sémantique

Les métriques dérivées au niveau du modèle peuvent faire référence à des métriques définies dans n’importe quelle table logique du modèle sémantique ou à d’autres métriques dérivées.

Note

Les expressions ne peuvent pas faire référence à des colonnes physiques d’autres tables physiques.

Concepts au niveau du modèle¶

Les relations connectent les tables logiques par des jointures sur des clés partagées. Par exemple, il peut y avoir une relation entre les tables clients et commandes par le biais d’une jointure sur la colonne customer_id. Vous pouvez utiliser des jointures pour analyser les données des commandes avec les attributs des clients.

relationships:

  # Relationship between orders and lineitems
  - name: order_lineitems_to_orders
    left_table: order_lineitems
    right_table: orders
    relationship_columns:
      - left_column: order_key
        right_column: order_key
    join_type: left_outer
    relationship_type: many_to_one

  # Relationship between lineitems and partsuppliers
  - name: order_lineitems_to_part_suppliers
    left_table: order_lineitems
    right_table: part_suppliers
    # The relationship requires equality of multiple columns from each table
    relationship_columns:
      - left_column: part_key
        right_column: part_key
      - left_column: supplier_key
        right_column: supplier_key
    join_type: left_outer
    relationship_type: many_to_one

Copy

Un référentiel de requêtes vérifié (VQR) est un ensemble de questions et de requêtes SQL correspondantes dont l’exactitude a été vérifiée. Vous pouvez utiliser les requêtes pour améliorer la précision des résultats de Cortex Analyst.

Vous pouvez utiliser Instructions personnalisées dans Cortex Analyst pour mieux contrôler la génération de requêtes SQL par Cortex Analyst. Dans les instructions personnalisées, vous fournissez au LLM le contexte unique de votre entreprise.

Les modèles sémantiques de Cortex Analyst sont spécifiés en YAML. Le modèle fournit les informations sémantiques nécessaires pour répondre aux questions en langue naturelle avec une grande précision.

Format YAML¶

Le YAML est équilibré entre la lisibilité humaine et la précision. Les utilisateurs professionnels peuvent le comprendre tandis que les ingénieurs de données et les analystes peuvent définir clairement des concepts techniques.

La syntaxe générale d’un modèle sémantique Cortex Analyst est la suivante :

# Name and description of the semantic model.
name: <name>
description: <string>
comments: <string>

# Logical table-level concepts

# A semantic model can contain one or more logical tables.
tables:

  # A logical table on top of a base table.
  - name: <name>
    description: <string>


    # The fully qualified name of the base table.
    base_table:
      database: <database>
      schema: <schema>
      table: <base table name>

    # Dimension columns in the logical table.
    dimensions:
      - name: <name>
        synonyms: <array of strings>
        description: <string>

        expr: <SQL expression>
        data_type: <data type>
        unique: <boolean>
        cortex_search_service:
          service: <string>
          literal_column: <string>
          database: <string>
          schema: <string>
        is_enum: <boolean>


    # Time dimension columns in the logical table.
    time_dimensions:
      - name: <name>
        synonyms:  <array of strings>
        description: <string>

        expr: <SQL expression>
        data_type: <data type>
        unique: <boolean>

    # Fact columns in the logical table.
    facts:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        access_modifier: < public_access | private_access >  # Default is public_access

        expr: <SQL expression>
        data_type: <data type>


    # Regular metrics scoped to the logical table.
    metrics:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        access_modifier: < public_access | private_access >  # Default is public_access

        expr: <SQL expression>


    # Commonly used filters over the logical table.
    filters:
      - name: <name>
        synonyms: <array of strings>
        description: <string>

        expr: <SQL expression>

# Model-level concepts

# Relationships between logical tables
relationships:
  - name: <string>

    left_table: <table>
    right_table: <table>
    relationship_columns:
      - left_column: <column>
        right_column: <column>
      - left_column: <column>
        right_column: <column>
    join_type: <left_outer | inner>
    relationship_type: < one_to_one | many_to_one >

# Derived metrics scoped to the semantic model
metrics:
  - name: <name>
    synonyms: <array of strings>
    description: <string>
    access_modifier: < public_access | private_access >  # Default is public_access

    expr: <SQL expression>


# Additional context concepts

#  Verified queries with example questions and queries that answer them
verified_queries:
  - name:        # A descriptive name of the query.

    question:    # The natural language question that this query answers.
    verified_at: # Optional: Time (in seconds since the UNIX epoch, January 1, 1970) when the query was verified.
    verified_by: # Optional: Name of the person who verified the query.
    use_as_onboarding_question:  # Optional: Marks this question as an onboarding question for the end user.
    sql:                         # The SQL query for answering the question

Copy

Pour un exemple de spécification, voir le fichier :download :snow_tpch.yaml </samples/cortex/cortex-analyst/snow_tpch.yaml>.

Créer un modèle sémantique à l’aide du générateur de modèles¶

Utilisez le générateur de modèles sémantique pour créer un modèle sémantique à partir de vos tables. Au lieu de créer manuellement un modèle sémantique avec votre propre spécification YAML, vous pouvez utiliser le générateur de modèles dans l”Snowsight pour gagner du temps. Le processus de création d’un modèle sémantique consiste à effectuer les opérations suivantes :

Fournir une description avec des informations de base sur le modèle.
Fournir la source de données que vous utilisez pour créer le modèle. Vous devez fournir au moins une table ou une vue.
Sélection des colonnes que vous utilisez pour créer le modèle.

Pour commencer à créer le modèle, accédez à la page Let’s Create a Semantic Model :

Dans Snowsight, sélectionnez AI & ML.
À côté de Cortex Analyst, sélectionnez Try.
Choisissez Create new.

Vous avez ouvert la page de description du générateur de modèles sémantiques. Pour créer un modèle sémantique, procédez comme suit :

Pour Description, spécifiez des informations sur le modèle sémantique. Vous devez fournir le nom du fichier, son emplacement et le nom du modèle. Vous pouvez également fournir une description du contexte des données.
(Facultatif) Pour User Questions, indiquez les types de questions que les utilisateurs peuvent poser sur les données. Le générateur de modèles utilise les informations que vous fournissez dans le champ pour suggérer des tables, des vues et des colonnes que vous pouvez utiliser pour créer le modèle.
Pour Select Data (Table/View), indiquez le fournisseur de données que vous utilisez pour créer le modèle sémantique. Vous devez fournir au moins une table ou une vue. Il n’y a pas de limite au nombre de tables ou de vues que vous pouvez spécifier, mais nous vous recommandons de ne pas en utiliser plus de 10 pour le modèle sémantique.
Pour Select Columns, sélectionnez les colonnes que vous utilisez pour créer le modèle sémantique. Vous pouvez sélectionner toutes les colonnes ou des colonnes spécifiques. Pour des raisons de performance, nous vous recommandons de ne pas utiliser plus de 50 colonnes.

Après avoir créé le modèle, enregistrez-le dans une zone de préparation. Pour sauvegarder, sélectionnez Save dans le coin supérieur droit de l’écran. Si vous devez apporter d’autres modifications, vous pouvez éditer le modèle en utilisant l”Snowsight ou en éditant directement le fichier YAML.

Ouvrir un modèle sémantique existant¶

Après avoir créé un modèle sémantique, vous pouvez l’ouvrir dans l”Snowsight. Pour ouvrir un modèle sémantique, procédez comme suit :

Sélectionnez Open semantic model.
Sélectionnez Open.
Sélectionnez Select from stage.
Sélectionnez la base de données et le schéma.
Cliquez en dehors de la boîte de dialogue.
Sélectionnez la zone de préparation où vous avez enregistré le fichier.
Sélectionnez Ouvrir.

Note

If you don’t see your semantic model within your stage, try refreshing the list of models, not the page.

Conseils pour créer un modèle sémantique¶

Organisez votre fichier YAML par domaine d’activité ou par thème
- Structurez vos fichiers YAML à aligner sur des domaines ou des sujets commerciaux spécifiques, en gardant le champ d’application ciblé. Par exemple, créez des modèles sémantiques distincts pour l’analyse des ventes et l’analyse marketing.
- Adaptez vos cas d’utilisation en fonction du public cible, des questions attendues ou KPIs, et les données requises. Des cas d’utilisation bien définis conduisent à des modèles sémantiques plus riches et à une récupération de données plus efficace.
Réfléchissez du point de vue de l’utilisateur final
- Identifiez les questions clés que les utilisateurs sont susceptibles de poser sur le sujet et incluez uniquement les tables et les colonnes nécessaires pour répondre à ces questions.
- Utilisez des noms et des synonymes similaires au vocabulaire utilisé par vos utilisateurs finaux.
- Incluez des détails importants dans les champs de description qui seraient utiles à quelqu’un qui écrit des requêtes sur cet ensemble de données pour la première fois, comme le fuseau horaire d’une colonne DATETIME.
Capturez des calculs complexes

Incorporez des requêtes plus difficiles ou spécifiques à l’entreprise dans des expressions.
Utilisez des tables larges au lieu de tables longues

Si vous avez un tableau avec des colonnes telles que « métrique » et « valeur », aplatissez la table de sorte que chaque métrique soit une colonne. Cette approche fournit au modèle plus d’informations sémantiques sur chaque métrique.
Examinez les descriptions générées automatiquement

Si vous utilisez le générateur de modèles sémantiques, il tente de générer automatiquement des descriptions pour vos tables et colonnes. Examinez toujours ces descriptions pour vous assurer qu’elles sont raisonnables et pertinentes ; apportez les modifications nécessaires.
Commencez simplement et développez progressivement

Un fichier sémantique bien défini garantit une plus grande précision et exactitude des résultats. Commencez avec un petit nombre de tables et de colonnes et développez le modèle sémantique YAML progressivement pour couvrir davantage de types de questions. Rappelez-vous que la création de YAML est un processus continu.
Incluez les requêtes vérifiées

Un référentiel de requêtes vérifié (VQR), qui est un ensemble de questions en anglais simple et de requêtes qui y répondent, peut aider à améliorer l’exactitude et la fiabilité des résultats.

Limitations connues¶

Cortex Analyst impose une limite de taille de 1 MB au fichier du modèle sémantique afin de restreindre la taille des entrées de l’API.

Spécification¶

Cette section contient des spécifications détaillées pour les concepts clés décrits dans les sections précédentes.

Modèle sémantique¶

Un modèle sémantique représente un ensemble de tables. Le modèle contient des descriptions de tables, chacun contenant des descriptions d’aspects spécifiques de la table. Chaque table décrite dans le modèle correspond à une table de base physique dans Snowflake.

Elle contient les domaines suivants :

Nécessaire

name

Un nom descriptif pour ce modèle sémantique.

Doit être unique et suivre les exigences relatives aux identificateurs non cités. Il ne peut pas non plus entrer en conflit avec les mots-clés réservés pour Snowflake.

Facultatif

Ces champs ne sont pas obligatoires, mais doivent être inclus dans la mesure du possible.

description: Une description de ce modèle sémantique, y compris des détails sur le type d’analyse pour lequel il est utile.
tables: Une liste de tables logiques dans ce modèle sémantique.
relationships: Une liste des jointures entre les tables logiques.

Table logique¶

Vous pouvez considérer une table logique comme une vue sur une table ou une vue de base de données physique. Elle contient les domaines suivants :

Nécessaire

name

Un nom descriptif pour cette table.

Doit être unique et suivre les exigences relatives aux identificateurs non cités. Il ne peut pas non plus entrer en conflit avec les mots-clés réservés pour Snowflake.

base_table

Un nom entièrement qualifié de la table de base sous-jacente dans la base de données.

Facultatif

Ces champs ne sont pas obligatoires, mais doivent être inclus dans la mesure du possible.

synonyms: Une liste d’autres termes/expressions utilisés pour faire référence à cette table. Elle doit être unique pour tous les synonymes de la table logique.
description: Une description de cette table.
primary_key: Les colonnes de la clé primaire de cette table. Obligatoire si vous définissez des relations.
dimensions: Une liste des colonnes de dimension dans cette table.
time_dimensions: Une liste de colonnes de dimension temporelle dans cette table.
facts: Une liste des colonnes de faits de cette table.
metrics: Une liste des métriques de cette table.
filters: Filtres prédéfinis sur cette table, le cas échéant.

Dimension¶

Une dimension décrit des valeurs catégoriques telles que l’état, le type d’utilisateur, la plateforme, etc. Elle contient les domaines suivants :

Nécessaire

name

Un nom descriptif pour cette dimension.

Doit être unique et suivre les exigences relatives aux identificateurs non cités. Il ne peut pas non plus entrer en conflit avec les mots-clés réservés pour Snowflake.

expr

L’expression SQL pour cette dimension. Cela pourrait être une référence à une colonne physique ou à une expression SQL avec une ou plusieurs colonnes de la table de base sous-jacente.

data_type

Le type de données de cette dimension. Pour un aperçu de tous les types de données dans Snowflake, consultez Référence de types de données SQL. Noter que VARIANT, OBJECT, GEOGRAPHY, et ARRAY ne sont actuellement pas pris en charge.

Facultatif

Ces champs ne sont pas obligatoires, mais doivent être inclus dans la mesure du possible.

synonyms

Une liste d’autres termes/expressions utilisés pour désigner cette dimension. Doit être unique parmi tous les synonymes de ce modèle sémantique.

description

Une brève description de cette dimension, y compris les données qu’elle contient.

unique

Une valeur booléenne qui indique que cette dimension a des valeurs uniques.

sample_values

Exemples de valeurs de cette colonne, le cas échéant. Ajoutez toute valeur susceptible d’être référencée dans les questions des utilisateurs.

is_enum

Une valeur booléenne. Si True, les valeurs du champ sample_values sont considérées comme la liste complète des valeurs possibles, et le modèle ne choisit que parmi ces valeurs lors du filtrage sur cette colonne.

cortex_search_service

Spécifie le service Cortex Search Service à utiliser pour cette dimension. Elle contient les domaines suivants :

service : Le nom du Cortex Search Service.
literal_column : (facultatif) La colonne du Cortex Search Service qui contient les valeurs littérales.
database : (facultatif) La base de données dans laquelle se trouve le Cortex Search Service. La valeur par défaut est la base de données de base_table.
schema : (facultatif) Le schéma dans lequel le Cortex Search Service est situé. La valeur par défaut est le schéma de base_table.

cortex_search_service replaces the cortex_search_service_name field, which could only specify the name. cortex_search_service_name has been deprecated.

Dimension temporelle¶

Une dimension temporelle décrit des valeurs temporelles, telles que sale_date, created_at et year. Elle contient les domaines suivants :

Nécessaire

name

Un nom descriptif pour cette dimension temporelle.

Doit être unique et suivre les exigences relatives aux identificateurs non cités. Il ne peut pas non plus entrer en conflit avec les mots-clés réservés pour Snowflake.

expr

L’expression SQL pour cette colonne. Cela pourrait être une référence à une colonne physique ou à une expression SQL avec une ou plusieurs colonnes de la table de base sous-jacente.

data_type

Le type de données de cette dimension temporelle. Pour un aperçu de tous les types de données dans Snowflake, consultez Référence de types de données SQL. Noter que VARIANT, OBJECT, GEOGRAPHY, et ARRAY ne sont actuellement pas pris en charge.

Facultatif

Ces champs ne sont pas obligatoires, mais doivent être inclus dans la mesure du possible.

synonyms: Une liste d’autres termes/expressions utilisés pour faire référence à cette dimension temporelle. Doit être unique parmi tous les synonymes de ce modèle sémantique.
description: Une brève description de cette dimension, y compris les données qu’elle contient. Fournissez des informations qui aideront quelqu’un à rédiger des requêtes à l’aide de cette table. Par exemple, pour les colonnes DATETIME, spécifiez le fuseau horaire des données.
unique :: Une valeur booléenne qui indique que cette colonne a des valeurs uniques.
sample_values :: Exemples de valeurs de cette colonne, le cas échéant. Ajoutez toutes les valeurs susceptibles d’être référencées dans les questions des utilisateurs. Ce champ est facultatif.

Fait¶

A fact describes numerical values, such as revenue, impressions, and salary. Facts used to be called measures in earlier releases of Cortex Analyst. Facts are backward compatible with measures. Facts have the following fields:

Nécessaire

name

Un nom descriptif pour ce fait.

Doit être unique et suivre les exigences relatives aux identificateurs non cités. Il ne peut pas non plus entrer en conflit avec les mots-clés réservés pour Snowflake.

expr

Cette expression SQL peut faire référence soit à une colonne physique de la table physique de base de la même table logique, soit à une colonne logique (fait, dimension ou dimension temporelle) au sein de cette table logique.

data_type

Le type de données de ce fait. Pour un aperçu de tous les types de données dans Snowflake, consultez Référence de types de données SQL. Noter que VARIANT, OBJECT, GEOGRAPHY, et ARRAY ne sont actuellement pas pris en charge.

Facultatif

The following fields are not required, but should be included whenever possible.

synonyms: Une liste d’autres termes/expressions utilisés pour désigner cette mesure. Doit être unique parmi tous les synonymes de ce modèle sémantique.
description: Une brève description de cette mesure, y compris les données contenues dans cette colonne.
unique: Une valeur booléenne qui indique que cette colonne a des valeurs uniques.
sample_values: Exemples de valeurs de cette colonne, le cas échéant. Ajoutez toutes les valeurs susceptibles d’être référencées dans les questions des utilisateurs.

Le champ suivant est facultatif. S’il n’est pas inclus, la valeur par défaut est public_access.

access_modifier: Soit public_access soit private_access. Si private_access, le fait est accessible dans le modèle sémantique, mais pas par les utilisateurs finaux.

Filtre¶

Un filtre représente une expression SQL utilisée pour le filtrage. Elle contient les domaines suivants :

Nécessaire

name: Un nom descriptif pour ce filtre.
expr: L’expression SQL de ce filtre, référençant des colonnes logiques.

Facultatif

Ces champs ne sont pas obligatoires, mais doivent être inclus dans la mesure du possible.

synonyms: Une liste d’autres termes/expressions utilisés pour faire référence à ce filtre. Doit être unique parmi tous les synonymes de ce modèle sémantique.
description: Une brève description de ce filtre, y compris des détails sur l’utilisation habituelle de ce filtre.

Métrique¶

A metric describes quantifiable measures of business performance, such as total revenue, average order value, or customer count. Metrics can be regular metrics or derived metrics.

Les métriques régulières sont rattachées à une table logique et peuvent référencer des colonnes logiques (faits, dimensions ou dimensions temporelles) dans la même table logique, ou des colonnes logiques d’autres tables logiques du modèle sémantique. Dans le modèle sémantique, l’élément metric se trouve à l’intérieur d’un élément table. Les métriques régulières utilisent des fonctions d’agrégation et de fenêtre pour calculer les valeurs globales de la table.
Les métriques dérivées sont liées au modèle sémantique et fournissent un moyen de combiner d’autres métriques. Dans le modèle sémantique, l’élément metric se trouve à l’intérieur de l’élément semantic_model. Vous pouvez uniquement faire référence à d’autres métriques (y compris d’autres métriques dérivées) dans l’expression de la métrique.

Metrics have the following fields.

Nécessaire

name

A descriptive name for this metric. This name deterines whether it is a regular metric.

Doit être unique et suivre les exigences relatives aux identificateurs non cités. Il ne peut pas non plus entrer en conflit avec les mots-clés réservés pour Snowflake.

expr

L’expression SQL pour cette colonne. Le format de l’expression varie selon que la métrique est une métrique régulière ou une métrique dérivée.

Regular metrics, which are scoped to a table, reference a logical column (fact, dimension, or time dimension) in the same logical table or a logical column from another logical table in the semantic model and use aggregate or window functions to calculate overall values.
Les métriques dérivées sont des expressions scalaires qui peuvent faire référence à des métriques régulières ou à d’autres métriques dérivées.

Facultatif

The following fields are not required, but should be included whenever possible.

synonyms: A list of other terms/phrases used to refer to this metric. Each synonym must be unique across all synonyms in the semantic model.
description: Une brève description de cette métrique, y compris les données dont dispose cette colonne.
sample_values: Exemples de valeurs de cette colonne, le cas échéant. Ajoutez toutes les valeurs susceptibles d’être référencées dans les questions des utilisateurs.

Le champ suivant est facultatif. S’il n’est pas inclus, la valeur par défaut est public_access.

access_modifier: Soit public_access soit private_access. Si private_access, la métrique est accessible dans le modèle sémantique, mais pas par les utilisateurs finaux.

Table de base¶

Une table de base est utilisée pour représenter des noms de table entièrement qualifiés. Il s’agit de la table physique à laquelle une table logique est mappée. Elle contient les domaines suivants :

Nécessaire

database: Nom de la base de données.
schema: Nom du schéma.
table: Nom de la table.

Clé primaire¶

Une clé primaire représente les colonnes qui représentent de manière unique chaque ligne de la table. La clé primaire est exigée si la table est utilisée dans une relation. Elle contient les domaines suivants :

Nécessaire

columns: Une liste de colonnes de dimensions représentant la table de manière unique.

Relations¶

Définit les relations de jointure entre les tables logiques. Pour garantir une bonne fonctionnalité des jointures, des clés primaires doivent être définies pour les tables impliquées dans les relations. Elle contient les domaines suivants :

Nécessaire

name: Un identifiant unique pour la relation.
left_table: Nom de la table logique tel qu’il a été défini précédemment dans votre fichier YAML. Pour les relations de type plusieurs à un, la table de gauche doit être le côté plusieurs de la relation pour des performances optimales.
right_table: Nom de la table logique tel qu’il a été défini précédemment dans votre fichier YAML. Pour les relations de type plusieurs à un, la table de droite doit être le côté un de la relation pour une performance optimale.
relationship_columns: Une liste de colonnes égales provenant de la table de gauche et de la table de droite représentant le chemin de jointure.
join_type: Soit left_outer soit inner.
relationship_type: Soit many_to_one soit one_to_one.

Requêtes vérifiées¶

Consultez Cortex Analyst Référentiel de requêtes vérifiées pour obtenir des informations sur le but et la structure de cette section du fichier YAML.

Instructions personnalisées¶

For information about custom instructions, see Instructions personnalisées dans Cortex Analyst.