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.

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
        }
      ]
    }
  ]
}

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