Instructions personnalisées dans Cortex Analyst

Les instructions personnalisées vous permettent de mieux contrôler la génération de SQL. En utilisant le langage naturel, vous pouvez indiquer à Cortex Analyst exactement comment générer des requêtes SQL à partir de votre fichier de modèle sémantique YAML. Par exemple, utilisez des instructions personnalisées pour indiquer à Cortex Analyst ce que vous entendez par performances ou exercice financier. Vous pouvez ainsi améliorer la précision du SQL généré en y incorporant une logique personnalisée ou des éléments supplémentaires.

Pour un contrôle plus granulaire, vous pouvez également spécifier des instructions personnalisées pour des modules individuels dans le pipeline de génération SQL. Voir Instructions personnalisées pour le module pour plus d’informations.

Fonctionnement des instructions personnalisées

Cortex Analyst introduit le champ custom_instructions dans le fichier du modèle sémantique YAML. Ce champ vous permet d’appliquer des modifications ou des ajouts de définition à la génération SQL.

Pour plus d’informations sur la syntaxe du modèle sémantique, voir Spécification du modèle sémantique Cortex Analyst.

Exemples

Pour explorer les cas d’utilisation possibles des instructions personnalisées, examinez les exemples suivants.

Formatage de la sortie des données

Veillez à ce que tous les chiffres de la sortie soient arrondis à deux décimales.

Le champ custom_instructions dans le fichier YAML du modèle sémantique

custom_instructions: "Ensure that all numeric columns are rounded to 2 decimal points in the output."
Copy

Requête SQL générée

SELECT
  ROUND(column_name, 2) AS column_name,
  ...
FROM
  your_table;
Copy

Ajustement des pourcentages

Multipliez automatiquement les calculs de pourcentage ou de taux par 100 pour plus de cohérence.

Le champ custom_instructions dans le fichier YAML du modèle sémantique

custom_instructions: "For any percentage or rate calculation, multiply the result by 100."
Copy

Requête SQL générée

SELECT
  (column_a / column_b) * 100 AS percentage_rate,
  ...
FROM
  your_table;
Copy

Ajouter des filtres par défaut

Appliquez un filtre si l’utilisateur n’en spécifie pas (par exemple, choisir par défaut la dernière année).

Le champ custom_instructions dans le fichier YAML du modèle sémantique

custom_instructions: "If no date filter is provided, apply a filter for the last year."
Copy

Requête SQL générée

SELECT
  ...
FROM
  your_table
WHERE
  date_column >= DATEADD(YEAR, -1, CURRENT_DATE);
Copy

Lier les filtres des colonnes

Appliquez des filtres supplémentaires sur les colonnes connexes en fonction des entrées de l’utilisateur.

Le champ custom_instructions dans le fichier YAML du modèle sémantique

custom_instructions: "If a filter is applied on column X, ensure that the same filter is applied to dimension Y."
Copy

Requête SQL générée

SELECT
  ...
FROM
  your_table
WHERE
  column_x = 'filter_value' AND
  dimension_y = 'filter_value';
Copy

Instructions personnalisées pour le module

Fixez la clé module_custom_instructions au niveau supérieur de votre modèle sémantique afin de définir des instructions personnalisées pour des composants spécifiques du pipeline de génération SQL. Cette fonction est utile dans les cas d’utilisation suivants :

  • Définir la logique qui influence la façon dont les questions des utilisateurs sont interprétées avant que SQL ne soit généré

  • Maintenir des instructions distinctes et plus structurées pour les différentes parties du flux de travail de l’analyste

  • Passer de custom_instructions existantes vers un format plus modulaire au fur et à mesure de l’évolution de votre utilisation

Actuellement, module_custom_instructions prend en charge les composants suivants :

  • question_categorization : Définissez la manière dont Cortex Analyst doit classer les questions des utilisateurs (par exemple, en bloquant certains sujets ou en guidant le comportement des utilisateurs).

  • sql_generation : Indiquez comment le SQL doit être généré (par exemple, formatage et filtrage des données).

Les instructions relatives à l’un ou l’autre de ces éléments, ou aux deux, peuvent être définis sous la clé module_custom_instructions.

Important

Migrez toutes les custom_instructions existantes vers le composant sql_generation, comme indiqué dans l’exemple suivant.

Migration des instructions personnalisées existantes

Si votre modèle comporte déjà un champ custom_instructions, migrez son contenu vers le champ sql_generation sous module_custom_instructions.

Avant :

custom_instructions: "Ensure that all numeric columns are rounded to 2 decimal points."
Copy

Après :

module_custom_instructions:
  sql_generation: |
     "Ensure that all numeric columns are rounded to 2 decimal points."
Copy

Blocage des questions sur des sujets spécifiques

Vous pouvez utiliser le composant question_categorization pour bloquer les questions portant sur des sujets spécifiques. Par exemple, si vous souhaitez bloquer les questions sur les utilisateurs, vous pouvez définir les instructions suivantes. Cortex Analyst rejette alors les questions sur les utilisateurs avec un message leur indiquant de contacter leur administrateur.

module_custom_instructions:
  question_categorization: |
     Reject all questions asking about users. Ask users to contact their admin.
Copy

Vous pouvez également utiliser les instructions de catégorisation des questions pour demander des détails manquants. Dans l’exemple suivant, Cortex Analyst demande à l’utilisateur de fournir un type de produit s’il pose des questions sur les utilisateurs et n’en spécifie pas.

module_custom_instructions:
  question_categorization: |
    - If the question asks for users without providing a product_type, consider this question UNCLEAR and ask the user to specify product_type.
Copy

Meilleures pratiques

Soyez précis.

Décrivez clairement les modifications ; par exemple, « Ajouter une colonne avec une valeur fixe de 42 » ou « Inclure un calcul de somme pour la colonne X ».

Commencez modestement.

Commencez par des modifications simples, comme l’ajout d’une colonne statique ou de filtres par défaut, avant de passer à des scénarios plus complexes.

Prévisualisez la requête SQL générée.

Assurez-vous que les instructions s’appliquent comme prévu et que la requête SQL générée est correcte.

Procédez par itération graduelle.

Expérimentez avec des cas d’utilisation plus complexes à mesure que vous vous familiarisez avec la fonctionnalité.

Langage: Français