用途
本技能用于在用户请求 Snowflake SQL、数据管道、Cortex AI 或 Snowpark Python 相关帮助时，提供 Snowflake 专属的开发指导；也包括 dbt、性能调优与安全加固方面的 Snowflake 特定建议。
SQL 最佳实践
命名与风格方面：所有标识符使用 snake_case；避免使用双引号标识符，因为其创建区分大小写的名称并需要持续加引号；优先使用 CTE（WITH 子句）而非嵌套子查询；使用 CREATE OR REPLACE 实现幂等 DDL；生产环境使用显式列清单，不要 SELECT *，因为 Snowflake 列式存储仅扫描被引用的列。
存储过程的冒号前缀规则：在 SQL 存储过程（BEGIN...END 块）中，SQL 语句内的变量与参数必须加冒号 : 前缀，否则 Snowflake 会报“invalid identifier”错误。示例（保留原文）：
BAD： CREATE PROCEDURE my_proc(p_id INT) RETURNS STRING LANGUAGE SQL AS BEGIN LET result STRING; SELECT name INTO result FROM users WHERE id = p_id; RETURN result; END;
GOOD： CREATE PROCEDURE my_proc(p_id INT) RETURNS STRING LANGUAGE SQL AS BEGIN LET result STRING; SELECT name INTO :result FROM users WHERE id = :p_id; RETURN result; END;
半结构化数据：VARIANT、OBJECT、ARRAY 用于 JSON/Avro/Parquet/ORC；访问嵌套字段使用 src:customer.name::STRING，并始终转换类型如 src:price::NUMBER(10,2)；VARIANT null 与 SQL NULL 不同，JSON null 存储为 "null"，加载时使用 STRIP_NULL_VALUE = TRUE；展开数组示例：SELECT f.value:name::STRING FROM my_table, LATERAL FLATTEN(input => src:items) f;
MERGE 用于上插：提供 MERGE INTO 目标表 USING 源表 的完整语句，MATCHED 时更新、NOT MATCHED 时插入，并使用 CURRENT_TIMESTAMP()。
数据管道
方案选型表：Dynamic Tables 用于声明式转换，为默认选择，定义查询后由 Snowflake 处理刷新；Streams + Tasks 用于命令式 CDC，适合过程逻辑与存储过程调用；Snowpipe 用于从 S3/GCS/Azure 持续加载文件。
Dynamic Tables：提供 CREATE OR REPLACE DYNAMIC TABLE 示例，设置 TARGET_LAG = '5 minutes'、WAREHOUSE 与查询。关键规则：TARGET_LAG 逐层递进设置，顶层更紧、底层更松；增量 DT 不能依赖全量刷新的 DT；SELECT * 会在模式变更时出错，使用显式列清单；基表必须保持变更跟踪启用；视图不能夹在两个 Dynamic Tables 之间。
Streams 和 Tasks：提供创建 STREAM 与 TASK 的示例，Task 使用 WAREHOUSE、SCHEDULE（USING CRON）、WHEN SYSTEM$STREAM_HAS_DATA 条件以及 INSERT 语句；注意 Task 创建后处于 SUSPENDED 状态，必须用 ALTER TASK ... RESUME 恢复。
Cortex AI
函数参考表：AI_COMPLETE 用于 LLM 补全（文本、图像、文档）；AI_CLASSIFY 分类，最多 500 个标签；AI_FILTER 对文本/图像做布尔过滤；AI_EXTRACT 从文本/图像/文档做结构化抽取；AI_SENTIMENT 情感评分（-1 到 1）；AI_PARSE_DOCUMENT 做 OCR 或布局抽取；AI_REDACT 去除 PII。已弃用函数（不要使用）：COMPLETE、CLASSIFY_TEXT、EXTRACT_ANSWER、PARSE_DOCUMENT、SUMMARIZE、TRANSLATE、SENTIMENT、EMBED_TEXT_768。
TO_FILE 常见错误来源：stage 路径与文件名是两个独立参数，示例 BAD：TO_FILE('@stage/file.pdf')；GOOD：TO_FILE('@db.schema.mystage', 'invoice.pdf')。
分类应使用 AI_CLASSIFY 而非 AI_COMPLETE，示例：SELECT AI_CLASSIFY(ticket_text, ['billing', 'technical', 'account']):labels[0]::VARCHAR AS category FROM tickets;
Cortex Agents：提供 CREATE OR REPLACE AGENT 结合 $spec$ 的规范示例，包含 models、instructions、tools、tool_resources。Agent 规则：使用 $spec$ 分隔符而非 $$；models 必须为对象而非数组；tool_resources 是独立顶层对象，不嵌套在 tools 内；编辑规范中不要包含空值/null，否则会清除已有值；工具描述是质量的第一要素；不要直接修改生产 Agent，先克隆。
Snowpark Python
提供 Session.builder.configs 的代码示例，从环境变量读取账号、用户、密码，并设置 role、warehouse、database、schema。要点：绝不硬编码凭据；DataFrame 是惰性的，在 collect()/show() 时才执行；不要对大型 DataFrame 使用 collect()，应在服务端处理；批量/ML 工作负载使用向量化 UDF（快 10-100 倍）而非标量 UDF。
dbt on Snowflake
Dynamic table 物化（流式/近实时集市）：{{ config(materialized='dynamic_table', snowflake_warehouse='transforming', target_lag='1 hour') }}。 增量物化（大型事实表）：{{ config(materialized='incremental', unique_key='event_id') }}。 Snowflake 特定配置（可与任意物化组合）：{{ config(transient=true, copy_grants=true, query_tag='team_daily') }}。 规则：不要在未使用 {% if is_incremental() %} 保护的情况下使用 {{ this }}；流式/近实时集市使用 dynamic_table 物化。
性能
聚簇键：仅用于多 TB 表，选择 WHERE/JOIN/GROUP BY 列。搜索优化：ALTER TABLE t ADD SEARCH OPTIMIZATION ON EQUALITY(col);。仓库规格：从 X-Small 起步，按需扩容；AUTO_SUSPEND = 60，AUTO_RESUME = TRUE；按工作负载分离仓库。先估算 AI 成本：SELECT SUM(AI_COUNT_TOKENS('claude-4-sonnet', text)) FROM table;。
安全
遵循最小权限 RBAC；使用数据库角色做对象级授权；定期审计 ACCOUNTADMIN：SHOW GRANTS OF ROLE ACCOUNTADMIN;；使用网络策略做 IP 白名单；对 PII 列使用脱敏策略，对多租户隔离使用行访问策略。
常见错误模式
表格列出："Object does not exist" 因上下文错误或缺少授权，修复方式为完全限定名称并检查授权；存储过程中 "Invalid identifier" 因缺少冒号前缀，使用 :variable_name；"Numeric value not recognized" 因 VARIANT 未转换，使用 src:field::NUMBER(10,2)；Task 不运行因忘记恢复，使用 ALTER TASK ... RESUME；DT 刷新失败因模式变更或跟踪关闭，使用显式列并检查变更跟踪。
限制
仅在任务明确匹配上述范围时使用本技能。不要将输出视为环境特定验证、测试或专家审查的替代。若缺少必需输入、权限、安全边界或成功标准，应停止并请求澄清。