用途
Snowflake 的 lineage 图原生只跟踪账户内的对象。要把数据从外部系统（Postgres、MySQL、S3、Kafka、DB2、Trino 等）流入或流出 Snowflake 的关系展示出来，需要向外部血缘 REST 端点 POST OpenLineage COMPLETE 事件。事件被接受后，外部节点会出现在 Snowsight 的 Catalog → Database Explorer → [表] → Lineage 中。
该技能覆盖三类任务：构建合法的 OpenLineage 载荷；使用现有 Snowflake 连接（无需额外管理令牌）发送事件；在数据源退役时删除外部血缘关系。
前置条件
- 账户上的 INGEST LINEAGE 权限（删除操作需要 DELETE LINEAGE）。
- 一个活跃的 cortex 连接，或一个 Programmatic Access Token (PAT)。
- Python 依赖：requests、snowflake-connector-python。
使用方式
第 1 步：确认权限与目标
执行 SHOW GRANTS ON ACCOUNT; 查找授予当前角色的 INGEST LINEAGE，并用 DESCRIBE TABLE <db>.<schema>.<table>; 确认目标表。若权限缺失应告知用户，由管理员执行 GRANT INGEST LINEAGE ON ACCOUNT TO ROLE <role>;，未经明确批准不要自行执行。
第 2 步：构建载荷
载荷示例包含 eventType、eventTime、job、run、producer、schemaURL、inputs、outputs 字段。规则：eventType 必须为 COMPLETE，其他类型会被忽略；inputs 与 outputs 需混合 Snowflake 与外部对象；外部对象不要包含 facets，否则会默认渲染为 "External Node"；各来源的 namespace 格式见 namespace_conventions.md。此步骤设有停止点：发送前应先向用户展示载荷并等待确认。
第 3 步：发送事件
首选使用 Cortex Code 连接：SNOWFLAKE_CONNECTION_NAME=<connection> python <SKILL_DIR>/send_lineage_via_connection.py -p payload.json。也可先生成再发送：<SKILL_DIR>/generate_payload.sh -a <ACCOUNT> -o <DB>.<SCHEMA>.<TABLE> -i 'postgres://host:5432::db.schema.source' -f /tmp/payload.json，随后用上述 Python 命令发送。PAT 方式：<SKILL_DIR>/send_lineage.sh -a <ACCOUNT> -t token.txt -p payload.json。
第 4 步：验证
打开 Snowsight → Catalog → Database Explorer → 目标表 → Lineage 标签页，传播需要 1–2 分钟。
第 5 步：删除外部血缘（可选）
发送 DELETE 前需确认源与目标。使用 curl 调用 /api/v2/lineage/external-lineage 端点，参数包括 sourceNamespace、sourceName、sourceDatasetType、targetName、targetDatasetType。删除范围：同时指定源和目标则断开该条链接；只指定源则断开该源的全部下游；只指定目标则把目标从图中移除。端点始终返回 HTTP 200，必须在 Snowsight 中验证是否真的删除。
常见错误
- eventType 不是 COMPLETE，会被静默丢弃。
- 账户 URL 中使用下划线，应改用连字符（ORG-ACCOUNT）。
- curl 忘记加
--globoff，导致 External%20Node 被错误处理。 - 在外部节点上包含 facets，破坏 "External Node" 渲染。
- 把 DELETE 的 200 当作成功，应在 Snowsight 验证。
- 删除方向不匹配：创建时外部对象是 INPUT，删除时就必须作为 source。
- 忽略大小写：namespace 与 name 区分大小写。
限制
- 保留期为 1 年，每账户最多 10,000 个事件。
- FQN 最长 1000 字符。
- 不支持列级血缘。
- GET_LINEAGE 不会返回外部血缘。
参考文件
namespace_conventions.md（各来源的 namespace 格式）、token_setup.md（创建 PAT）、troubleshooting.md（401/403/404 修复）、send_lineage_via_connection.py（推荐的发送器）、send_lineage.sh（基于 PAT 的发送器）、generate_payload.sh（载荷构建器）。
适用场景
需要在 Snowflake 血缘视图中展示外部数据源、以 OpenLineage 事件补充跨系统数据流、或清理已下线外部数据源血缘关系的数据工程与运维场景。