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.

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

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