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

Pourquoi utiliser des modèles sémantiques ?¶

Cortex Analyst permet aux utilisateurs de poser des questions sur les données Snowflake en utilisant un langage naturel. Il existe généralement un écart entre le vocabulaire utilisé par les utilisateurs professionnels lorsqu’ils posent des questions sur les données et le vocabulaire utilisé dans le schéma de la base de données. Ces utilisateurs utilisent généralement des termes spécifiques à l’entreprise ou au domaine, tandis que le schéma de base de données peut utiliser des abréviations ou des termes souvent utilisés dans les pipelines ETL. Les schémas de base de données manquent souvent également de détails sémantiques pour aider une personne non familière avec un ensemble de données à comprendre les données. Cette différence de vocabulaire rend difficile pour Cortex Analyst de répondre aux questions sur les données avec une grande précision.

Un modèle sémantique est un mécanisme léger qui répond à ces problèmes en permettant la spécification de détails sémantiques supplémentaires sur un ensemble de données. Ces détails sémantiques supplémentaires, comme des noms ou des synonymes plus descriptifs, permettent à Cortex Analyst de répondre aux questions de données de manière beaucoup plus fiable.

Note

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

Concepts clés¶

Note

Tout au long de cette rubrique, les artefacts liés à la base de données de base sont appelés artefacts « physiques » et les artefacts liés au modèle sémantique sont appelés artefacts « 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.

Un concept central des modèles sémantiques de Snowflake est la table logique. Une table logique peut être considérée comme une simple vue sur une table ou une vue de base de données physique. Chaque table logique est une collection de colonnes logiques, qui sont classées en dimensions, time_dimensions, et measures.

Une colonne logique peut être soit une référence à une colonne physique sous-jacente, soit une expression impliquant une ou plusieurs colonnes physiques. L’expression peut être simple, comme une concaténation de chaînes ou une opération mathématique, ou elle peut inclure des expressions d’agrégation. Par exemple, vous pouvez utiliser une expression comme SUM(click)/SUM(spend) pour calculer le coût par clic (CPC).

Le modèle sémantique peut également contenir un référentiel de requêtes vérifié (VQR), qui peut aider à améliorer l’exactitude et la fiabilité des résultats en fournissant une collection de questions et de requêtes SQL correspondantes pour y répondre.

Le modèle sémantique pour Cortex Analyst la spécification est dans YAML. Il fournit les informations sémantiques nécessaires pour répondre aux questions en langage naturel avec une grande précision.

La syntaxe générale est la suivante :

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

# 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_name: <string>

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

    # Measure columns in the logical table.
    measures:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        expr: <SQL expression>
        data_type: <data type>
        default_aggregation: <aggregate function>

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

# 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

Générateur de modèles sémantiques¶

Vous pouvez utiliser l”outil générateur de modèles sémantiques pour générer un modèle sémantique à utiliser avec Cortex Analyst. L’outil offre plusieurs options pour générer des modèles sémantiques : via une application Streamlit, via la ligne de commande ou directement dans votre code Python. L’application Streamlit est particulièrement pratique, vous permettant de créer des modèles sémantiques à partir de zéro ou d’itérer sur des modèles existants téléchargés dans une zone de préparation Snowflake.

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.
Pensez 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 1MB sur le fichier de modèle sémantique pour restreindre la taille des entrées 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¶

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 (recommandé)

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.

Table¶

Une table logique peut être considérée 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 (recommandé)

synonyms: Une liste d’autres termes/expressions utilisés pour faire référence à cette table. Doit être unique parmi les synonymes dans la table logique.
description: Une description de cette table.
dimensions: Une liste des colonnes de dimension dans cette table.
time_dimensions: Une liste de colonnes de dimension temporelle dans cette table.
measures: Une liste de mesures dans 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 (recommandé)

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_name: Nom du Cortex Search Service qui recherche les valeurs littérales dans la colonne. Si un nom de service et sample_values sont spécifiées, les valeurs du champ sample_values sont ignorées.

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 (recommandé)

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.

Mesure¶

Une mesure décrit des valeurs numériques, telles que les revenus, les impressions et le salaire. Elle contient les domaines suivants :

Nécessaire

name

Un nom descriptif pour cette mesure.

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 mesure. 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 (recommandé)

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.
default_aggregation: L’agrégation par défaut appliquée à cette colonne dans le contexte d’un regroupement. Quelques exemples de valeurs sont sum, avg, min, max, median, count, count_distinct, etc.
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.

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 de ce filtre, référençant des colonnes logiques.

Facultatif (recommandé)

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.

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.

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.

Exemple de YAML¶

Cette section montre un exemple de modèle sémantique YAML.

Cet exemple suppose que vous avez la table suivante dans votre schéma :

CREATE TABLE sales.public.sd_data (
    id INT PRIMARY KEY,
    dt DATETIME,
    cat VARCHAR(255),
    loc VARCHAR(255),
    cntry VARCHAR(255),
    chn VARCHAR(50),
    amt DECIMAL(10, 2),
    unts INT,
    cst DECIMAL(10, 2)
);

Copy

Cette table contient des noms de colonnes cryptiques et peu d’informations sémantiques sur les colonnes. Ce qui suit est un modèle sémantique YAML qui donne plus d’informations sémantiques sur cette table :

# Name and description of the semantic model.
name: Sales Data
description: This semantic model can be used for asking questions over the sales data.

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

  # A logical table on top of the 'sd_data' base table.
  - name: sales_data
    description: A logical table capturing daily sales information across different store locations and product categories.

    # The fully qualified name of the base table.
    base_table:
      database: sales
      schema: public
      table: sd_data

    # Dimension columns in the logical table.
    dimensions:
      - name: product_category
        synonyms:
          - "item_category"
          - "product_type"
        description: The category of the product sold.
        expr: cat
        data_type: NUMBER
        unique: false
        sample_values:
          - "501"
          - "544"

      - name: store_country
        description: The country where the sale took place.
        expr: cntry
        data_type: TEXT
        unique: false
        sample_values:
          - "USA"
          - "GBR"

      - name: sales_channel
        synonyms:
          - "channel"
          - "distribution_channel"
        description: The channel through which the sale was made.
        expr: chn
        data_type: TEXT
        unique: false
        sample_values:
          - "FB"
          - "GOOGLE"

    # Time dimension columns in the logical table.
    time_dimensions:
      - name: sale_timestamp
        synonyms:
          - "time_of_sale"
          - "transaction_time"
        description: The time when the sale occurred. In UTC.
        expr: dt
        data_type: TIMESTAMP
        unique: false

    # Measure columns in the logical table.
    measures:
      - name: sales_amount
        synonyms:
          - "revenue"
          - "total_sales"
        description: The total amount of money generated from the sale.
        expr: amt
        data_type: NUMBER
        default_aggregation: sum

      - name: sales_tax
        description: The sales tax paid for this sale.
        expr: amt * 0.0975
        data_type: NUMBER
        default_aggregation: sum

      - name: units_sold
        synonyms:
          - "quantity_sold"
          - "number_of_units"
        description: The number of units sold in the transaction.
        expr: unts
        data_type: NUMBER
        default_aggregation: sum

      - name: cost
        description: The cost of the product sold.
        expr: cst
        data_type: NUMBER
        default_aggregation: sum

      - name: profit
        synonyms:
          - "earnings"
          - "net income"
        description: The profit generated from a sale.
        expr: amt - cst
        data_type: NUMBER
        default_aggregation: sum

    # A table can define commonly used filters over it. These filters can then be referenced in user questions directly.
    filters:
      - name: north_america
        synonyms:
          - "North America"
          - "N.A."
          - "NA"
        description: "A filter to restrict only to north american countries"
        expr: cntry IN ('canada', 'mexico', 'usa')

Copy