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 qu’un lieu ou une heure). 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

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 la performance d’une entreprise, généralement calculée en agrégeant des faits sur plusieurs lignes. Vous exprimez une métrique sous la forme d’une formule SQL qui peut combiner plusieurs objets logiques et fonctions d’agrégation, telles que SUM() ou AVG(). Vous pouvez utiliser les métriques comme indicateurs clés de performance (KPIs) dans les rapports et les tableaux de bord. Définissez les métriques au niveau le plus granulaire pour les agréger aux niveaux supérieurs. Par exemple, définissez total_revenue au niveau de la rubrique pour permettre l’agrégation par client, fournisseur ou région.

  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

Références autorisées¶

Les expressions pour les dimensions, les faits, les métriques ou les filtres peuvent faire référence à ce qui suit :

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

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>

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


    # Business metrics across logical objects
    metrics:
      - name: <name>
        synonyms: <array of strings>
        description: <string>

        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>


# Additional context concepts

#  Verified queries with example questions and queries that answer them
verified_queries:
# Verified Query (1 of n)
  - 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

Si vous ne voyez pas votre modèle sémantique dans votre zone de préparation, essayez d’actualiser la liste des modèles, et non la 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.
Cortex Analyst effectue la récupération en mémoire des valeurs d’échantillon et des requêtes vérifiées ajoutées à la sémantique YAML. Après avoir supprimé toutes les valeurs d’échantillon et les requêtes vérifiées, le modèle sémantique ne peut pas dépasser 32 000 jetons (environ 4 x 32 000 caractères ou environ 128 KB). Vous pouvez utiliser la commande de validation du générateur de modèle sémantique pour garantir que votre fichier reste dans ces limites. Les limites pourraient augmenter à mesure que la prise en charge des modèles avec des fenêtres de contexte plus grandes est ajoutée.

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.

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.

Ce champ remplace le champ cortex_search_service_name, qui ne pouvait spécifier que le nom. cortex_search_service_name est obsolète.

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.

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¶

Un fait décrit des valeurs numériques, telles que les recettes, les impressions et les salaires. Dans les versions antérieures de Cortex Analyst, les faits étaient appelés mesures. Les faits sont rétro-compatibles avec les mesures. Elle contient les domaines suivants :

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)

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 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.

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¶

Une métrique décrit des mesures quantifiables de la performance d’une entreprise, telles que le chiffre d’affaires total, la valeur moyenne des commandes ou le nombre de clients. Elle contient les domaines suivants :

Nécessaire

name

Un nom descriptif pour cette métrique.

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. Elle peut faire référence à une colonne logique (fait, dimension ou dimension temporelle) de la même table logique ou à une colonne logique d’une autre table logique du modèle sémantique.

data_type

Le type de données de cette métrique. Pour un aperçu de tous les types de données dans Snowflake, consultez la référence pour les 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/phrases utilisés pour faire référence à cette métrique. Elle doit être unique pour tous les synonymes de ce modèle sémantique.
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.

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¶

Pour plus d’informations sur les instructions personnalisées, voir Instructions personnalisées dans Cortex Analyst.