這是一份實用指南,介紹了使 Cortex Code 在實際資料工作中發揮作用的命令、提示、模式和習慣。
Cortex Code是一款資料原生編碼代理,它直接作用於您的資料環境。它可以辨識模式、角色、授權、標籤、血緣關係、查詢歷史、語義模型以及您試圖避免破壞的資料的即時結構。
你的 SQL 程式碼存放在程式碼倉庫中。你的dbt模型存放在程式碼倉庫中。你的 DAG 也存放在程式碼倉庫中。但最終的成敗往往取決於其他地方:資料本身、平台狀態以及圍繞資料製定的操作規則。
這就是 Cortex Code 的用武之地。它可以針對程式碼所依賴的相同環境進行操作,而不是將程式碼庫視為整個系統。
本文是針對希望每天使用 Cortex Code 的資料工程師的實戰指南。它重點介紹值得隨時掌握的命令、提示、 dbt工作流程、Airflow 模式、 AGENTS.md和技能。
Cortex Code 的重點不是「更花俏的 SQL 自動補全」。
關鍵是它不僅會影響磁碟上的文件,還會影響你的 Snowflake 環境。
這改變了事情的可能性:
您可以按業務概念而不是物件名稱來請求表。
你可以問為什麼某個角色無法讀取某個物件,而不是手動深入權限進行排查。
您可以編輯dbt模型,執行最小安全版本,比較開發環境和生產環境,並留下驗證查詢。
您可以利用帳戶資訊詢問成本和管理方面的資訊。
你可以將一個好的工作流程打包成一個可重複使用的技能,而不是永遠重複同樣的十步驟流程。
如果作業依賴 Snowflake 帳戶狀態,則 Cortex 程式碼應該會進入循環。
它比通用編碼代理更適合資料工程,原因有以下幾點:
它理解 Snowflake 物件、角色、模式和 SQL 語義。
它可以直接搜尋 Snowflake 物件和文件。
它可以直接執行 SQL,而無需將 SQL 複製到其他工具中。
它可以在Snowsight中用於發現、管理和工作區任務。
它可以用於本地倉庫的 CLI 操作、 dbt 、 git 、shell 命令、Airflow、Skills 和自動化。
它相容於 Snowflake 的基於角色的存取控制 (RBAC) 和命令列介面 (CLI) 的批准模式。這對於日常工作涉及生產資料和存取邊界管理的情況至關重要。
僅限倉庫的代理商仍然很有價值,我一直在使用它們。但對於資料工程而言,倉庫上下文只是問題的一半。
如果你花十分鐘時間進行設定而不是臨時抱佛腳,日常體驗會好得多。
在開始前,請先安裝 Snowflake CLI( snow )。 Cortex Code CLI 與 Snowflake 使用相同的連接設定和~/.snowflake/connections.toml檔案。此外,請確保您的平台是 Cortex Code CLI 支援的平台(詳見官方文件)。
curl -LsS https://ai.snowflake.com/static/cc-scripts/install.sh | sh
如果您使用的是 Windows 系統,請使用官方文件中的 PowerShell 安裝程式:
irm https://ai.snowflake.com/static/cc-scripts/install.ps1 | iex
使用指定的連接和工作目錄啟動它:
cortex -c dev -w ~/src/analytics
繼續上一堂課:
cortex --continue
從 shell 執行一次性提示符號:
如果您的帳戶支援列印模式,請使用-p進行快速的一次性列印提示。訂閱帳戶和試用帳戶會停用-p / --print參數,因此在這些環境下,您應該啟動cortex -c dev並以互動方式執行相同的請求。
cortex -c dev -p "List every table tagged PII = TRUE in ANALYTICS_DB"
具體的角色設定取決於您使用的介面:
Cortex Code CLI :以SNOWFLAKE.CORTEX_USER開始。
Cortex Code in Snowsight :授予SNOWFLAKE.COPILOT_USER以及SNOWFLAKE.CORTEX_USER或SNOWFLAKE.CORTEX_AGENT_USER 。
如果兩者都使用,最簡單的基線是COPILOT_USER加上CORTEX_USER 。
ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'AWS_US';
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE DATA_ENGINEER;
-- If you use Cortex Code in Snowsight:
GRANT DATABASE ROLE SNOWFLAKE.COPILOT_USER TO ROLE DATA_ENGINEER;
-- Optional, depending on your org's access model for agentic workflows:
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE DATA_ENGINEER;
ALTER ACCOUNT語句必須由ACCOUNTADMIN執行。請將AWS_US替換為您帳戶所需的區域設定。如果您的組織限制模型存取,請確保允許存取所需的模型,並為您實際需要的區域啟用跨區域推理。
還有一個需要注意的地方:有些帳戶會透過PUBLIC繼承SNOWFLAKE.CORTEX_USER ,除非該帳戶已被撤銷,因此不要假設缺少明確授權總是意味著缺少有效權限。
做一次就好。未來的你會感謝你的。
~/.snowflake/connections.toml
[dev]
account = "myorg-myaccount"
user = "[email protected]"
authenticator = "externalbrowser"
warehouse = "DEV_WH"
role = "DATA_ENGINEER"
database = "ANALYTICS"
schema = "PUBLIC"
[prod_readonly]
account = "myorg-myaccount"
user = "[email protected]"
authenticator = "externalbrowser"
warehouse = "PROD_WH"
role = "ANALYST"
database = "ANALYTICS"
schema = "PUBLIC"
現在你可以明確表達了:
cortex -c dev -w ~/src/analytics
cortex -c prod_readonly -w ~/src/analytics
這個習慣可以避免很多愚蠢的事情。
這些是我真正會常備在手邊的。
cortex
cortex -c dev
cortex -c dev -w ~/src/analytics
cortex --continue
cortex --plan
cortex -p "Explain why this query is slow and optimize it"
這些是Cortex Code CLI指令。在Snowsight中, /主要用於內建功能和自訂功能,而不是完整的 CLI 斜線指令介面。
/plan
/status
/sql
/sh
/conn
/diff
/fdbt
/lineage
/worktree
/skill
/mcp
cortex airflow health
cortex airflow dags list
cortex airflow dags get my_pipeline
cortex airflow dags source my_pipeline
cortex airflow runs trigger my_pipeline
cortex airflow runs list my_pipeline
cortex airflow tasks list my_pipeline <run_id>
您不需要進行大量的本地配置,但一點點配置就能帶來很大的好處。
~/.snowflake/cortex/settings.json
{
"defaultViewMode": "compact",
"autoUpdate": true,
"theme": "dark"
}
~/.snowflake/cortex/settings.json
{
"permissions": {
"defaultMode": "ask",
"dangerouslyAllowAll": false
}
}
這樣可以保持命令列介面的簡潔,並預設啟用權限提示。 permissions.json permissions.json最好被視為已儲存的權限緩存,而不是設定這些預設值的主要位置。
如果您的團隊希望共享程式碼庫行為,請使用AGENTS.md來定義專案規則,並使用 Skills 來定義可重複的工作流程。如果您的組織希望進行更嚴格的控制,請使用託管設置,而不是依賴每個人都以相同的方式配置 CLI。
兩者都可以用。它們不是相互競爭的表面。
| 表面 | 最適合 |
| :---- | :---- |
| Cortex Code in Snowsight | SQL 編寫、快速目錄發現、Snowflake 上的 dbt 專案、權限問題、治理、FinOps、快速查詢修復、基於@的物件上下文、工作區中的差異審查 |
| Cortex Code CLI | 本地dbt倉庫、本地檔案、 git 、shell 指令、驗證工作流程、Airflow、技能、 AGENTS.md 、可重複的工程工作 |
簡單的原則是這樣的:
探索之旅可以從Snowsight開始。
當您需要本機檔案、原始碼控製或可重複的工作流程時,請切換至 CLI。
這就是Cortex Code與通用編碼代理最明顯的區別所在。
你不是讓它從空白提示字元開始寫 SQL 語句,而是讓它和你一起瀏覽資料倉儲。
首先用淺顯易懂的英語:
Find all tables related to customers that I have write access to.
然後縮小範圍:
List every table tagged PII = TRUE in ANALYTICS_DB and show the owning roles.
然後詢問血統:
Show the lineage from RAW_DB.ORDERS to downstream dashboards.
在Snowsight中,使用@提及功能可以將物件直接附加到聊天上下文中,然後再提出後續問題。
例子:
@RAW_DB.ORDERS @ANALYTICS_DB.CUSTOMERS
Explain the likely join path between these objects and tell me which columns you would trust for churn analysis.
如果您在命令列介面 (CLI) 中,並且想要快速執行備用查詢,請使用/sql 。在互動式 CLI 中,使用Ctrl+J可以輸入多行 SQL 語句。
/sql
SELECT table_catalog, table_schema, table_name
FROM SNOWFLAKE.ACCOUNT_USAGE.TABLES
WHERE deleted IS NULL
AND (
table_name ILIKE '%CUSTOMER%'
OR table_schema ILIKE '%CUSTOMER%'
)
ORDER BY created DESC;
通用代理在給定模式後表現尚可。但如果需要自行尋找模式,Cortex Code 則更勝一籌。
要注意的是: SNOWFLAKE.ACCOUNT_USAGE.TABLES只是一個方便的備用方案,並非通用或即時的資料發現介面。它依賴您對ACCOUNT_USAGE的存取權限,而這些視圖可能會有延遲。
權限錯誤會浪費大量時間,因為它們起初看起來像是程式碼錯誤。
實用提示:
What privileges does my role have on this database?
Why am I getting a permissions error on ANALYTICS_DB.CORE.CUSTOMERS?
Show the grants my current role can see for ANALYTICS_DB.CORE.CUSTOMERS, and tell me what extra visibility I would need for a full access audit.
Find all tables that have PII in them.
這正是通用編碼代理通常會遇到的瓶頸。它們可以解釋基於角色的存取控制(RBAC)的概念,而Cortex Code可以幫助你研究真實的Snowflake物件以及你目前角色實際上可以存取的所有權限。
使用 Cortex Code 的最佳方法之一是給它實際存在的 SQL 語句,並要求它改進這些 SQL 語句。
What does this SQL script do?
Explain why this query is slow and optimize it without changing semantics.
WITH daily_revenue AS (
SELECT
customer_id,
CAST(order_date AS DATE) AS order_day,
SUM(amount) AS daily_revenue
FROM ANALYTICS_DB.MART.ORDERS
WHERE order_date >= DATEADD(day, -90, CURRENT_DATE())
GROUP BY 1, 2
)
SELECT
a.customer_id,
a.order_day,
a.daily_revenue,
(
SELECT SUM(b.daily_revenue)
FROM daily_revenue b
WHERE b.customer_id = a.customer_id
AND b.order_day BETWEEN DATEADD(day, -6, a.order_day) AND a.order_day
) AS rolling_7d_revenue
FROM daily_revenue a
ORDER BY a.customer_id, a.order_day;
然後繼續深入:
Show me the tradeoffs in your rewrite.
If there are multiple good versions, rank them by readability, cost, and likely performance.
在Snowsight中,您還可以使用內建的修復流程來處理失敗的 SQL,然後在同一上下文中提出後續問題。
這一點很重要。優秀的資料工作幾乎從來都不是“寫一個查詢語句”,而是“編寫、檢查、修復、重新執行、比較”。
從這裡開始,Cortex Code 開始獲得永久終端空間。
最顯著的模式是:
在正確的工作目錄中開啟包含 Cortex Code 的倉庫。
要求提供計劃。
進行模型變更。
執行最窄範圍的dbt選擇器。
提供證據,而不僅僅是程式碼。
開始會話:
cortex -c dev -w ~/src/analytics
然後開啟規劃模式:
/plan
然後給它一個具體的任務:
Update models/marts/fct_customer_revenue.sql to include refunded_amount.
Run the smallest safe dbt build for the affected graph.
If tests fail, fix the model or tests.
Then write a validation query comparing dev and prod totals for the last 30 days.
Save the validation SQL in analysis/refunded_amount_check.sql.
這比“加入退款金額”的提示更好,因為它要求提供完整的流程,包括證明。
這是你能為dbt做的最有槓桿作用的事情之一。
AGENTS.md
# analytics repo rules
- Always use fully qualified object names in generated SQL unless the model style already abstracts them.
- For changes to marts, metrics, or business logic, generate a validation query in `analysis/`.
- Prefer `TRY_TO_*` functions for raw ingestion cleanup.
- For model changes, start with `dbt build -s "<changed_model>+"` to validate the changed model and downstream dependents. Use `dbt ls -s "+<changed_model>"` when you want to inspect upstream ancestors first.
- Add or update schema tests for every new key, enum, or non-null business field.
- Never use production roles for write operations.
- When a change touches finance metrics, compare dev and prod for at least the last 30 days.
現在,Cortex Code 會在開始進行更改之前先讀取您的規則。
好的dbt行為療法提示:
Create a new staging model for RAW.CUSTOMERS that handles duplicates, mixed-case email, malformed dates, and empty-string fields.
Analyze this dbt project and identify the smallest set of models I need to run after changing fct_customer_revenue.
Show me the upstream and downstream graph for this model and tell me where a breaking change would hurt the most.
Review the failing dbt tests and tell me whether the bug is in the model, test assumptions, or source data.
有時,最佳模式是對話推理加上直接執行 shell 指令:
/sh dbt build -s "fct_customer_revenue+"
/sh dbt ls -s "+fct_customer_revenue"
/sh dbt docs generate
第一條指令驗證修改後的模型及其下游相依性。第二個指令顯示上游祖先關係,以便您在擴大 blast 半徑之前檢查依賴關係。
如果你想暫時保持在 shell 模式下,可以執行不含任何參數的/sh 。命令列介面會切換到終端模式,並將後續輸入視為 shell 命令,直到你退出該模式為止。
如果你需要血統上的幫助,請直接提出:
/lineage fct_customer_revenue
然後問:
Based on the lineage, which models should I validate manually before merging this change?
這裡提供的 Snowflake 內部範例尤其出色。
常用的提示模式有:
Analyze our dbt project, identify the slowest-running models, suggest specific optimizations, and flag any models that are not used downstream that we could drop.
這可能會暴露出一些人們在流程「執行」後通常不會再去關注的問題:
糟糕的物質選擇
不必要的連接
過時的模型,沒有後續價值
不應完全刷新的增量模型
可能需要拆分的模型
經過良好的優化之後,最好的做法是將其轉化為技能。
這是經常被忽略的差異化因素之一。
如果你每週都要進行同樣的除錯或優化操作,那就把它打包起來。
對於本地倉庫或 CLI 工作流程,專案技能位於.cortex/skills/目錄下。在Snowsight工作區中,個人技能位於該工作區的.snowflake/cortex/skills目錄下,並且僅在該工作區可用。
建立目錄:
mkdir -p .cortex/skills/dbt-slow-model-audit
然後加入SKILL.md :
---
name: dbt-slow-model-audit
description: Find slow dbt models and propose safe optimizations
---
# When to use
- The user wants to reduce runtime or credits in a dbt project.
- The user suspects one or more models are bottlenecks.
# Instructions
1. Identify the slowest models using available dbt artifacts or warehouse history.
2. Inspect materialization strategy, joins, filters, and incremental logic.
3. Flag unused downstream models that may be removable.
4. Propose the smallest set of changes that will improve runtime safely.
5. Generate a validation plan and save findings in `analysis/dbt_slow_model_audit.md`.
本範例特意保持 frontmatter 的簡潔。 toolstools:是可選的。如果您想將某個技能鎖定到特定的工具集,請使用目前 Cortex Code 文件或已知可用的技能倉庫中的確切工具辨識碼。另請注意,目前 CLI 的自訂技能模型是文件最完善的方案。在Snowsight`中,請堅持使用已記錄的個人技能。
列出可用技能:
cortex skill list
會議期間:
/skill
這就是如何將「經紀人曾經做過的那件聰明事」轉化為團隊工作流程的方法。
如果你的世界裡有 Airflow,那麼 Cortex Code 就比一般的 Python 輔助函數更有趣了。
這假設您已經為 Cortex Code 配置了 Airflow 實例並安裝了uv ,正如 Snowflake 的《將Using Apache Airflow with Cortex Code CLI文件所要求的那樣。
一個值得注意的實作細節: cortex airflow是 Snowflake 自帶的 Airflow 輔助工具的直通封裝。請將以下範例視為實際的命令模式,而不是由主 CLI 完全擁有的、單獨文件化的原生命令語法。
實用命令:
cortex airflow health
cortex airflow dags list
cortex airflow dags get daily_etl
cortex airflow dags source daily_etl
cortex airflow runs trigger daily_etl
cortex airflow runs list daily_etl
實用提示:
Why did my_pipeline fail last night?
Create a DAG that extracts from Snowflake and loads to S3 daily.
Set up my dbt project to run in Airflow using Cosmos.
Migrate my DAGs from Airflow 2 to Airflow 3.
這正是 Cortex Code 優勢的絕佳例證。通用編碼代理可以編寫 DAG 程式碼,而 Cortex Code 則可以在同一個地方處理 DAG、Airflow 實例以及 Snowflake 工作流程端的邏輯關係。
不要強制所有操作都透過命令列介面 (CLI) 進行。
Snowsight非常適合處理人們通常會為了處理的事情而中斷工作流程:
快速編寫 SQL
找到正確的表格或列
修復失敗的 SQL
檢查使用者和角色存取權限
成本和使用問題
在工作區中使用差異審查迭代程式碼
在Snowsight中效果良好的範例提示:
What databases do I have access to?
Write a query for top 10 customers by revenue and a 7-day moving average.
Which 5 service types are using the most credits? Show me a visualization and how to reduce costs.
Find all tables that have PII in them.
Snowsight在日常工程工作中最強大的功能可能是最簡單的:您可以留在編寫和執行查詢的同一環境中。
這是大家最關心的部分,所以這裡就直截了當地說一下。這些是實際工作流程的比較,而不是廠商的基準測試。通用編碼代理的功能很大程度上取決於你如何將其與 shell、資料庫、MCP 伺服器和其他工具整合。
| 任務 | 通用編碼代理 | Cortex Code 優勢 |
| :---- | :---- | :---- |
| 僅憑業務概念查找合適的表 | 在沒有 Snowflake 感知集成的情況下,通常需要粘貼模式或單獨的元資料查詢 | 可以直接搜尋 Snowflake 物件和文件,並在可用時顯示標籤和血緣關係 |
| 偵錯角色或權限問題 | 可以解釋基於角色的存取控制 (RBAC) 模式,但通常需要 Snowflake 即時存取權限來檢查實際的權限授予 | 可以利用您當前的 Snowflake 存取權限來幫助調查權限和存取問題 |
| 優化倉庫中執行緩慢的查詢 | 可以從 SQL 文本中進行推理,但通常需要配置 Snowflake 存取權限才能獲得特定於倉庫的答案 | 可以根據 Snowflake 上下文、文件和帳戶感知模式進行工作 |
| 編輯dbt模型並驗證更改的安全性 | 擅長程式碼編輯,但除非將查詢和工具整合到工作流程中,否則可能無法了解 Snowflake 的即時狀態 | 可以在一個工作流程中協助處理 SQL、 dbt 、驗證查詢和 Snowflake 端驗證 |
| 在 Snowflake 上選擇模型模式 | 除非能夠檢查 Snowflake 物件和文件,否則僅提供一般建議 | 針對語義物件、平台行為和角色感知執行的 Snowflake 感知指導 |
| 建置涉及 SQL、檔案、shell 和帳戶狀態的資料工作流程 | 整合 shell、資料庫和元資料工具後效果更佳;開箱即用功能較少 | 原生支援混合資料工程工作流程 |
| 支援 Airflow 和 Snowflake 除錯 | 精通 Python,依賴 Airflow 和 Snowflake 集成來獲取實時實例上下文 | 內置 Airflow 支持,並具備 Snowflake 感知推理能力 |
最簡單的概括仍然適用:
如果答案取決於您的 Snowflake 帳戶,請使用 Cortex Code。
如果答案取決於大型非 Snowflake 程式碼庫或前端技術棧,那麼通用編碼代理程式可能是更好的首選工具。
坦誠面對這一點吧。 Cortex Code 並非萬用工具。
執行下列操作時,請先使用 Cursor、Claude Code 或 Codex:
前端工作
框架密集應用鷹架
跨大型非 Snowflake 服務的多語言重構
本地程式碼庫推理,其中倉庫上下文無關緊要
對大多數團隊來說,最佳方案並非人員替換,而是結對協作。
使用您最喜歡的通用編碼代理進行全庫工程。當工作從純軟體工程轉變為資料工程時,請使用 Cortex Code。
如果你想認真使用 Cortex Code,養成一些好習慣大有裨益。
/plan
這在進行架構更改、大規模dbt執行以及任何涉及生產物件的操作之前尤其有用。
不要靠感覺來確保代理人的安全,要透過人脈和角色來確保安全。
這聽起來顯而易見,但這正是「有用的加速器」和「昂貴的故事」之間的界線。
AGENTS.md中不要依賴模型來猜測團隊的驗證和推廣標準。
這樣可以確保操作的可重複性,並使步驟可檢查。
ACCOUNTADMIN如果需要更高的配置,請特意去做。不要將其作為預設的開發方式。
這些是我真正會保留下來的提示。
Find all tables related to customers that I have write access to.
List every table tagged PII = TRUE in ANALYTICS_DB and show the owning roles.
Show the lineage from RAW_DB.ORDERS to downstream dashboards.
Why am I getting a permissions error on ANALYTICS_DB.CORE.CUSTOMERS?
What does this SQL script do?
Explain why this query is slow and optimize it without changing semantics.
Write a query for top 10 customers by revenue and add a 7-day moving average.
Create a staging model for RAW.CUSTOMERS that handles duplicates, malformed dates, empty strings, and mixed-case emails.
Update models/marts/fct_customer_revenue.sql to include refunded_amount, run the smallest safe dbt selector, and generate a dev-versus-prod validation query.
Analyze this dbt project, identify the slowest-running models, and suggest the smallest safe changes to reduce runtime and credits.
Why did my_pipeline fail last night?
Create a DAG that extracts from Snowflake and loads to S3 daily.
Set up my dbt project to run in Airflow using Cosmos.
In a local repo, turn this repeated optimization workflow into a Skill and save it in .cortex/skills/dbt-slow-model-audit.
理解 Cortex Code 的最佳方式是將其視為資料工作的更佳工作流程壓縮方案。
這一點在強有力的用例中反覆出現:
dbt變更、測試和驗證
模式發現、血緣關係與治理
查詢調優以及帳戶上下文
Airflow 和 Snowflake 除錯
重複的工作流程轉化為技能
這就是為什麼它與僅支援程式碼倉庫的代理感覺不同的原因。它不僅幫助你編寫當前步驟,還能幫助你完成整個流程,而不會失去上下文。
如果你是資料工程師,那麼這部分內容就值得你關注了。
原文出處:https://dev.to/snowflake/the-data-engineers-cortex-code-cheat-sheet-3b60