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
In a nutshell
  • Cortex Search on a dimension (cortex_search_service) resolves messy or high cardinality literal values.
  • Ambiguous question: the response has suggestions instead of sql.
  • use_as_onboarding_question: true marks 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.
User questionshow Acme salesfilter value?Cortex Search servicecustomer namesexact valueAnalyst SQLWHERE customer = 'Acme Corp'Ambiguous questionno SQLsuggestionsalternatives user can pick

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.

KeyMeaning
serviceName of the Cortex Search service
database, schemaOptional location of the service
literal_columnOptional 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.

Exam tip

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 keyControlsExample
sql_generationHow SQL is writtenRound numbers to 2 decimals; default to the last year when no date is given
question_categorizationHow a question is classified before SQLReject 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

ProblemFeature
Filter value spelled differently from the dataCortex Search integration
Same question always answered the same trusted wayVerified query
Wrong rounding or missing default date filtersql_generation instruction
Off topic or restricted questionsquestion_categorization instruction
Users do not know what to askOnboarding questions
Ambiguous question returns no SQLSuggestions 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.

Watch out

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 suggestions instead of sql.
  • use_as_onboarding_question: true marks starter questions.
  • Custom instructions: module_custom_instructions with sql_generation and question_categorization.
  • The caller needs USAGE on 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_categorization inside module_custom_instructions.

  • What does Analyst return when a question is too ambiguous to write SQL?

    A suggestions content 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.