# Snowflake Cortex

> 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.

Source: https://cotera.co/docs/reference/tools/individual-tools/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](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens).

***

## 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:**

```json
{
  "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:**

```json
{
  "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):**

```json
{
  "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):**

```json
{
  "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