name: snowflake-developmentdescription: “Comprehensive Snowflake development assistant covering SQL best practices, data pipeline design (Dynamic Tables, Streams, Tasks, Snowpipe), Cortex AI functions, Cortex Agents, Snowpark Python, dbt integration, performance tuning, and security hardening.”category:>Snowflake 开发你是 Snowflake 开发专家。在编写 SQL、构建数据管道、使用 Cortex AI 或在 Snowflake 上使用 Snowpark Python 时应用这些规则。何时使用当用户请求有关 Snowflake SQL、数据管道、Cortex AI 或 Snowpark Python 的帮助时。当你需要针对 dbt、性能调优或安全加固的 Snowflake 特定指导时。SQL 最佳实践命名与风格对所有标识符使用snake_case。避免使用双引号标识符——它们会创建区分大小写的名称需要不断加引号。使用 CTEWITH子句而不是嵌套子查询。使用CREATE OR REPLACE实现幂等的 DDL。使用显式列列表——生产环境中绝不要使用SELECT *Snowflake 的列式存储只扫描引用的列。存储过程——冒号前缀规则在 SQL 存储过程BEGIN…END 块中变量和参数必须在 SQL 语句内使用冒号:前缀。否则Snowflake 会报标识符无效错误。错误示例CREATEPROCEDUREmy_proc(p_idINT)RETURNSSTRINGLANGUAGESQLASBEGINLET result STRING;SELECTnameINTOresultFROMusersWHEREidp_id;RETURNresult;END;正确示例CREATEPROCEDUREmy_proc(p_idINT)RETURNSSTRINGLANGUAGESQLASBEGINLET result STRING;SELECTnameINTO:resultFROMusersWHEREid:p_id;RETURNresult;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 进行更新插入MERGEINTOtarget tUSINGsource sONt.ids.idWHENMATCHEDTHENUPDATESETt.names.name,t.updated_atCURRENT_TIMESTAMP()WHENNOTMATCHEDTHENINSERT(id,name,updated_at)VALUES(s.id,s.name,CURRENT_TIMESTAMP());数据管道选择你的方法方法何时使用动态表Dynamic Tables声明式转换。默认选择。定义查询Snowflake 负责刷新。流 任务Streams Tasks命令式 CDC。用于过程逻辑、存储过程调用。Snowpipe从 S3/GCS/Azure 持续加载文件。动态表CREATEORREPLACEDYNAMICTABLEcleaned_events TARGET_LAG5 minutesWAREHOUSEtransform_whASSELECTevent_id,event_type,user_id,event_timestampFROMraw_eventsWHEREevent_typeISNOTNULL;关键规则逐步设置TARGET_LAG上游更紧下游更松。增量动态表不能依赖于全量刷新动态表。模式更改会破坏SELECT *——请使用显式列列表。基础表必须保持启用更改跟踪。两个动态表之间不能放置视图。流和任务CREATEORREPLACESTREAM raw_streamONTABLEraw_events;CREATEORREPLACETASK process_events WAREHOUSEtransform_wh SCHEDULEUSING CRON 0 */1 * * * America/Los_AngelesWHENSYSTEM$STREAM_HAS_DATA(raw_stream)ASINSERTINTOcleaned_eventsSELECT...FROMraw_stream;-- 任务默认处于 SUSPENDED 状态——你必须恢复它们ALTERTASK process_events RESUME;Cortex AI函数参考函数用途AI_COMPLETELLM 补全文本、图像、文档AI_CLASSIFY分类到类别中最多 500 个标签AI_FILTER对文本/图像进行布尔过滤AI_EXTRACT从文本/图像/文档中结构化提取AI_SENTIMENT情感评分-1 到 1AI_PARSE_DOCUMENTOCR 或版面提取AI_REDACTPII 移除已弃用请勿使用COMPLETE、CLASSIFY_TEXT、EXTRACT_ANSWER、PARSE_DOCUMENT、SUMMARIZE、TRANSLATE、SENTIMENT、EMBED_TEXT_768。TO_FILE —— 常见错误来源阶段路径和文件名是独立的参数-- 错误TO_FILE(stage/file.pdf)-- 正确TO_FILE(db.schema.mystage,invoice.pdf)使用 AI_CLASSIFY 进行分类而不是 AI_COMPLETESELECTAI_CLASSIFY(ticket_text,[billing,technical,account]):labels[0]::VARCHARAScategoryFROMtickets;Cortex 智能体AgentsCREATEORREPLACEAGENT my_db.my_schema.sales_agentFROMSPECIFICATION $spec$ {models: {orchestration:auto},instructions: {orchestration:You are SalesBot...,response:Be concise.},tools:[{tool_spec: {type:cortex_analyst_text_to_sql,name:Sales,description:Queries sales...}}],tool_resources: {Sales: {semantic_model_file:stage/model.yaml}} } $spec$;智能体规则使用$spec$分隔符而不是$$。models必须是对象而不是数组。tool_resources是独立的顶层对象不要嵌套在 tools 中。编辑规范中不要包含空/null 值——这会清除现有值。工具描述是头号质量因素。绝不要直接修改生产智能体——先克隆。Snowpark Pythonfromsnowflake.snowparkimportSessionimportos sessionSession.builder.configs({account:os.environ[SNOWFLAKE_ACCOUNT],user:os.environ[SNOWFLAKE_USER],password:os.environ[SNOWFLAKE_PASSWORD],role:my_role,warehouse:my_wh,database:my_db,schema:my_schema}).create()绝不要硬编码凭据。DataFrame 是惰性的——在collect()/show()时执行。不要对大型 DataFrame 使用collect()——在服务端处理。对于批处理/ML 工作负载使用向量化 UDF快 10-100 倍而不是标量 UDF。dbt on Snowflake动态表物化流式/近实时数据集市{{ config(materializeddynamic_table,snowflake_warehousetransforming,target_lag1 hour)}}增量物化大型事实表{{ config(materializedincremental,unique_keyevent_id)}}Snowflake 特定配置可与任何物化方式组合{{ config(transienttrue,copy_grantstrue,query_tagteam_daily)}}不要在没有{% if is_incremental() %}保护的情况下使用{{ this }}。对流式/近实时数据集市使用dynamic_table物化。性能聚类键Cluster keys仅用于多 TB 级表用在 WHERE/JOIN/GROUP BY 列上。搜索优化Search OptimizationALTER TABLE t ADD SEARCH OPTIMIZATION ON EQUALITY(col);仓库大小从 X-Small 开始再向上扩展。AUTO_SUSPEND 60AUTO_RESUME TRUE。每个工作负载使用独立的仓库。先估算 AI 成本SELECT SUM(AI_COUNT_TOKENS(claude-4-sonnet, text)) FROM table;安全遵循最小权限 RBAC。使用数据库角色进行对象级授权。定期审计 ACCOUNTADMINSHOW GRANTS OF ROLE ACCOUNTADMIN;使用网络策略进行 IP 白名单管理。对 PII 列使用掩码策略对多租户隔离使用行访问策略。常见错误模式错误原因修复“对象不存在”上下文错误或缺少授权完全限定名称检查授权存储过程中的标识符无效缺少冒号前缀使用:variable_name“无法识别数值”VARIANT 未转换src:field::NUMBER(10,2)任务未运行忘记恢复ALTER TASK ... RESUME动态表刷新失败模式更改或跟踪被禁用使用显式列检查更改跟踪限制仅当任务明确符合上述范围时使用此技能。不要将输出视为特定环境验证、测试或专家审查的替代品。如果缺少必需的输入、权限、安全边界或成功标准请停下来询问澄清。