Snowflake Gen AI Functions · Topic 19 of 26
Cortex Analyst with Cortex Search, Suggested Questions and Custom Instructions
Tune Cortex Analyst: link dimensions to Cortex Search for literal values, use suggested and onboarding questions, and steer SQL with custom instructions.
- 4 min
- Cortex Search on a dimension (
cortex_search_service) resolves messy or high cardinality literal values. - Ambiguous question: the response has
suggestionsinstead ofsql. use_as_onboarding_question: truemarks starter questions.
What it is
Three features make Cortex Analyst answer better once the basic semantic view exists.
- Cortex Search integration helps Analyst match a user's wording to the exact value stored in a column.
- Suggested questions guide users when a question is ambiguous or when they first open the tool.
- Custom instructions are plain language rules that steer how SQL is written and which questions are accepted.
How it works
Integration with Cortex Search
A user types "sales for Acme" but the column holds ACME CORPORATION INC. A plain WHERE name = 'Acme' returns nothing. The fix is to attach a Cortex Search service to the dimension, so Analyst retrieves the real stored value before it writes the filter. This helps most for dimensions with many distinct values, such as customer names, product names or cities, where listing every value in the semantic view is impractical.
In the YAML the dimension gets a cortex_search_service block.
| Key | Meaning |
|---|---|
service | Name of the Cortex Search service |
database, schema | Optional location of the service |
literal_column | Optional column whose value is used in the filter |
dimensions:
- name: customer_name
expr: customer_name
cortex_search_service:
service: customer_name_search
literal_column: customer_name
Access matters: the Analyst caller needs USAGE on the referenced Cortex Search service, plus SELECT on the tables. The response metadata includes a cortex_search_retrieval entry, so you can see that retrieval happened.
The scenario word to look for is "users type names that do not match the stored values" or "a column with thousands of distinct values." The answer is a Cortex Search service on that dimension.
Suggested questions
Two things carry this name in practice, and both are worth knowing.
Suggestions in the response. If a question is ambiguous and Analyst cannot produce SQL, the response contains content of type suggestions, a list of questions the semantic model can answer. The sql and suggestions content types are mutually exclusive in one response, so an app should handle either.
Onboarding questions. A verified query with use_as_onboarding_question: true is offered to end users as a starter question. This helps first time users learn what the model covers.
Separate from these, Snowsight shows suggested verified queries built from real usage. They come as up to 10 at a time, are not applied automatically, and need a person to accept, edit or dismiss them.
Custom instructions
Custom instructions are natural language guidance written in the semantic model. Prefer the modular key module_custom_instructions, which has two parts.
| Sub key | Controls | Example |
|---|---|---|
sql_generation | How SQL is written | Round numbers to 2 decimals; default to the last year when no date is given |
question_categorization | How a question is classified before SQL | Reject questions about individual users and refer to an admin |
module_custom_instructions:
sql_generation: |
Round all numeric columns to 2 decimal places.
If no date filter is given, filter to the last year.
question_categorization: |
Reject all questions asking about users. Tell them to contact their admin.
The older single string custom_instructions still exists, but the docs say to migrate it to module_custom_instructions under sql_generation.
Best practices from the docs: be specific, start with simple changes such as a default filter, preview the generated SQL to confirm the rule applied, and add complexity gradually.
Which feature fixes which problem
| Problem | Feature |
|---|---|
| Filter value spelled differently from the data | Cortex Search integration |
| Same question always answered the same trusted way | Verified query |
| Wrong rounding or missing default date filter | sql_generation instruction |
| Off topic or restricted questions | question_categorization instruction |
| Users do not know what to ask | Onboarding questions |
| Ambiguous question returns no SQL | Suggestions in the response |
Common mistakes
Putting a rule in custom instructions that a verified query handles better. Use a verified query for a specific question and instructions for general behavior.
Using instructions to block data access. Instructions steer the model. They are not security. Access control comes from roles and policies.
Forgetting USAGE on the search service for the user calling Analyst.
Expecting suggestions to be applied automatically. A person reviews each one.
Custom instructions guide the model but do not guarantee compliance. For a hard restriction on who can see data, use RBAC, masking and row access policies.
What to remember for the exam
- Cortex Search on a dimension (
cortex_search_service) resolves messy or high cardinality literal values. - Ambiguous question: the response has
suggestionsinstead ofsql. use_as_onboarding_question: truemarks starter questions.- Custom instructions:
module_custom_instructionswithsql_generationandquestion_categorization. - The caller needs
USAGEon the search service.
Check yourself
Which feature lets Analyst match "Acme" to the stored value "ACME CORPORATION INC"?
A Cortex Search service attached to the dimension.
Which custom instruction key rejects off topic questions?
question_categorizationinsidemodule_custom_instructions.What does Analyst return when a question is too ambiguous to write SQL?
A
suggestionscontent item with questions the model can answer.
Topic 19 of 26 in Snowflake Gen AI Functions
Test yourself on Snowflake Gen AI Functions
The full Snowflake GES-C02 question bank has 585 questions, with timed practice exams and an explanation for every answer.
This study guide is independent and is not affiliated with, endorsed by, or sponsored by Snowflake. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.