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

For semantic views, facts can be made private (accessible in the semantic view, but not by end users) by setting the access_modifier field to private_access. By default, facts are public (accessible by users).

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.
Derived metrics are calculated from existing metrics, using arithmetic operations such as addition or division. Derived metrics are supported only in semantic views.

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

For semantic views, metrics can be made private (accessible in the semantic view, but not by end users) by setting the access_modifier field to private_access. By default, metrics are public (accessible by users).

Références autorisées¶

Les expressions pour les dimensions, les faits, les filtres ou les métriques régulières de la table peuvent faire référence aux éléments suivants :

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

For semantic views, derived metrics can reference metrics defined in any logical table in the semantic view or other derived metrics.

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
    # For semantic views, do not specify
    # join_type or relationship_type.
    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
    # For semantic views, do not specify
    # join_type or relationship_type.
    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 >  # Supported only for semantic views.
                                                             # 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 >  # Supported only for semantic views.
                                                             # 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>
    # For semantic views, do not specify
    # join_type or relationship_type.
    join_type: <left_outer | inner>
    relationship_type: < one_to_one | many_to_one >

# Derived metrics scoped to the semantic view.
# Derived metrics are supported only for semantic views.
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>.

Create a semantic view using the AI-assisted model generator¶

Use the AI-assisted generator to create a semantic model that combines semantic information from multiple sources. For more information about the AI-assisted generator, see Using the AI-assisted generator to create a semantic view.

To create the model, complete the following steps:

Sign in to Snowsight.
In the navigation menu, select AI & ML » Cortex Analyst.
In the title bar, select Create new » Create new Semantic Model.
Select a location to store the semantic model after creation.
Enter a name for the semantic model.
This name automatically populates the File name field.
For Description, specify information about the semantic model.
Optional: Enter a different file name.
Select Next.
Optional: To provide context, for SQL Queries, provide example questions and their respective SQL queries that you want to use as part of the model.

Note

The AI-assisted generator runs EXPLAIN on these queries, so these queries should return actual data. If they do not, Snowflake doesn’t guarantee proper performance.

For Select tables, provide the data source that you’re using to create the semantic model. You must provide at least one table or view. There’s no limit on the tables or views that you can specify, but we recommend not using more than 10 for the semantic model.
Select Next.
For Select columns, select the columns that you’re using to create the semantic model. You can select all the columns or specific columns. For performance reasons, we recommend not using more than 50 columns.
Select whether you want to add sample values from each column to the semantic model.

Sample values help improve the accuracy of Cortex Analyst’s results.
Select whether you want to add AI-generated descriptions for tables and columns to the semantic model.

The AI-generated descriptions are based on the column names and sample values.
Select Create and save.

You can view the progress of the model generation, including details about the steps that the model generator is taking, on the semantic model page. The process can take a few minutes.

To make further modifications, edit the model by either using Snowsight or editing the YAML file directly.

Cortex Analyst automatically generates suggestions to improve the semantic model after creation. Cortex Analyst uses the query history accessible by the role used to create the semantic model to generate both relationships and verified query suggestions. It might take some time for the suggestions to appear. After the suggestions appear, you can review them and apply them to the model as needed.

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 :

Sign in to Snowsight.
In the navigation menu, select AI & ML » Cortex Analyst.
On the Semantic models tab, select the database, schema, and stage where the semantic model was saved.
From the list of semantic models, select the semantic model that you want to open.
Sélectionnez Open.

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 imposes a 2 MB size limit on the semantic model or semantic view to restrict the size of API inputs.

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 remplace le champ cortex_search_service_name, qui ne pouvait spécifier que le nom. cortex_search_service_name est obsolète.

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 revenus, les impressions et le salaire. Les faits étaient appelés mesures dans les versions antérieures de Cortex Analyst. Les faits sont rétrocompatibles avec les mesures. Les faits ont les champs 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

Les champs suivants 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.

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

access_modifier: Supported only for semantic views. The possible values are public_access and private_access. If this is set to private_access, the fact is accessible in the semantic view, but not by end users.

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 performances opérationnelles, telles que le chiffre d’affaires total, la valeur moyenne des commandes ou le nombre de clients. Les métriques peuvent être des métriques régulières ou des métriques dérivées.

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.
Derived metrics (which are supported only for semantic views) are scoped to the semantic view and provide a way of combining other metrics. In the semantic model, the metric element is inside the semantic_model element. You can refer only to other metrics (including other derived metrics) in the metric’s expression.

Les métriques comportent les champs suivants.

Nécessaire

name

Un nom descriptif pour cette métrique. Ce nom détermine s’il s’agit d’une métrique régulière.

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.

Les mesures régulières, qui sont limitées à une table, font référence à une colonne logique (fait, dimension ou dimension temporelle) dans la même table logique ou à une colonne logique d’une autre table logique dans le modèle sémantique et utilisent des fonctions d’agrégation ou de fenêtre pour calculer les valeurs globales.
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

Les champs suivants 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 métrique. Chaque synonyme doit être unique parmi tous les synonymes du 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.

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

access_modifier: Supported only for semantic views. The possible values are public_access or private_access. If this is set to private_access, the metric is accessible in the semantic view, but not by end users.

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.

Do not specify this for semantic views.

relationship_type

Soit many_to_one soit one_to_one.

Do not specify this for semantic views. Instead, use unique or primary keys in the logical tables to indicate that the relationship should be many-to-one or 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.