Skip to content

Commit 045788f

Browse files
waleedlatif1waleedlatif1
authored
feat(snowflake): add Cortex Analyst operations to the Snowflake block (#8347)
* feat(snowflake): add Cortex Analyst operations to the Snowflake block * fix(snowflake): keep Cortex Analyst SQL context for quoted and multi-source views and replay suggestions * fix(snowflake): run Cortex Analyst SQL with the resolved token, the chosen source's schema, and document access requirements
1 parent c479a5a commit 045788f

13 files changed

Lines changed: 1232 additions & 11 deletions

File tree

‎apps/docs/content/docs/integrations/snowflake.mdx‎

Lines changed: 101 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Snowflake
3-
description: Query data and manage warehouses and tasks in Snowflake
3+
description: Query data, ask Cortex Analyst, and manage warehouses and tasks in Snowflake
44
---
55

66
import { BlockInfoCard } from "@/components/ui/block-info-card"
@@ -14,12 +14,20 @@ import { BlockInfoCard } from "@/components/ui/block-info-card"
1414
[Snowflake](https://www.snowflake.com/) stores data in databases and schemas and uses virtual warehouses to run queries. Sim connects over the SQL API with a programmatic access token.
1515

1616
Use the block to execute SQL, synchronize rows, move staged data, manage warehouses and tasks, and inspect history. To unload a query result, first materialize it as a view or with `CREATE TABLE AS SELECT`.
17+
18+
**Cortex Analyst.** Ask Cortex Analyst turns a plain-English question into SQL against a semantic view or semantic model, and can run that SQL to return rows. Pass the returned `conversation` back as history to ask follow-up questions, and start a new conversation after a handful of turns, since Snowflake reprocesses the whole history on every question. Before you use it:
19+
20+
- The access token's role needs the `SNOWFLAKE.CORTEX_USER` or `SNOWFLAKE.CORTEX_ANALYST_USER` database role, `SELECT` on the tables behind the semantic view, and read access to the stage when the model is a staged YAML file.
21+
- Cortex Analyst always answers under the access token's role. The block's execution role, warehouse, and row limit apply only when it runs the generated SQL.
22+
- Cortex Analyst runs natively in a limited set of cloud regions. Other accounts need cross-region inference turned on.
23+
- Snowflake bills each successful answer, and running the SQL uses warehouse credits on top.
24+
- Snowflake now recommends Cortex Agents for new builds; Cortex Analyst remains available.
1725
{/* MANUAL-CONTENT-END */}
1826

1927

2028
## Usage Instructions
2129

22-
Connect with a Snowflake programmatic access token to execute SQL, synchronize structured rows, load and unload staged data, browse databases and schemas, size and control warehouses, run and schedule tasks, review query and load history, inspect schemas, and call stored procedures.
30+
Connect with a Snowflake programmatic access token to execute SQL, synchronize structured rows, load and unload staged data, browse databases and schemas, size and control warehouses, run and schedule tasks, review query and load history, inspect schemas, and call stored procedures. Ask Cortex Analyst questions in natural language against a semantic view or model to get generated SQL and, optionally, its results, with multi-turn follow-ups.
2331

2432

2533

@@ -1354,4 +1362,95 @@ Call a stored procedure with explicitly typed Snowflake bindings.
13541362
| ↳ `duplicateRowsUpdated` | number | Duplicate rows updated by the statement |
13551363
| ↳ `rowsAffected` | number | Total inserted, updated, and deleted rows |
13561364

1365+
### Snowflake Cortex Analyst Ask
1366+
1367+
Ask Snowflake Cortex Analyst a question in natural language against a semantic view or semantic model. Returns its interpretation and the generated SQL, or suggested questions when the question is ambiguous, and can run the SQL to return rows. Pass the returned conversation as history to ask a follow-up.
1368+
1369+
#### Input
1370+
1371+
| Parameter | Type | Required | Description |
1372+
| --------- | ---- | -------- | ----------- |
1373+
| `oauthCredential` | string | Yes | Snowflake credential \(account host and programmatic access token\) |
1374+
| `question` | string | Yes | The question to ask about your data |
1375+
| `semanticView` | string | No | Fully qualified semantic view name \(for example MY_DB.MY_SCHEMA.MY_VIEW\). Provide exactly one semantic source. |
1376+
| `semanticModelFile` | string | No | Stage path to a semantic model YAML file \(for example @MY_DB.MY_SCHEMA.MY_STAGE/model.yaml\). Provide exactly one semantic source. |
1377+
| `semanticModel` | string | No | Full semantic model YAML. Provide exactly one semantic source. |
1378+
| `semanticModels` | json | No | Several semantic sources for Cortex Analyst to choose between, as a JSON array of \{"semantic_view": "..."\} or \{"semantic_model_file": "@..."\} objects. Provide exactly one semantic source. |
1379+
| `history` | json | No | Earlier conversation messages in order, as returned in the conversation output of a previous ask |
1380+
| `executeSql` | boolean | No | Run the generated SQL with the same credential and return the result rows |
1381+
| `warehouse` | string | No | Warehouse for running the generated SQL; defaults to the PAT user setting |
1382+
| `role` | string | No | Snowflake role for running the generated SQL. Cortex Analyst itself always answers under the access token role |
1383+
| `maxRows` | number | No | Maximum result rows when running the SQL; defaults to 1000 \(Sim limit 10000\) |
1384+
| `statementTimeoutSeconds` | number | No | Timeout in seconds for running the SQL; 0 uses the Snowflake maximum |
1385+
1386+
#### Output
1387+
1388+
| Parameter | Type | Description |
1389+
| --------- | ---- | ----------- |
1390+
| `requestId` | string | Cortex Analyst request ID, used to send feedback on this answer |
1391+
| `text` | string | How Cortex Analyst interpreted the question, or why it could not answer it \(text content joined in order\) |
1392+
| `sql` | string | SQL Cortex Analyst generated, or null when the question was ambiguous |
1393+
| `verifiedQuery` | object | Verified Query Repository entry used to generate the SQL, or null when none was used |
1394+
| ↳ `name` | string | Verified query name |
1395+
| ↳ `question` | string | Question the verified query answers |
1396+
| ↳ `sql` | string | SQL of the verified query |
1397+
| ↳ `verifiedAt` | number | When the query was last verified \(Unix epoch seconds, UTC\) |
1398+
| ↳ `verifiedBy` | string | Who verified the query |
1399+
| `suggestions` | array | Questions the semantic model can answer, returned instead of SQL when the question was ambiguous |
1400+
| `warnings` | array | Warnings Cortex Analyst raised about the request |
1401+
| `questionCategory` | string | How Cortex Analyst categorized the question \(for example CLEAR_SQL\) |
1402+
| `modelNames` | array | Models used to generate the response |
1403+
| `semanticModelSelection` | object | Which semantic source Cortex Analyst chose when several were given, or null for a single source |
1404+
| ↳ `index` | number | Zero-based position of the chosen source in Semantic Sources |
1405+
| ↳ `semanticView` | string | Chosen semantic view |
1406+
| ↳ `semanticModelFile` | string | Chosen staged semantic model file |
1407+
| ↳ `inlineSemanticModel` | string | Chosen inline semantic model YAML |
1408+
| `cortexSearchRetrieval` | json | Entities Cortex Analyst resolved with Cortex Search \(\[\{service, query, response_body\}\]\), passed through as returned |
1409+
| `conversation` | array | Full conversation including this question and answer \(analyst turns keep their text and SQL\); pass it as History to ask a follow-up. Snowflake recommends starting a new conversation after many turns |
1410+
| ↳ `role` | string | user or analyst |
1411+
| ↳ `content` | array | Message content blocks \(text, sql, suggestions\) |
1412+
| `execution` | object | Result of running the generated SQL when Run Generated SQL is on, otherwise null. A query still running after 45 seconds returns status RUNNING with a statementHandle; fetch its rows with Get Statement |
1413+
| ↳ `statementHandle` | string | Snowflake statement handle |
1414+
| ↳ `status` | string | Statement status: SUCCEEDED, RUNNING, or CANCELED |
1415+
| ↳ `message` | string | Snowflake response message |
1416+
| ↳ `result` | object | Completed result partition, or null while running or when no result is available |
1417+
| ↳ `columns` | array | Documented Snowflake result column metadata, or null when Snowflake returned a metadata-less partition response |
1418+
| ↳ `name` | string | Column name |
1419+
| ↳ `type` | string | Snowflake data type |
1420+
| ↳ `length` | number | Column length |
1421+
| ↳ `precision` | number | Numeric precision |
1422+
| ↳ `scale` | number | Numeric scale |
1423+
| ↳ `nullable` | boolean | Whether the column is nullable |
1424+
| ↳ `rows` | array | One complete Snowflake result partition as string or null arrays |
1425+
| ↳ `totalRows` | number | Total result rows |
1426+
| ↳ `currentPartition` | number | Zero-based partition returned |
1427+
| ↳ `partitionCount` | number | Total partitions in the result set. Snowflake reports this only on the first partition, so pass it back to Get Statement when fetching later partitions |
1428+
| ↳ `nextPartition` | number | Next partition to request with Get Statement, if one exists |
1429+
| ↳ `truncated` | boolean | Whether more result partitions remain to fetch with Get Statement, or null when Snowflake returned a metadata-less partition response and partitionCount was not supplied. Snowflake does not report when the requested row limit capped the result set, so that cap is never reflected here |
1430+
| ↳ `dml` | object | Completed DML statistics, or null when the statement has no DML statistics |
1431+
| ↳ `rowsInserted` | number | Rows inserted by the statement |
1432+
| ↳ `rowsUpdated` | number | Rows updated by the statement |
1433+
| ↳ `rowsDeleted` | number | Rows deleted by the statement |
1434+
| ↳ `duplicateRowsUpdated` | number | Duplicate rows updated by the statement |
1435+
| ↳ `rowsAffected` | number | Total inserted, updated, and deleted rows |
1436+
1437+
### Snowflake Cortex Analyst Feedback
1438+
1439+
Rate a Cortex Analyst answer thumbs up or down, with an optional comment. Feedback appears in the Snowsight Cortex Analyst monitoring tab.
1440+
1441+
#### Input
1442+
1443+
| Parameter | Type | Required | Description |
1444+
| --------- | ---- | -------- | ----------- |
1445+
| `oauthCredential` | string | Yes | Snowflake credential \(account host and programmatic access token\) |
1446+
| `requestId` | string | Yes | Request ID returned by Cortex Analyst Ask |
1447+
| `positive` | boolean | Yes | true for positive \(thumbs up\) feedback, false for negative \(thumbs down\) |
1448+
| `feedbackMessage` | string | No | Optional feedback comment |
1449+
1450+
#### Output
1451+
1452+
| Parameter | Type | Description |
1453+
| --------- | ---- | ----------- |
1454+
| `success` | boolean | Whether the feedback was recorded |
1455+
13571456

0 commit comments

Comments
 (0)