pgRouting API完全参考：函数参数与返回值详解

【免费下载链接】pgrouting Repository contains pgRouting library. Development branch is "develop", stable branch is "master" 项目地址: https://gitcode.com/gh_mirrors/pg/pgrouting

pgRouting是一个基于PostgreSQL和PostGIS的开源空间路由扩展库，提供了丰富的路径分析功能。本文将详细解析pgRouting核心API的函数参数与返回值，帮助开发者快速掌握各类路由函数的使用方法。

核心函数分类与命名规范

pgRouting函数采用统一的命名规范，通常以pgr_为前缀，后接算法名称或功能描述。主要函数类别包括：

• 最短路径算法：如pgr_dijkstra、pgr_astar等
• 路径成本分析：如pgr_dijkstraCost、pgr_astarCost等
• 网络分析工具：如pgr_connectedComponents、pgr_articulationPoints等
• 高级路由功能：如pgr_TSP（旅行商问题）、pgr_chinesePostman（中国邮递员问题）等

所有函数定义文件位于项目的sql/目录下，按功能模块分类存放，例如最短路径相关函数在sql/dijkstra/目录中。

基础路径算法参数解析

Dijkstra算法

Dijkstra算法是pgRouting中最常用的最短路径算法，其核心函数pgr_dijkstra定义如下：

CREATE OR REPLACE FUNCTION pgr_dijkstra(
    TEXT,  --  edges_sql
    BIGINT, --  start_vid
    BIGINT, --  end_vid
    BOOLEAN --  directed := true
)
RETURNS TABLE(seq INTEGER, path_seq INTEGER, node BIGINT, edge BIGINT, cost FLOAT, agg_cost FLOAT)

关键参数说明：

• edges_sql：查询边表的SQL语句，必须返回id、source、target、cost字段
• start_vid/end_vid：起点/终点节点ID
• directed：是否为有向图（默认true）

返回值说明：

• seq：结果序号
• path_seq：路径中的序号
• node：节点ID
• edge：边ID（-1表示虚拟边）
• cost：边的成本
• agg_cost：累计成本

A*算法

A*算法在Dijkstra基础上增加了启发式函数，适用于已知终点坐标的场景：

CREATE OR REPLACE FUNCTION pgr_astar(
    TEXT,  -- edges_sql
    BIGINT, -- start_vid
    BIGINT, -- end_vid
    BOOLEAN, -- directed := true
    BOOLEAN  -- heuristic := true
)
RETURNS TABLE(seq INTEGER, path_seq INTEGER, node BIGINT, edge BIGINT, cost FLOAT, agg_cost FLOAT)

额外参数：

• heuristic：是否启用启发式函数（默认true）

使用A*算法时，边表SQL需要额外提供x1,y1,x2,y2字段表示节点坐标，用于计算启发式距离。

高级路由功能详解

成本矩阵计算

pgr_dijkstraCostMatrix函数可一次性计算多个起点到多个终点的成本矩阵：

CREATE OR REPLACE FUNCTION pgr_dijkstraCostMatrix(
    TEXT, -- edges_sql
    ANYARRAY, -- start_vids
    ANYARRAY, -- end_vids := start_vids
    BOOLEAN, -- directed := true
    BOOLEAN  -- only_cost := true
)
RETURNS TABLE(start_vid BIGINT, end_vid BIGINT, agg_cost FLOAT)

应用场景：物流配送路径规划、多源点可达性分析

旅行商问题(TSP)

pgr_TSP函数解决旅行商问题，寻找访问所有节点的最短闭合路径：

CREATE OR REPLACE FUNCTION pgr_TSP(
    TEXT, -- cost_matrix_sql
    INTEGER, -- start_id := 0
    BOOLEAN, -- randomize := true
    INTEGER  -- tries := 10
)
RETURNS TABLE(seq INTEGER, node BIGINT, cost FLOAT, agg_cost FLOAT)

TSP问题最优路径示例

使用示例：

SELECT * FROM pgr_TSP(
    'SELECT * FROM cost_matrix',
    start_id := 1,
    tries := 20
);

网络分析工具参数说明

连通分量分析

pgr_connectedComponents函数用于识别图中的连通分量：

CREATE OR REPLACE FUNCTION pgr_connectedComponents(
    TEXT, -- edges_sql
    BOOLEAN  -- directed := false
)
RETURNS TABLE(component_id INTEGER, node BIGINT)

连通分量示例

返回结果：每个节点及其所属的连通分量ID，可用于网络分割或孤立区域检测。

收缩层次算法

pgr_contractionHierarchies函数通过预处理加速路径查询：

CREATE OR REPLACE FUNCTION pgr_contractionHierarchies(
    TEXT, -- edges_sql
    INTEGER, -- contraction_order := 3
    BOOLEAN  -- directed := true
)
RETURNS TABLE(id BIGINT, source BIGINT, target BIGINT, cost FLOAT, reverse_cost FLOAT)

收缩层次算法示例

函数调用最佳实践

1. 边表准备：确保边表包含必要字段，有向图需提供reverse_cost
2. 索引优化：为source和target字段创建索引提升性能
3. 参数验证：使用pgr_analyzeGraph检查图结构完整性
4. 内存控制：处理大型网络时，考虑使用pgr_dijkstraNear等限制返回结果数量的函数

常见问题与解决方案

• 参数错误：确保SQL查询返回正确的字段名和数据类型
• 性能问题：对大规模网络，优先考虑收缩层次算法或使用pgr_withPoints减少节点数量
• 结果异常：使用pgr_checkEdges验证边表拓扑结构

完整的函数文档可参考项目中的doc/目录，每个算法都有详细的参数说明和使用示例。通过合理组合这些API，可实现从简单路径查询到复杂物流优化的各类空间分析功能。

【免费下载链接】pgrouting Repository contains pgRouting library. Development branch is "develop", stable branch is "master" 项目地址: https://gitcode.com/gh_mirrors/pg/pgrouting