Cortex Analyst Référentiel de requêtes vérifiées

Le Référentiel de requêtes vérifiées Cortex Analyst (VQR) peut aider à améliorer l’exactitude et la fiabilité des résultats en fournissant une série de questions et de requêtes SQL correspondantes pour y répondre. Cortex Analyst exploite ensuite les requêtes SQL pertinentes du référentiel lors de la réponse à des questions similaires. Vous pouvez spécifier des requêtes vérifiées dans votre fichier YAML de modèle sémantique.

Important

Les requêtes SQL doivent utiliser les noms des tables et des colonnes logiques définies dans le modèle sémantique, et non ceux de l’ensemble de données sous-jacent. Consultez l’exemple de requête et sa discussion pour plus d’informations.

Les requêtes vérifiées sont spécifiées dans la section verified_queries du modèle sémantique, comme illustré ici.

verified_queries:

# Verified Query 1
- 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.

# Verified Query 2
- name:
  question:
  verified_at:
  verified_by:
  use_as_onboarding_question:
  sql:

Vous trouverez ci-dessous un exemple de modèle sémantique qui inclut une requête vérifiée.

name: Sales Data
tables:
- name: sales_data
  base_table:
    database: sales
    schema: public
    table: sd_data

  dimensions:
    - name: state
      description: The state where the sale took place.
      expr: d_state
      data_type: TEXT
        unique: false
        sample_values:
          - "CA"
          - "IL"

    # 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: profit
        synonyms:
          - "earnings"
          - "net income"
        description: The profit generated from a sale.
        expr: amt - cst
        data_type: NUMBER
        default_aggregation: sum

verified_queries:
  - name: "California profit"
    question: "What was the profit from California last month?"
    verified_at: 1714497970
    verified_by: Jane Doe
    use_as_onboarding_question: true
    sql: "
SELECT sum(profit)
FROM __sales_data
WHERE state = 'CA'
    AND sale_timestamp >= DATE_TRUNC('month', DATEADD('month', -1, CURRENT_DATE))
    AND sale_timestamp < DATE_TRUNC('month', CURRENT_DATE)
"

Dans l’exemple ci-dessus, __sales_data correspond à la table sales_data définie dans le modèle. Pour éviter les conflits de noms, le nom de la table logique est précédé par deux traits de soulignement. Les colonnes utilisées dans la requête (state, sale_timestamp, et profit) sont les colonnes logiques définies dans la table sale_data du modèle. Les noms des colonnes sous-jacentes (d_state, dt, amt, et cst) ne sont pas utilisés directement dans la requête.

Comme illustré dans l’exemple, la question n’a pas besoin d’être une phrase complète, ni même sous la forme d’une question, mais elle doit refléter quelque chose qu’un utilisateur pourrait demander. Assurez-vous que les requêtes SQL sont syntaxiquement correctes et répondent réellement aux questions posées ; c’est l’essence même d’une « requête vérifiée ». Les requêtes non valides ou inexactes peuvent avoir un impact négatif sur les performances et la précision de Cortex Analyst.

Astuce

Utilisez l’application de génération de modèles sémantiques open source, décrite dans la section suivante, pour vous aider à ajouter des requêtes vérifiées à votre modèle sémantique, sans avoir à vous soucier de la syntaxe SQL ou YAML.

Ajout de requêtes vérifiées à l’aide du générateur de modèle sémantique

Snowflake fournit une application Streamlit open source pour vous aider à ajouter des requêtes vérifiées à votre modèle. Pour installer et utiliser cette application, suivez ces instructions.

  1. Clonez le référentiel. Commencez par cloner le référentiel du semantic-model-generator.

  2. Configurez les identifiants de connexion et installez l’application. Suivez les instructions de configuration dans la rubrique README du référentiel pour fournir vos identifiants de connexion Snowflake et exécuter l’application sur Snowflake ou localement.

  3. Configurer l’application. Une fois l’application en cours d’exécution, entrez la base de données, le schéma et l’emplacement de la zone de préparation du fichier YAML de votre modèle sémantique dans les champs prévus à cet effet. Le fichier YAML apparaîtra dans un éditeur interactif sur le côté gauche de la fenêtre.

  4. Générer une requête. Sur le côté droit de la fenêtre, utilisez l’interface de chat pour poser une question qui générera une requête SQL.

  5. Vérifiez et enregistrez la requête.

  • Inspectez la requête générée et les résultats qu’elle produit. Si cela fonctionne comme prévu, sélectionnez le bouton Save as verified query sous la réponse de l’assistant pour ajouter la requête à votre modèle sémantique.

  • Si la requête générée est incorrecte, sélectionnez le bouton Edit pour modifier la requête. Exécutez la requête modifiée pour vérifier si elle produit les résultats escomptés. Continuez à éditer et à tester jusqu’à ce que la requête fonctionne comme souhaité. Sélectionnez ensuite Save as verified query pour l’ajouter à votre modèle sémantique.

  1. Mettre à jour le modèle sémantique. Sélectionnez le bouton Save en bas à gauche de la fenêtre pour mettre à jour le modèle sémantique. Répétez le processus pour ajouter d’autres requêtes.

  2. Téléchargez le nouveau fichier YAML. Une fois que vous êtes satisfait des requêtes que vous avez ajoutées, sélectionnez le bouton Upload, entrez un nom de fichier pour votre nouveau fichier YAML et sélectionnez Submit Upload.

Lorsque vous revenez à votre zone de préparation dans Snowsight, vous verrez le nouveau fichier YAML du modèle sémantique avec vos requêtes vérifiées.

Ajout des entrées de requête vérifiées Cortex Analyst suggérées

Cortex Analyst fournit également l’interface de suggestion de requêtes vérifiées dans Snowsight, ce qui offre de nouvelles requêtes vérifiées basées sur le comportement des utilisateurs. Pour plus d’informations sur l’ajout de suggestions de requêtes vérifiées, voir Suggestions pour les modèles et les vues sémantiques.

Voir les requêtes vérifiées utilisées dans la réponse Cortex Analyst

Lorsque la question de l’utilisateur est similaire à une requête contenue dans le dépôt de requêtes vérifiées (VQR), Cortex Analyst utilise cette requête pour générer la requête SQL dans sa réponse. Pour savoir quelle requête vérifiée a été utilisée, consultez le champ de confiance dans la réponse API.