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.

Concepts clés¶

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

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

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 :

1. Fournir une description avec des informations de base sur le modèle.

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

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

1. Dans Snowsight, sélectionnez AI & ML.

2. À côté de Cortex Analyst, sélectionnez Try.

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

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

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

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

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

1. Sélectionnez Open semantic model.

2. Sélectionnez Open.

3. Sélectionnez Select from stage.

4. Sélectionnez la base de données et le schéma.

5. Cliquez en dehors de la boîte de dialogue.

6. Sélectionnez la zone de préparation où vous avez enregistré le fichier.

7. Sélectionnez Ouvrir.

Définir les jointures¶

Cortex Analyst prend en charge les jointures SQL, ce qui permet d’effectuer des analyses de données plus poussées sur plusieurs tables. Cette fonction vous permet d’effectuer facilement des requêtes sur les données des tables de faits et des tables de dimensions associées.

relationships:
  - name: <string>
    left_table: <string>
    right_table: <string>
    relationship_columns:
      - left_column: <string>
        right_column: <string>
      - left_column: <string>
        right_column: <string>
    join_type: <join_type>
    relationship_type: <relationship_type>

tables:
  - name: orders
    primary_key:
      columns:
        - order_id
        - location_id

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¶

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)
);

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')