Snowflake Cortex

Authentication Type: API Key
Description: Use natural language to query your data with Snowflake Cortex. Automatically generates SQL queries from semantic models. API Key should be your Snowflake programmatic access token.

Authentication

To authenticate, you'll need a Snowflake programmatic access token. Learn how to create one in the Snowflake documentation.

Analyst

Query your data using natural language with Snowflake Cortex.

Ask Question (SQL Only)

Ask a natural language question about your data. Cortex will generate SQL queries using your semantic models but will NOT execute them. Returns only the generated SQL code. Use this when you want to review the SQL before running it.

Operation Type: Query (Read)

Parameters:

accountUrl string (required): Snowflake account URL (e.g., https://myorg-myaccount.snowflakecomputing.com)
warehouse string (nullable): Snowflake warehouse to use for compute (optional, uses default if not specified)
database string (nullable): Snowflake database context (optional, uses default if not specified)
schema string (nullable): Snowflake schema context (optional, uses default if not specified)
role string (nullable): Snowflake role to use (optional, uses default role from token if not specified)
question string (required): The natural language question to ask about your data
semanticModel string (nullable): YAML semantic model specification. Required if semanticModelFile and semanticView are not provided
semanticModelFile string (nullable): Path to the semantic model YAML file on a Snowflake stage (e.g., @my_db.my_schema.my_stage/my_semantic_model.yaml)
semanticView string (nullable): Fully qualified name of the semantic view (e.g., MY_DB.MY_SCHEMA.SEMANTIC_VIEW)
conversationHistory array of objects (nullable): Previous conversation history for multi-turn conversations. Include previous messages to build upon previous queries
- role string: The role of the speaker (user or analyst)
- content array of objects: The content of the message
  - type string: The content type (text, sql, or suggestions)
  - text string (nullable): Text content (for type: text)
  - statement string (nullable): SQL statement (for type: sql)
  - suggestions array of strings (nullable): Suggested questions (for type: suggestions)

Returns:

requestId string: Unique request ID from Snowflake
message object: The analyst response message
- role string: The role of the responder (analyst)
- content array of objects: Array of content blocks in the response
  - type string: The content type (text, sql, or suggestions)
  - text string (nullable): Explanatory text from the analyst
  - statement string (nullable): Generated SQL statement
  - confidence object (nullable): Confidence information for SQL responses
    - verifiedQueryUsed object (nullable): Information about verified query used
      - name string: Name of the verified query
      - question string: Question answered by the verified query
      - sql string: SQL statement of the verified query
      - verifiedAt number: Timestamp when query was verified
      - verifiedBy string: Person who verified the query
  - suggestions array of strings (nullable): Suggested questions if SQL cannot be generated
warnings array of objects (nullable): List of warnings from the analyst
- message string: Detailed description of the warning
responseMetadata object (nullable): Metadata about response generation
- modelNames array of strings (nullable): List of models used to generate response
- cortexSearchRetrieval array (nullable): Entities resolved with cortex search
- questionCategory string (nullable): How the question was categorized
- semanticModelSelection string (nullable): Which semantic model was chosen when multiple models were provided

Example Usage:

{
  "accountUrl": "https://myorg-myaccount.snowflakecomputing.com",
  "warehouse": "COMPUTE_WH",
  "database": "SALES_DB",
  "schema": "PUBLIC",
  "role": "ANALYST_ROLE",
  "question": "What were the top 5 products by revenue last quarter?",
  "semanticModel": "name: sales_model\ntables:\n  - name: sales\n    base_table: sales_db.public.sales_fact\n    dimensions:\n      - name: product_name\n        expr: product_name\n      - name: sale_date\n        expr: sale_date\n    measures:\n      - name: revenue\n        expr: SUM(amount)\n        aggregation: sum",
  "semanticModelFile": null,
  "semanticView": null,
  "conversationHistory": null
}

Ask Question & Get Results

Ask a natural language question about your data. Cortex will generate SQL queries using your semantic models AND execute them automatically. Returns both the generated SQL and the actual query results. Provide your Snowflake account URL, connection context (warehouse, database, schema, role), and either a semantic model YAML, file reference, or semantic view name.

Operation Type: Query (Read)

Parameters:

accountUrl string (required): Snowflake account URL (e.g., https://myorg-myaccount.snowflakecomputing.com)
warehouse string (nullable): Snowflake warehouse to use for compute (optional, uses default if not specified)
database string (nullable): Snowflake database context (optional, uses default if not specified)
schema string (nullable): Snowflake schema context (optional, uses default if not specified)
role string (nullable): Snowflake role to use (optional, uses default role from token if not specified)
question string (required): The natural language question to ask about your data
semanticModel string (nullable): YAML semantic model specification. Required if semanticModelFile and semanticView are not provided
semanticModelFile string (nullable): Path to the semantic model YAML file on a Snowflake stage (e.g., @my_db.my_schema.my_stage/my_semantic_model.yaml)
semanticView string (nullable): Fully qualified name of the semantic view (e.g., MY_DB.MY_SCHEMA.SEMANTIC_VIEW)
conversationHistory array of objects (nullable): Previous conversation history for multi-turn conversations. Include previous messages to build upon previous queries
- role string: The role of the speaker (user or analyst)
- content array of objects: The content of the message
  - type string: The content type (text, sql, or suggestions)
  - text string (nullable): Text content (for type: text)
  - statement string (nullable): SQL statement (for type: sql)
  - suggestions array of strings (nullable): Suggested questions (for type: suggestions)

Returns:

requestId string: Unique request ID from Snowflake
generatedSql string (nullable): The SQL query generated by Cortex Analyst (null if no SQL was generated)
explanation string (nullable): Explanation of the generated query
executionResults object (nullable): Results from executing the generated SQL (null if no SQL was generated)
- statementHandle string: Snowflake statement execution handle
- data array of objects: Query results as array of records
- rowCount number: Number of rows returned
- executionTime number: Query execution time in milliseconds
suggestions array of strings (nullable): Suggested questions if Cortex could not generate SQL
warnings array of objects (nullable): List of warnings from Cortex Analyst
- message string: Detailed description of the warning
responseMetadata object (nullable): Metadata about response generation
- modelNames array of strings (nullable): List of models used to generate response
- cortexSearchRetrieval array (nullable): Entities resolved with cortex search
- questionCategory string (nullable): How the question was categorized
- semanticModelSelection string (nullable): Which semantic model was chosen when multiple models were provided

Example Usage:

{
  "accountUrl": "https://myorg-myaccount.snowflakecomputing.com",
  "warehouse": "COMPUTE_WH",
  "database": "SALES_DB",
  "schema": "PUBLIC",
  "role": "ANALYST_ROLE",
  "question": "Show me monthly revenue trends for the last 6 months",
  "semanticModel": null,
  "semanticModelFile": "@sales_db.public.models_stage/sales_semantic_model.yaml",
  "semanticView": null,
  "conversationHistory": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What were total sales last year?",
          "statement": null,
          "suggestions": null
        }
      ]
    },
    {
      "role": "analyst",
      "content": [
        {
          "type": "sql",
          "text": null,
          "statement": "SELECT SUM(revenue) FROM sales WHERE year = 2024",
          "suggestions": null
        }
      ]
    }
  ]
}

Agent

Interact with Snowflake Cortex Agents to have intelligent conversations powered by your data and tools.

Chat

Chat with a Snowflake Cortex Agent. Agents can answer questions, execute tools, and maintain conversation context across multiple turns.

Operation Type: Mutation (Write)

Parameters:

accountUrl string (required): Snowflake account URL (e.g., https://myorg-myaccount.snowflakecomputing.com)
agentRef object (required): Reference to the Cortex Agent to chat with
- database string: Database where the agent is located
- schema string: Schema where the agent is located
- name string: Name of the agent
message string (required): The message to send to the agent
threadId string (nullable): Thread ID for continuing a conversation. Pass the threadId from a previous response to maintain context. Leave null for a new conversation
parentMessageId string (nullable): Message ID to continue from. Pass the messageId from a previous response for follow-up questions
toolChoice object (nullable): Control how the agent uses tools
- type string: Tool selection mode - "auto" (agent decides), "required" (must use a tool), or "tool" (use specific tools)
- name array of strings (nullable): Tool names to allow or require (required when type is "tool")
warehouse string (nullable): Snowflake warehouse to use for compute (optional, uses default if not specified)
role string (nullable): Snowflake role to use (optional, uses default role from token if not specified)
originApplication string (nullable): Application identifier for tracking purposes

Returns:

text string: The agent's response text
threadId string: Thread ID to use for follow-up messages in the same conversation
messageId string: Message ID to use as parentMessageId for the next message
continuationHint string: Human-readable hint explaining how to continue the conversation

Example Usage (New Conversation):

{
  "accountUrl": "https://myorg-myaccount.snowflakecomputing.com",
  "agentRef": {
    "database": "ANALYTICS_DB",
    "schema": "AGENTS",
    "name": "SALES_ASSISTANT"
  },
  "message": "What were our top performing products last quarter?",
  "threadId": null,
  "parentMessageId": null,
  "toolChoice": null,
  "warehouse": "COMPUTE_WH",
  "role": "ANALYST_ROLE",
  "originApplication": null
}

Example Usage (Follow-up Message):

{
  "accountUrl": "https://myorg-myaccount.snowflakecomputing.com",
  "agentRef": {
    "database": "ANALYTICS_DB",
    "schema": "AGENTS",
    "name": "SALES_ASSISTANT"
  },
  "message": "Can you break that down by region?",
  "threadId": "abc123-thread-id",
  "parentMessageId": "1",
  "toolChoice": null,
  "warehouse": "COMPUTE_WH",
  "role": "ANALYST_ROLE",
  "originApplication": null
}

Important: For multi-turn conversations, you must pass the threadId and messageId from the previous response. The first call will return these values - use them in subsequent calls to maintain conversation context.

Common Use Cases

Self-Service Analytics:

Enable business users to query data using natural language without SQL knowledge
Generate verified SQL queries from semantic models for consistent analysis
Review generated SQL before execution for transparency and learning

Interactive Data Exploration:

Ask follow-up questions building on previous queries using conversation history
Explore data patterns and trends through multi-turn conversations
Get suggested questions when the analyst needs more context

Report Generation:

Automatically execute queries and retrieve results for dashboards and reports
Track query performance with execution time and statement handles
Leverage semantic models to ensure consistent metrics across reports

Data Governance:

Use verified queries to ensure approved SQL patterns are followed
Track which semantic models and entities were used for each query
Monitor warnings and metadata to understand query generation quality

Conversational AI Assistants:

Build intelligent assistants that can answer questions using your Snowflake data
Maintain conversation context across multiple turns for natural follow-up questions
Leverage Cortex Agents with custom tools and data access for domain-specific expertise