Custom instructions in Cortex Analyst

Custom instructions let you have greater control over SQL generation. Using natural language, you can tell Cortex Analyst exactly how to generate SQL queries from within your semantic model YAML file. For example, use custom instructions to tell Cortex Analyst what you mean by performance or financial year. In this way, you can improve the accuracy of the generated SQL by incorporating custom logic or additional elements.

For more granular control, you can also specify custom instructions for individual modules in the SQL generation pipeline. See Module custom instructions for more information.

How custom instructions work

Cortex Analyst introduces the custom_instructions field into the semantic model YAML file. This field enables you to apply defining modifications or additions to SQL generation.

For more information about the semantic model syntax, see Cortex Analyst semantic model specification.

Examples

To explore possible use cases for custom instructions, consider the following examples.

Formatting data output

Ensure that all numbers in the output are rounded to two decimal points.

The custom_instructions field in the semantic model YAML file

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

Generated SQL query

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

Adjusting percentages

Automatically multiply percentage or rate calculations by 100 for consistency.

The custom_instructions field in the semantic model YAML file

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

Generated SQL query

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

Adding default filters

Apply a filter if the user doesn’t specify one (for example, default to the last year).

The custom_instructions field in the semantic model YAML file

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

Generated SQL query

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

Linking column filters

Apply additional filters on related columns based on user input.

The custom_instructions field in the semantic model YAML file

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

Generated SQL query

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

Module custom instructions

Set the module_custom_instructions key in the top level of your semantic model to define custom instructions for specific components in the SQL generation pipeline. This feature is useful for use cases like the following:

  • Define logic that influences how user questions are interpreted before SQL is generated

  • Maintain separate, more structured instructions for different parts of the Analyst workflow

  • Transition from existing custom_instructions to a more modular format as your usage grows

Currently, module_custom_instructions supports the following components:

  • question_categorization: Define how Cortex Analyst should classify user questions (for example, by blocking certain topics or guiding user behavior).

  • sql_generation: Specify how SQL should be generated (for example, data formatting and filtering).

Instructions for either or both of these components can be set under the module_custom_instructions key.

Important

Migrate any existing custom_instructions to the sql_generation component, as shown in the following example.

Migrating existing custom instructions

If your model already has a custom_instructions field, migrate its content to the sql_generation field under module_custom_instructions.

Before:

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

After:

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

Blocking questions about specific topics

You can use the question_categorization component to block questions about specific topics. For example, if you want to block questions about users, you might set the following instructions. Cortex Analyst then rejects questions about users with a message telling them to contact their administrator.

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

You can also use question categorization instructions to ask for missing details. In the following example, Cortex Analyst asks the user to provide a product type if they ask about users and do not specify one.

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

Best practices

Be specific.

Clearly describe the modifications; for example, “Add a column with a fixed value of 42” or “Include a sum calculation for column X.”

Start small.

Start with simple modifications, such as adding a static column or default filters, before moving to more complex scenarios.

Preview the generated SQL query.

Ensure that the instructions apply as intended and that the generated SQL query is correct.

Iterate gradually.

Experiment with more complex use cases as your familiarity with the feature grows.

Language: English