Snowflake actions

The Snowflake action pack contains the following actions:

• Search Snowflake with SQL – Directly execute SQL queries on your Snowflake data from a Glean agent.

• Search Snowflake with Cortex – Ask natural-language questions that Snowflake Cortex Analyst translates into SQL using your semantic models or semantic views.

• Query Snowflake Cortex Agent (Beta) – Send a natural-language question to a Snowflake Cortex Agent you manage in Snowflake, and let it orchestrate tools like Cortex Analyst and Cortex Search to answer.

Overview

The Snowflake Action Pack in Glean enables users to perform both direct SQL queries and Cortex Analyst (natural language) queries against Snowflake data, seamlessly integrating Snowflake’s advanced analytics into Glean agents.

Key Features

• Natural Language Querying via Cortex Analyst: Users can issue natural language queries that are interpreted and run against Snowflake using the Cortex Analyst API for advanced analytics use cases.
• Direct SQL Execution: Allows users to write and execute raw SQL queries on Snowflake datasets directly from Glean.
• Semantic Model and Semantic View Support: Enables referencing semantic model or semantic view definitions to guide analyst queries in natural language mode.
• User OAuth: Supports authenticated access, requiring users to log in with their credentials for data access.
• Cortex Agent Orchestration: Send a natural-language question to a Snowflake Cortex Agent that can orchestrate tools like Cortex Analyst, Cortex Search, and custom tools you configure.
• Reusable Agent Logic: Leverage Cortex agents within Snowflake to centralize prompts and tool logic, enabling consistent reuse across Glean agents.

Usage Instructions

Setup in Agent Builder

1. Ensure the Snowflake Action Pack has been successfully set up by an admin.
2. Create a new Glean Agent.
3. Add the following steps to the agent:
   • Step 1: Select Trigger type > Task.
   • Step 2: Select the “Search Snowflake with Cortex” action. In the text box, add:
     For Snowflake Cortex Analyst, send the following natural language query to the tool as is without any modification: [[query]].
     Include a comma-separated list of semantic model files or semantic views and the warehouse to be used by Cortex Analyst.
   • Step 3: Select the “Respond” action. In the text box, add:
     Show me the results from the Search Snowflake with Cortex Analyst tool only. If there are more than 3 rows, show them as a table. Use the first row in the response from the tool for column names. Always show citations.
4. Save your changes and share the agent with your teammates using the sharing link.

Usage Examples

• Revenue Insights in Natural Language: What was the total revenue last month? using the Cortex Analyst feature and a semantic model or semantic view input.
• Direct SQL Querying: SELECT COUNT(*) FROM customers LIMIT 5 executed directly through SQL.
• Query Snowflake Cortex Agent: What was our revenue last quarter, and what were the top three revenue days? using a Snowflake Cortex Agent you manage.

Query Snowflake Cortex Agent (Beta)

Use Query Snowflake Cortex Agent to send a natural-language question to a Snowflake Cortex Agent that you manage in your Snowflake account. The Cortex Agent can orchestrate multiple tools such as Cortex Analyst for text‑to‑SQL, Cortex Search over unstructured data, and any custom tools you configure to answer questions over Snowflake‑governed data.

Use this action when:

• You already have Cortex Agents defined in Snowflake that encapsulate your business logic and tool orchestration.

• You want Glean agents to reuse those existing agents instead of recreating similar behavior with “Search Snowflake with Cortex” and custom prompts.

Permissions and prerequisites

Before you use Query Snowflake Cortex Agent, make sure:

• The Snowflake action pack is set up in the Glean Admin Console with a Snowflake OAuth security integration and role, for example, GLEAN_QUERY_SNOWFLAKE_ROLE that has access to your data.

• The authenticated Snowflake user (the OAuth user behind Glean) has:

  • A suitable Cortex role such as SNOWFLAKE.CORTEX_USER or SNOWFLAKE.CORTEX_AGENT_USER.

  • USAGE privileges on:

    • The database, schema, and Cortex Agent object you configure.
    • Any Cortex Search services or semantic models the agent uses.
    • Underlying databases, schemas, and tables referenced by those models including USAGE and SELECT where required.

  • Any required privileges on stored procedures or UDFs used by the agent’s custom tools, for example, USAGE and execute.

If these permissions are missing, the action will fail with a Snowflake error, for example, “does not exist or is not authorized”.

Parameters

The action sends the following fields to Snowflake’s Cortex Agents REST API.

Parameter	Type	Required	Recommended source	Description
Query	string	Yes	Dynamic (user input or step)	Natural language question or request for the Cortex Agent. Include relevant business context, filters, and constraints.
Database	string	Yes	Fixed in step configuration	Name of the Snowflake database that contains the Cortex Agent definition.
Schema	string	Yes	Fixed in step configuration	Name of the Snowflake schema that contains the Cortex Agent definition.
Agent Name	string	Yes	Fixed in step configuration	Name of the Cortex Agent to query (as defined in Snowflake).

How to use this action in an agent

1. Create or open a Glean agent.

2. Add a Trigger step, for example, an input form trigger that captures the user’s question, such as [[query]].

3. Add a new step and select the Snowflake action pack.

4. Choose Query Snowflake Cortex Agent (Beta) from the list of Snowflake actions.

5. Configure the action:

   • Database: Set to the database that contains your Cortex Agent.
   • Schema: Set to the schema that contains your Cortex Agent.
   • Agent name: Set to the name of the Cortex Agent object.
   • Natural Language Query: The default option is **Let AI figure out the value.
     You can optionally append extra instructions, such as “Focus on ARR and only return results for the last full quarter.”

6. (Optional) Add a Respond step after the action to:

   • Show the final answer text from the Cortex Agent.
   • Render any returned table data as a table for the user.

When the action runs, Glean calls the Snowflake Cortex Agents REST API (agent:run) for the specified agent and aggregates the response into a simplified result that your agent can use.

The action returns:

• The final answer text from the Cortex Agent.

• Any table results produced by the agent, for example, query results that can be rendered as a table in a Respond step.

• Execution details you can inspect in the run history, such as:

  • The natural-language question Glean sent to the Cortex Agent.
  • Any SQL queries or search queries the Cortex Agent executed internally.

Known Limitations of Snowflake actions

• Does not support multi-turn conversations or visualizations through the Cortex Analyst interface.
• Glean does not control the quality of Snowflake Cortex Analyst responses (dependent on Snowflake’s API output).
• Advanced features of Snowflake Cortex Analyst (beyond simple query execution) are not supported.

Best Practices and Troubleshooting

• Always provide a warehouse for executing SQL queries with your agents, as some users may not have a default warehouse.
• In case of internal or external failure, the error is relayed back to the user to aid with troubleshooting.
• To get the best results out of Cortex Analyst, ensure that the semantic models or views are extensively defined. Creating a Cortex Search Service for a few of the target columns also helps.

FAQ

• Error: “You must specify the warehouse to use by either setting the warehouse field in the body of the request or by setting the DEFAULT_NAMESPACE property for the current user. Please set a default warehouse for your Snowflake account and provide USAGE privilege for the provided role on the warehouse.”

You need to specify which Snowflake warehouse to use. You can do this by setting the warehouse in the Snowflake warehouse field when configuring your agent, or by ensuring your user account has a default warehouse set in Snowflake. Additionally, make sure the role you are using has the necessary USAGE privilege on the warehouse. To grant this privilege, use the following command in Snowflake:

GRANT USAGE ON WAREHOUSE <WAREHOUSE> TO ROLE <ROLE>;

Replace <WAREHOUSE> with your warehouse name and <ROLE> with your role name.

• Error: “<SNOWFLAKE_OBJECT> does not exist or is not authorized”

This error means that either the object (database, schema, table, etc.) does not exist, the name is incomplete, or your role does not have the required privileges. Ensure you provide the complete and correct qualifier for the object (e.g., DATABASE.SCHEMA.TABLE). You must also grant the necessary USAGE privilege to the Snowflake role used by the action. Here are some example commands:

-- Grant usage to a database
GRANT USAGE ON DATABASE <SET_DATABASE_NAME> TO ROLE <SNOWFLAKE_ROLE>;

-- Grant usage to a schema
GRANT USAGE ON SCHEMA <SET_DATABASE_NAME>.<SET_SCHEMA_NAME> TO ROLE <SNOWFLAKE_ROLE>;

-- Grant read access for a table
GRANT SELECT ON TABLE <SET_DATABASE_NAME>.<SET_SCHEMA_NAME>.<SET_TABLE_NAME> TO ROLE <SNOWFLAKE_ROLE>;

-- Grant read access for all tables in a schema
GRANT SELECT ON ALL TABLES IN SCHEMA <SET_DATABASE_NAME>.<SET_SCHEMA_NAME> TO ROLE <SNOWFLAKE_ROLE>;

-- Grant access to Cortex
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE <SNOWFLAKE_ROLE>;

-- Grant role access to a user
GRANT ROLE <SNOWFLAKE_ROLE> TO USER <SET_USER_NAME>;

-- Grant role access to another role (applies to all users with that role)
GRANT ROLE <SNOWFLAKE_ROLE> TO ROLE <SET_ROLE_NAME>;