carto-spatial-enrichment

Spatial Enrichment in CARTO Workflows

Prerequisites: Load carto-create-workflow for the development process — it covers both access paths (the MCP server's workflow tools such as create_workflow, validate_workflow, and run_workflow when attached; the carto workflows CLI otherwise; routing signals in carto-basics/references/access-paths.md). There is no direct enrichment MCP tool — enrichment always runs as a Workflow, so route through those workflow tools.

This skill covers the universal pattern for enriching spatial data with demographics, risk scores, or any variable from a spatial features dataset.

---

Instructions

Follow the 5-step universal enrichment pattern. Each step maps to one or more workflow components.

Step 1: Load source data

Load the business entities (stores, points, polygons) that need enrichment.

• Points or polygons from a table: use a ReadTable source node
• Custom geometry: use native.tablefromgeojson to inline a GeoJSON polygon

Step 2: Define target area

Choose one method based on the use case:

Method	Component	When to use
Buffer	native.buffer	Distance-based area (e.g. 1km around each store)
Isochrones	native.isolines	Drive-time or walk-time areas
Direct polygon	(none needed)	Source data is already polygons
Direct points	(none needed)	Skip to Step 4 with native.enrichpoints

Step 3: Spatial indexing (polyfill)

Convert areas into a grid for enrichment. This step is required when using grid-based enrichment (native.h3enrich) or manual JOIN.

• H3 grid (most common): native.h3polyfill -- set resolution to match the enrichment dataset
• Quadbin grid: native.quadbinpolyfill -- set resolution to match the enrichment dataset

Key decision -- index type: Use H3 unless the enrichment data is natively in Quadbin.

Step 4: Enrich

Two approaches, each with different column naming:

A) CARTO ENRICH procedures (recommended for Data Observatory or spatial features data):

• native.h3enrich -- enrich an H3 grid
• native.enrichpoints -- enrich points directly (skip Step 3)
• native.enrichpolygons -- enrich polygons directly (skip Step 3)
• Output columns are named {variable}_{aggregation} (e.g. population_sum, air_quality_avg)

native.enrichpolygons vs native.spatialjoin + native.groupby — both bypass the grid step (Step 3) and aggregate a source dataset directly onto target polygons. Pick by these trade-offs:

Approach	Pros	Cons
native.enrichpolygons	One node; dedicated UI in Workflows; semantically clearest	Analytics Toolbox dependency; intermediate joined rows aren't inspectable; aggregation methods constrained to the SelectColumnAggregation list
native.spatialjoin + native.groupby	No AT dependency; intermediate joined table is inspectable in Workflows; full control over join predicate (intersects / covers / touches), join type, and column aliasing	Two nodes; verbose; must set maintablecolumns / secondarytablecolumns on the spatial join to keep the schema tight

Default to native.enrichpolygons for simple sum/avg of a single source onto target polygons. Switch to native.spatialjoin + native.groupby when you need a non-default predicate, multiple aggregations on the same column, or visibility into the intermediate join. The same trade-off applies between native.enrichpoints and the equivalent spatialjoin + groupby chain for point targets.

B) Manual JOIN on the spatial index column:

• Use native.join with the H3/Quadbin column as the join key
• Output columns from the secondary table get a _joined suffix
• Default is INNER JOIN (silently drops unmatched cells)

Aggregation method guidance:

• SUM -- population counts, totals
• MAX / MIN -- risk scores, thresholds
• AVG -- quality metrics, indices

Step 5: Save results

Use native.saveastable to persist the enriched output.

If the goal is per-entity enrichment (e.g. population per store), add a second JOIN + GROUP BY to aggregate grid-level results back to the source entity level.

Success: A validated workflow that loads source data, defines areas, enriches with the correct aggregation, and saves — with downstream column references matching the enrichment method used. Upload via create_workflow (MCP) or carto workflows create (CLI).

---

Gotchas

• Provider casing & SQL dialect. This skill documents output column names in lowercase (population_sum, air_quality_avg, <column>_joined, etc.) — BigQuery / Databricks / Postgres / Redshift convention. On Snowflake, unquoted identifiers surface UPPERCASE — reference them as POPULATION_SUM, AIR_QUALITY_AVG, <COLUMN>_JOINED. See carto-create-workflow/references/providers/<provider>.md for casing rules and SQL dialect equivalents.
• Resolution alignment is critical. The polyfill resolution MUST match the enrichment dataset's native resolution (e.g. H3 resolution 8 with resolution 8 spatial features). A mismatch produces zero JOIN matches with NO error.
• Manual JOIN drops unmatched cells. native.join defaults to INNER JOIN, silently dropping cells with no enrichment data. Use LEFT JOIN if completeness matters.
• Deduplicate after polyfill. Use SELECT DISTINCT or GROUP BY on the index column to remove duplicate cells. If you need to preserve source identity (e.g. which store each cell came from), set includecols: true in the polyfill node.
• Column naming differs by method (see Step 4): ENRICH procedures produce {variable}_{aggregation}; manual JOIN produces {column}_joined.
• Buffer distance is in meters. Isoline range units depend on type: seconds for time-based, meters for distance-based.
• Re-aggregation needed for entity-level results. Grid enrichment leaves data at the cell level; add a second JOIN + GROUP BY to roll it back to per-store / per-location totals (see Step 5).

---

Reference Templates

Templates included in this skill folder (from the CARTO Workflows template repository):

File	Pattern	Description
enrich_grid.json	GeoJSON polygon -> H3 polyfill -> ENRICH_GRID	Enrich a custom area with sociodemographic H3 data
enrich_points.json	Filter points -> ENRICH_POINTS	Enrich point locations with polygon-based risk data
estimate_population_around_retail_stores.json	Points -> Buffer -> H3 polyfill -> JOIN -> GROUP BY	Full entity-level enrichment with re-aggregation

---

Common Variations

Variation	Steps used	Key differences
Enrich points directly	1 -> 4 -> 5	Skip grid; use native.enrichpoints
Enrich polygons directly	1 -> 4 -> 5	Skip grid; use native.enrichpolygons
Buffer + grid enrichment	1 -> 2 -> 3 -> 4 -> 5	native.buffer then polyfill then enrich
Isochrone + grid enrichment	1 -> 2 -> 3 -> 4 -> 5	native.isolines then polyfill then enrich
Re-aggregate to source entity	1 -> 2 -> 3 -> 4 -> JOIN + GROUP BY -> 5	Add second JOIN to map cells back to source entities