Benutzerdefinierte Anweisungen in Cortex Analyst¶

So funktionieren benutzerdefinierte Anweisungen¶

Cortex Analyst fügt das Feld custom_instructions in die Datei des semantischen Modells YAML ein. In diesem Feld können Sie definierende Änderungen oder Ergänzungen bei der Erstellung von SQL vornehmen.

Weitere Informationen über die Syntax des semantischen Modells finden Sie unter Cortex Analyst-Spezifikation des semantischen Modells.

Beispiele¶

Um mögliche Anwendungsfälle für benutzerdefinierte Anweisungen zu erkunden, betrachten Sie die folgenden Beispiele.

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

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

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

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

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

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

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

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

Modul benutzerdefinierte Anweisungen¶

Legen Sie den Schlüssel module_custom_instructions auf der obersten Ebene Ihres semantischen Modells fest, um benutzerdefinierte Anweisungen für bestimmte Komponenten in der SQL-Generierungspipeline zu definieren. Dieses Feature ist nützlich für Anwendungsfälle wie den folgenden:

• Definieren Sie die Logik, die beeinflusst, wie die Fragen der Benutzer interpretiert werden, bevor SQL generiert wird

• Pflegen Sie separate, besser strukturierte Anweisungen für verschiedene Teile des Analysten-Workflows

• Umstellung von custom_instructions auf ein modulareres Format, wenn Ihre Nutzung wächst

Derzeit unterstützt module_custom_instructions die folgenden Komponenten:

• question_categorization: Legen Sie fest, wie Cortex Analyst die Fragen der Benutzer klassifizieren soll (z. B. indem Sie bestimmte Themen blockieren oder die Verhaltensweise der Benutzer steuern).

• sql_generation: Geben Sie an, wie SQL generiert werden soll (z. B. Datenformatierung und Filterung).

Anweisungen für eine oder beide dieser Komponenten können unter dem Schlüssel module_custom_instructions eingestellt werden.

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

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

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

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.

Best Practices¶

Seien Sie konkret.

Beschreiben Sie die Änderungen klar und deutlich, z. B. „Fügen Sie eine Spalte mit einem festen Wert von 42 hinzu“ oder „Fügen Sie eine Summenberechnung für Spalte X ein“.

Fangen Sie klein an.

Beginnen Sie mit einfachen Änderungen, wie dem Hinzufügen einer statischen Spalte oder von Standardfiltern, bevor Sie zu komplexeren Szenarien übergehen.

Zeigen Sie eine Vorschau der generierten SQL-Abfrage an.

Vergewissern Sie sich, dass die Anweisungen wie vorgesehen angewendet werden und dass die generierte SQL-Abfrage korrekt ist.

Iterieren Sie schrittweise.

Experimentieren Sie mit komplexeren Anwendungsfällen, je vertrauter Sie mit dem Feature werden.