carto-territory-planning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Territory Planning (Territory Balancing + Location Allocation)

区域规划（区域平衡 + 位置分配）

Builds CARTO Workflows that solve two related spatial optimization problems: dividing areas into balanced territories (e.g. sales regions, service zones) and finding optimal facility locations that maximize coverage or minimize cost.

Prerequisites: Load

carto-create-workflow

for the development process, JSON structure, and validation commands. Both components require the Territory Planning Extension Package installed on the connection.

在CARTO中构建工作流，解决两类相关的空间优化问题：将区域划分为均衡的片区（如销售区域、服务区域），以及寻找能最大化覆盖范围或最小化成本的最优设施位置。

前提条件：开发过程、JSON结构和验证命令需加载

carto-create-workflow

。两个组件都要求连接上已安装区域规划扩展包。

Territory Balancing

区域平衡

Divides a study area into spatially contiguous territories that are balanced by a demand variable (e.g. workload, population, revenue).

将研究区域划分为空间上连续的片区，这些片区通过需求变量（如工作量、人口、收入）实现均衡。

Pipeline

流程

Source Data (points) -> Spatial Indexing -> Aggregate per Cell -> Territory Balancing -> Save

Source Data (points) -> Spatial Indexing -> Aggregate per Cell -> Territory Balancing -> Save

Step 1: Load Source Data

步骤1：加载源数据

Use

native.gettablebyname

. Input is typically point data with one or more numeric metrics to balance.

Success: Node outputs a table with a geometry column and numeric metric columns.

使用

native.gettablebyname

。输入通常是包含一个或多个用于均衡的数值指标的点数据。

成功标志：节点输出包含几何列和数值指标列的表格。

Step 2: Convert to Spatial Index

步骤2：转换为空间索引

Use

native.h3frompoint

(or

native.quadbinfromgeopoint

) to assign each point to a grid cell.

Resolution guidance: Higher resolution = smaller cells = finer-grained territories, but more computation. H3 resolution 8-9 is typical for city-level analysis.

Success: Output has a spatial index column (e.g.

h3

使用

native.h3frompoint

（或

native.quadbinfromgeopoint

）将每个点分配到网格单元中。

分辨率指南：分辨率越高 = 单元越小 = 片区粒度越细，但计算量越大。城市级分析通常使用H3分辨率8-9。

成功标志：输出包含空间索引列（如

h3

）。

Step 3: Aggregate per Cell

步骤3：按单元聚合

Use

native.groupby

to produce one row per cell with the metrics to balance:

Group by: the spatial index column (
```
h3
```
)
Aggregation: e.g.
```
geom,count,revenue,sum,population,avg
```

Success: One row per cell with numeric columns for demand and optional similarity features.

使用

native.groupby

生成每个单元一行的结果，包含用于均衡的指标：

分组依据：空间索引列（
```
h3
```
）
聚合方式：例如
```
geom,count,revenue,sum,population,avg
```

成功标志：每个单元一行，包含需求数值列和可选的相似性特征。

Step 4: Run Territory Balancing

步骤4：运行区域平衡

Use

native.territorybalancing

with:

Input	Description	Example
`input_table`	Table input (from previous step)
`index_column`	H3 or Quadbin column	`h3`
`demand_column`	Numeric column to balance across territories	`geom_count`
`similarity_feats`	Optional numeric columns for within-territory similarity	`["sentiment_avg", "popularity_avg"]`
`npartitions`	Number of territories to create	`9`
`keep_input_columns`	Include all input columns in output	`true`

Success: Output contains all input rows with an additional territory assignment column. Each cell is assigned to exactly one territory.

使用

native.territorybalancing

，参数如下：

输入	描述	示例
`input_table`	输入表格（来自上一步）
`index_column`	H3或Quadbin列	`h3`
`demand_column`	用于在各片区间均衡的数值列	`geom_count`
`similarity_feats`	片区内相似性的可选数值列	`["sentiment_avg", "popularity_avg"]`
`npartitions`	要创建的片区数量	`9`
`keep_input_columns`	在输出中包含所有输入列	`true`

成功标志：输出包含所有输入行，并新增一个片区分配列。每个单元被分配到恰好一个片区。

Step 5: Save

步骤5：保存

Use

native.saveastable

to persist results. The spatial index column is directly visualizable in CARTO Builder, colored by territory ID.

Success: Validated workflow uploadable via

carto workflows create

使用

native.saveastable

保存结果。空间索引列可直接在CARTO Builder中可视化，按片区ID着色。

成功标志：验证后的工作流可通过

carto workflows create

上传。

Location Allocation

位置分配

Finds the optimal subset of candidate facility locations that either maximize demand coverage or minimize total cost/distance.

寻找候选设施位置的最优子集，以最大化需求覆盖范围或最小化总成本/距离。

Pipeline

流程

Demand Data (grid/points) -> Candidate Locations -> Location Allocation -> Save

Demand Data (grid/points) -> Candidate Locations -> Location Allocation -> Save

Step 1: Load Demand Data

步骤1：加载需求数据

Use

native.gettablebyname

to load a grid or point dataset representing demand (e.g. population per H3 cell, customer locations).

Success: Table with a spatial index column and a numeric demand column.

使用

native.gettablebyname

加载代表需求的网格或点数据集（如每个H3单元的人口、客户位置）。

成功标志：包含空间索引列和数值需求列的表格。

Step 2: Load Candidate Locations

步骤2：加载候选位置

Use a second

native.gettablebyname

for potential facility locations (e.g. existing infrastructure, candidate sites).

If candidates need filtering, use

native.wheresimplified

native.limit

to reduce the set -- fewer candidates = faster computation.

Success: Table with a spatial index column representing candidate sites.

使用第二个

native.gettablebyname

加载潜在设施位置（如现有基础设施、候选站点）。

如果需要筛选候选位置，使用

native.wheresimplified

或

native.limit

减少候选集——候选越少 = 计算越快。

成功标志：包含代表候选站点的空间索引列的表格。

Step 3: Run Location Allocation

步骤3：运行位置分配

Choose the variant based on the objective:

根据目标选择变体：

Maximize Coverage

最大化覆盖范围

Use

native.locallocallocation_maximizecoverage

Input	Description	Example
`demand`	Table with demand values
`demand_index_column`	Spatial index column in demand table	`h3`
`demand_column`	Numeric demand variable	`population`
`candidates`	Table with candidate locations
`candidates_index_column`	Spatial index column in candidates table	`h3`
`nfacilities`	Number of facilities to open	`5`
`coverageradius`	Maximum service distance (meters for geography)	`5000`

Success: Output identifies which facilities to open and which demand cells each facility serves, maximizing total covered demand within the radius.

使用

native.locallocallocation_maximizecoverage

：

输入	描述	示例
`demand`	包含需求值的表格
`demand_index_column`	需求表格中的空间索引列	`h3`
`demand_column`	数值需求变量	`population`
`candidates`	包含候选位置的表格
`candidates_index_column`	候选表格中的空间索引列	`h3`
`nfacilities`	要开设的设施数量	`5`
`coverageradius`	最大服务距离（地理类型单位为米）	`5000`

成功标志：输出确定要开设的设施以及每个设施服务的需求单元，在半径内最大化总覆盖需求。

Minimize Total Cost

最小化总成本

Use

native.locallocallocation_minimizetotalcost

Input	Description	Example
`demand`	Table with demand values
`demand_index_column`	Spatial index column in demand table	`h3`
`demand_column`	Numeric demand variable	`population`
`candidates`	Table with candidate locations
`candidates_index_column`	Spatial index column in candidates table	`h3`
`nfacilities`	Number of facilities to open	`5`

Success: Output identifies which facilities to open, minimizing total weighted travel distance between demand and assigned facilities.

使用

native.locallocallocation_minimizetotalcost

：

输入	描述	示例
`demand`	包含需求值的表格
`demand_index_column`	需求表格中的空间索引列	`h3`
`demand_column`	数值需求变量	`population`
`candidates`	包含候选位置的表格
`candidates_index_column`	候选表格中的空间索引列	`h3`
`nfacilities`	要开设的设施数量	`5`

成功标志：输出确定要开设的设施，最小化需求与分配设施之间的总加权出行距离。

Step 4: Save

步骤4：保存

Use

native.saveastable

to persist results.

Success: Validated workflow uploadable via

carto workflows create

使用

native.saveastable

保存结果。

成功标志：验证后的工作流可通过

carto workflows create

上传。

Gotchas

注意事项

Provider casing & SQL dialect. This skill uses lowercase column names (
```
h3
```
,
```
geom_count
```
,
```
population
```
,
```
sentiment_avg
```
, etc.) — BigQuery / Databricks / Postgres / Redshift convention. On Snowflake, unquoted identifiers surface UPPERCASE — reference them as
```
H3
```
,
```
GEOM_COUNT
```
,
```
POPULATION
```
,
```
SENTIMENT_AVG
```
. See
```
carto-create-workflow/references/providers/<provider>.md
```
for casing rules and SQL dialect equivalents.
Extension package required: Both territory balancing and location allocation require the Territory Planning Extension Package installed on the specific connection being used. This is NOT available by default -- the user must have it installed. Validation will fail if the package is missing.
Location allocation is computationally expensive with many candidates. Pre-filter candidates (by geography, capacity, or other criteria) to keep the candidate set small. Hundreds of candidates can be slow; thousands may time out.
Coverage radius units depend on the spatial reference system -- typically meters when using geography types. Verify the unit matches your intent.
Territory balancing optimizes a trade-off between spatial contiguity and balance. Perfect balance is not guaranteed -- territories will be approximately equal in the demand variable, not exactly equal.
Grid resolution sensitivity: Results change significantly with the input grid resolution. Finer grids give more precise boundaries but increase computation. Start with H3 resolution 8 for city-scale and adjust.

The component names use

native.territorybalancing

(no dot separator in "territory balancing") and

native.locallocallocation_maximizecoverage

native.locallocallocation_minimizetotalcost

(note the double "local" prefix).

Demand data must cover the study area. Gaps in the demand grid mean those areas are invisible to the optimizer. Use polyfill + COALESCE(value, 0) if you need full coverage.

提供商大小写与SQL方言：本技能使用小写列名（
```
h3
```
、
```
geom_count
```
、
```
population
```
、
```
sentiment_avg
```
等）——符合BigQuery / Databricks / Postgres / Redshift的惯例。在Snowflake中，未加引号的标识符会显示为大写——需引用为
```
H3
```
、
```
GEOM_COUNT
```
、
```
POPULATION
```
、
```
SENTIMENT_AVG
```
。请查看
```
carto-create-workflow/references/providers/<provider>.md
```
获取大小写规则和SQL方言等效写法。
需安装扩展包：区域平衡和位置分配都要求所用的特定连接上已安装区域规划扩展包。这并非默认提供——用户必须自行安装。如果缺少该包，验证将失败。
位置分配计算成本高：当候选数量较多时，计算成本很高。预先筛选候选位置（按地理范围、容量或其他标准）以缩小候选集。数百个候选可能会很慢；数千个可能会超时。
覆盖半径单位：取决于空间参考系统——使用地理类型时通常为米。请确认单位符合你的需求。
区域平衡优化权衡：在空间连续性与均衡性之间进行权衡优化。无法保证完美均衡——片区在需求变量上会大致相等，而非完全相等。
网格分辨率敏感性：输入网格分辨率会显著影响结果。更精细的网格能提供更精确的边界，但会增加计算量。城市规模分析从H3分辨率8开始，然后按需调整。

组件名称：

native.territorybalancing

（"territory balancing"无点分隔符）以及

native.locallocallocation_maximizecoverage

native.locallocallocation_minimizetotalcost

（注意双"local"前缀）。

需求数据需覆盖研究区域：需求网格中的空白意味着这些区域对优化器不可见。如果需要全覆盖，请使用polyfill + COALESCE(value, 0)。

Reference Templates

参考模板

Academy Tutorials

学院教程

Territory Balancing tutorial -- step-by-step walkthrough of the Milan POS use case
Location Allocation tutorial -- telco network management with location allocation
AI Agent + Location Allocation -- using AI agents with location allocation for emergency response hub placement

区域平衡教程 —— 米兰POS用例的分步演练
位置分配教程 —— 位置分配在电信网络管理中的应用
AI Agent + 位置分配 —— 使用AI Agent和位置分配优化应急响应枢纽选址

Common Variations

常见变体

Variant	How
Sales territory balancing	Points -> H3 -> aggregate revenue per cell -> territory balancing with revenue as demand
Service zone design	Grid with population -> territory balancing to create equal-population zones
Warehouse/depot placement	Population grid as demand + existing warehouses as candidates -> minimize total cost
Emergency response hubs	Population grid as demand + candidate sites -> maximize coverage with a response-time radius
Retail network expansion	Customer density grid as demand + potential store locations -> maximize coverage
Combined territory + allocation	First run location allocation to pick hub locations, then run territory balancing to assign areas to each hub

变体	实现方式
销售区域平衡	点数据 -> H3 -> 按单元聚合收入 -> 以收入为需求运行区域平衡
服务区域设计	带人口数据的网格 -> 运行区域平衡创建人口均衡的区域
仓库/配送中心选址	人口网格作为需求 + 现有仓库作为候选 -> 最小化总成本
应急响应枢纽	人口网格作为需求 + 候选站点 -> 按响应时间半径最大化覆盖范围
零售网络扩张	客户密度网格作为需求 + 潜在门店位置 -> 最大化覆盖范围
区域平衡+位置分配结合	先运行位置分配选择枢纽位置，再运行区域平衡将区域分配给每个枢纽