carto-spatial-enrichment

CARTO 工作流中的空间增强

前提条件：在开发过程中加载 carto-create-workflow — 它涵盖两种访问方式（已连接时使用 MCP 服务的工作流工具，如 create_workflow、validate_workflow 和 run_workflow；否则使用 carto workflows CLI；路由信号见 carto-basics/references/access-paths.md）。没有直接的增强 MCP 工具 — 增强始终作为工作流运行，因此应通过这些工作流工具进行。

本技能介绍使用人口统计数据、风险评分或空间要素数据集中的任意变量来增强空间数据的通用模式。

---

说明

遵循通用的 5 步增强模式。每一步对应一个或多个工作流组件。

步骤 1：加载源数据

加载需要增强的业务实体（商店、点、面）。

• 表中的点或面：使用 ReadTable 源节点
• 自定义几何：使用 native.tablefromgeojson 内联 GeoJSON 多边形

步骤 2：定义目标区域

根据使用场景选择一种方法：

方法	组件	适用场景
缓冲区	native.buffer	基于距离的区域（例如每家商店周围 1km）
等时圈	native.isolines	驾车或步行时间区域
直接使用多边形	（无需）	源数据已经是多边形
直接使用点	（无需）	跳到步骤 4，使用 native.enrichpoints

步骤 3：空间索引（polyfill）

将区域转换为网格以进行增强。使用基于网格的增强（native.h3enrich）或手动 JOIN 时，必须执行此步骤。

• H3 网格（最常见）：native.h3polyfill -- 将 resolution 设置为与增强数据集匹配
• Quadbin 网格：native.quadbinpolyfill -- 将 resolution 设置为与增强数据集匹配

关键决策 — 索引类型：除非增强数据原生采用 Quadbin，否则使用 H3。

步骤 4：增强

两种方法，各自的列命名方式不同：

A）CARTO ENRICH 过程（推荐用于 Data Observatory 或空间要素数据）：

• native.h3enrich -- 增强 H3 网格
• native.enrichpoints -- 直接增强点（跳过步骤 3）
• native.enrichpolygons -- 直接增强多边形（跳过步骤 3）
• 输出列命名为 {variable}_{aggregation}（例如 population_sum、air_quality_avg）

native.enrichpolygons 与 native.spatialjoin + native.groupby 对比 — 两者都可跳过网格步骤（步骤 3），并将源数据集直接聚合到目标多边形上。可根据以下权衡进行选择：

方法	优点	缺点
native.enrichpolygons	单个节点；Workflows 中有专用 UI；语义最清晰	依赖 Analytics Toolbox；无法检查中间连接行；聚合方法受限于 SelectColumnAggregation 列表
native.spatialjoin + native.groupby	不依赖 AT；可在 Workflows 中检查中间连接表；可完全控制连接谓词（intersects / covers / touches）、连接类型和列别名	两个节点；较冗长；必须在空间连接上设置 maintablecolumns / secondarytablecolumns，以精简架构

对于将单个源数据聚合到目标多边形上的简单求和/平均，默认使用 native.enrichpolygons。需要非默认谓词、对同一列进行多种聚合，或查看中间连接结果时，改用 native.spatialjoin + native.groupby。对于点目标，native.enrichpoints 与对应的 spatialjoin + groupby 链也适用相同的权衡。

B）基于空间索引列的手动 JOIN：

• 使用 native.join，并将 H3/Quadbin 列作为连接键
• 次要表的输出列会添加 _joined 后缀
• 默认使用 INNER JOIN（会静默丢弃未匹配的网格单元）

聚合方法指南：

• SUM -- 人口数量、总量
• MAX / MIN -- 风险评分、阈值
• AVG -- 质量指标、指数

第 5 步：保存结果

使用 native.saveastable 持久化增强后的输出。

如果目标是按实体增强（例如每家门店的人口数），请添加第二个 JOIN + GROUP BY，将网格级结果聚合回源实体级别。

成功标准：工作流经过验证，能够加载源数据、定义区域、使用正确的聚合方式进行增强并保存；下游列引用与所用的增强方法一致。通过 create_workflow（MCP）或 carto workflows create（CLI）上传。

---

注意事项

• 提供商的大小写规则和 SQL 方言。 本技能中记录的输出列名均为小写（population_sum、air_quality_avg、<column>_joined 等），符合 BigQuery / Databricks / Postgres / Redshift 的惯例。在 Snowflake 上，未加引号的标识符会显示为大写——请使用 POPULATION_SUM、AIR_QUALITY_AVG、<COLUMN>_JOINED 引用。大小写规则和 SQL 方言对照请参阅 carto-create-workflow/references/providers/<provider>.md。
• 分辨率必须对齐，这一点至关重要。 填充多边形时使用的分辨率必须与增强数据集的原生分辨率一致（例如，H3 分辨率 8 要与分辨率为 8 的空间要素搭配）。不匹配会导致 JOIN 匹配数为零，且不会报错。
• 手动 JOIN 会丢弃未匹配的单元格。 native.join 默认为 INNER JOIN，会静默丢弃没有增强数据的单元格。如果需要保证数据完整性，请使用 LEFT JOIN。
• 填充多边形后去重。 使用 SELECT DISTINCT 或按索引列执行 GROUP BY，以移除重复单元格。如果需要保留源数据的标识（例如每个单元格所属的门店），请在填充多边形的节点中设置 includecols: true。
• 不同方法的列命名方式不同（见第 4 步）：ENRICH 过程会生成 {variable}_{aggregation}；手动 JOIN 会生成 {column}_joined。
• 缓冲区距离的单位是米。 等时线范围的单位取决于类型：基于时间的使用秒，基于距离的使用米。
• 实体级结果需要重新聚合。 网格增强会使数据保持在单元格级别；请添加第二个 JOIN + GROUP BY，将其汇总回每家门店／每个位置的总量（见第 5 步）。

---

参考模板

此技能文件夹中包含以下模板（来自 CARTO Workflows 模板仓库）：

文件	模式	描述
enrich_grid.json	GeoJSON 多边形 -> H3 填充多边形 -> ENRICH_GRID	使用社会人口统计 H3 数据增强自定义区域
enrich_points.json	筛选点 -> ENRICH_POINTS	使用基于多边形的风险数据增强点位置
estimate_population_around_retail_stores.json	点 -> 缓冲区 -> H3 填充多边形 -> JOIN -> GROUP BY	完整的实体级增强，并重新聚合

---

常见变体

变体	使用的步骤	主要区别
直接增强点	1 -> 4 -> 5	跳过网格；使用 native.enrichpoints
直接增强多边形	1 -> 4 -> 5	跳过网格；使用 native.enrichpolygons
缓冲区 + 网格增强	1 -> 2 -> 3 -> 4 -> 5	使用 native.buffer，然后填充多边形并增强
等时线 + 网格增强	1 -> 2 -> 3 -> 4 -> 5	使用 native.isolines，然后填充多边形并增强
重新聚合到源实体	1 -> 2 -> 3 -> 4 -> JOIN + GROUP BY -> 5	添加第二个 JOIN，将单元格映射回源实体