# pgr_drivingDistance¶

pgr_drivingDistance - Returns the driving distance from a start node.

Availability

• New on v2.1.0:
• pgr_drivingDistance(multiple vertices)
• Signature change on v2.1.0:
• pgr_drivingDistance(single vertex)
• New on v2.0.0:
• pgr_drivingDistance(single vertex)

## Description¶

Using the Dijkstra algorithm, extracts all the nodes that have costs less than or equal to the value distance. The edges extracted will conform to the corresponding spanning tree.

## Signatures¶

Summary

pgr_drivingDistance(edges_sql, start_vid,  distance [, directed])
pgr_drivingDistance(edges_sql, start_vids, distance [, directed] [, equicost])
RETURNS SET OF (seq, [start_vid,] node, edge, cost, agg_cost)


Using defaults

pgr_drivingDistance(edges_sql, start_vid, distance)
RETURNS SET OF (seq, node, edge, cost, agg_cost)

Example: TBD

### Single Vertex¶

pgr_drivingDistance(edges_sql, start_vid, distance [, directed])
RETURNS SET OF (seq, node, edge, cost, agg_cost)

Example: TBD

### Multiple Vertices¶

pgr_drivingDistance(edges_sql, start_vids, distance, [, directed] [, equicost])
RETURNS SET OF (seq, start_vid, node, edge, cost, agg_cost)

Example: TBD

## Parameters¶

Column Type Description
edges_sql TEXT SQL query as described above.
start_vid BIGINT Identifier of the starting vertex.
start_vids ARRAY[ANY-INTEGER] Array of identifiers of the starting vertices.
distance FLOAT Upper limit for the inclusion of the node in the result.
directed BOOLEAN (optional). When false the graph is considered as Undirected. Default is true which considers the graph as Directed.
equicost BOOLEAN (optional). When true the node will only appear in the closest start_vid list. Default is false which resembles several calls using the single starting point signatures. Tie brakes are arbitrary.

## Inner query¶

Edges SQL: an SQL query, which should return a set of rows with the following columns:
Column Type Default Description
id ANY-INTEGER   Identifier of the edge.
source ANY-INTEGER   Identifier of the first end point vertex of the edge.
target ANY-INTEGER   Identifier of the second end point vertex of the edge.
cost ANY-NUMERICAL

Weight of the edge (source, target)

• When negative: edge (source, target) does not exist, therefore it’s not part of the graph.
reverse_cost ANY-NUMERICAL -1

Weight of the edge (target, source),

• When negative: edge (target, source) does not exist, therefore it’s not part of the graph.

Where:

ANY-INTEGER: SMALLINT, INTEGER, BIGINT SMALLINT, INTEGER, BIGINT, REAL, FLOAT

## Result Columns¶

Returns set of (seq [, start_v], node, edge, cost, agg_cost)

Column Type Description
seq INTEGER Sequential value starting from 1.
start_vid INTEGER Identifier of the starting vertex.
node BIGINT Identifier of the node in the path within the limits from start_vid.
edge BIGINT Identifier of the edge used to arrive to node. 0 when the node is the start_vid.
cost FLOAT Cost to traverse edge.
agg_cost FLOAT Aggregate cost from start_vid to node.

Example: For queries marked as directed with cost and reverse_cost columns

The examples in this section use the following Network for queries marked as directed and cost and reverse_cost columns are used

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost, reverse_cost FROM edge_table',
2, 3
);
seq | node | edge | cost | agg_cost
-----+------+------+------+----------
1 |    2 |   -1 |    0 |        0
2 |    1 |    1 |    1 |        1
3 |    5 |    4 |    1 |        1
4 |    6 |    8 |    1 |        2
5 |    8 |    7 |    1 |        2
6 |   10 |   10 |    1 |        2
7 |    7 |    6 |    1 |        3
8 |    9 |    9 |    1 |        3
9 |   11 |   12 |    1 |        3
10 |   13 |   14 |    1 |        3
(10 rows)

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost, reverse_cost FROM edge_table',
13, 3
);
seq | node | edge | cost | agg_cost
-----+------+------+------+----------
1 |   13 |   -1 |    0 |        0
2 |   10 |   14 |    1 |        1
3 |    5 |   10 |    1 |        2
4 |   11 |   12 |    1 |        2
5 |    2 |    4 |    1 |        3
6 |    6 |    8 |    1 |        3
7 |    8 |    7 |    1 |        3
8 |   12 |   13 |    1 |        3
(8 rows)

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost, reverse_cost FROM edge_table',
array[2,13], 3
);
seq | from_v | node | edge | cost | agg_cost
-----+--------+------+------+------+----------
1 |      2 |    2 |   -1 |    0 |        0
2 |      2 |    1 |    1 |    1 |        1
3 |      2 |    5 |    4 |    1 |        1
4 |      2 |    6 |    8 |    1 |        2
5 |      2 |    8 |    7 |    1 |        2
6 |      2 |   10 |   10 |    1 |        2
7 |      2 |    7 |    6 |    1 |        3
8 |      2 |    9 |    9 |    1 |        3
9 |      2 |   11 |   12 |    1 |        3
10 |      2 |   13 |   14 |    1 |        3
11 |     13 |   13 |   -1 |    0 |        0
12 |     13 |   10 |   14 |    1 |        1
13 |     13 |    5 |   10 |    1 |        2
14 |     13 |   11 |   12 |    1 |        2
15 |     13 |    2 |    4 |    1 |        3
16 |     13 |    6 |    8 |    1 |        3
17 |     13 |    8 |    7 |    1 |        3
18 |     13 |   12 |   13 |    1 |        3
(18 rows)

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost, reverse_cost FROM edge_table',
array[2,13], 3, equicost:=true
);
seq | from_v | node | edge | cost | agg_cost
-----+--------+------+------+------+----------
1 |      2 |    2 |   -1 |    0 |        0
2 |      2 |    1 |    1 |    1 |        1
3 |      2 |    5 |    4 |    1 |        1
4 |      2 |    6 |    8 |    1 |        2
5 |      2 |    8 |    7 |    1 |        2
6 |      2 |    7 |    6 |    1 |        3
7 |      2 |    9 |    9 |    1 |        3
8 |     13 |   13 |   -1 |    0 |        0
9 |     13 |   10 |   14 |    1 |        1
10 |     13 |   11 |   12 |    1 |        2
11 |     13 |   12 |   13 |    1 |        3
(11 rows)


Example: For queries marked as undirected with cost and reverse_cost columns

The examples in this section use the following Network for queries marked as undirected and cost and reverse_cost columns are used

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost, reverse_cost FROM edge_table',
2, 3, false
);
seq | node | edge | cost | agg_cost
-----+------+------+------+----------
1 |    2 |   -1 |    0 |        0
2 |    1 |    1 |    1 |        1
3 |    3 |    2 |    1 |        1
4 |    5 |    4 |    1 |        1
5 |    4 |    3 |    1 |        2
6 |    6 |    8 |    1 |        2
7 |    8 |    7 |    1 |        2
8 |   10 |   10 |    1 |        2
9 |    7 |    6 |    1 |        3
10 |    9 |   16 |    1 |        3
11 |   11 |   12 |    1 |        3
12 |   13 |   14 |    1 |        3
(12 rows)

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost, reverse_cost FROM edge_table',
13, 3, false
);
seq | node | edge | cost | agg_cost
-----+------+------+------+----------
1 |   13 |   -1 |    0 |        0
2 |   10 |   14 |    1 |        1
3 |    5 |   10 |    1 |        2
4 |   11 |   12 |    1 |        2
5 |    2 |    4 |    1 |        3
6 |    6 |    8 |    1 |        3
7 |    8 |    7 |    1 |        3
8 |   12 |   13 |    1 |        3
(8 rows)

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost, reverse_cost FROM edge_table',
array[2,13], 3, false
);
seq | from_v | node | edge | cost | agg_cost
-----+--------+------+------+------+----------
1 |      2 |    2 |   -1 |    0 |        0
2 |      2 |    1 |    1 |    1 |        1
3 |      2 |    3 |    2 |    1 |        1
4 |      2 |    5 |    4 |    1 |        1
5 |      2 |    4 |    3 |    1 |        2
6 |      2 |    6 |    8 |    1 |        2
7 |      2 |    8 |    7 |    1 |        2
8 |      2 |   10 |   10 |    1 |        2
9 |      2 |    7 |    6 |    1 |        3
10 |      2 |    9 |   16 |    1 |        3
11 |      2 |   11 |   12 |    1 |        3
12 |      2 |   13 |   14 |    1 |        3
13 |     13 |   13 |   -1 |    0 |        0
14 |     13 |   10 |   14 |    1 |        1
15 |     13 |    5 |   10 |    1 |        2
16 |     13 |   11 |   12 |    1 |        2
17 |     13 |    2 |    4 |    1 |        3
18 |     13 |    6 |    8 |    1 |        3
19 |     13 |    8 |    7 |    1 |        3
20 |     13 |   12 |   13 |    1 |        3
(20 rows)

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost, reverse_cost FROM edge_table',
array[2,13], 3, false, equicost:=true
);
seq | from_v | node | edge | cost | agg_cost
-----+--------+------+------+------+----------
1 |      2 |    2 |   -1 |    0 |        0
2 |      2 |    1 |    1 |    1 |        1
3 |      2 |    3 |    2 |    1 |        1
4 |      2 |    5 |    4 |    1 |        1
5 |      2 |    4 |    3 |    1 |        2
6 |      2 |    6 |    8 |    1 |        2
7 |      2 |    8 |    7 |    1 |        2
8 |      2 |    7 |    6 |    1 |        3
9 |      2 |    9 |   16 |    1 |        3
10 |     13 |   13 |   -1 |    0 |        0
11 |     13 |   10 |   14 |    1 |        1
12 |     13 |   11 |   12 |    1 |        2
13 |     13 |   12 |   13 |    1 |        3
(13 rows)


Example: For queries marked as directed with cost column

The examples in this section use the following Network for queries marked as directed and only cost column is used

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost FROM edge_table',
2, 3
);
seq | node | edge | cost | agg_cost
-----+------+------+------+----------
1 |    2 |   -1 |    0 |        0
2 |    5 |    4 |    1 |        1
3 |    6 |    8 |    1 |        2
4 |   10 |   10 |    1 |        2
5 |    9 |    9 |    1 |        3
6 |   11 |   11 |    1 |        3
7 |   13 |   14 |    1 |        3
(7 rows)

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost FROM edge_table',
13, 3
);
seq | node | edge | cost | agg_cost
-----+------+------+------+----------
1 |   13 |   -1 |    0 |        0
(1 row)

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost FROM edge_table',
array[2,13], 3
);
seq | from_v | node | edge | cost | agg_cost
-----+--------+------+------+------+----------
1 |      2 |    2 |   -1 |    0 |        0
2 |      2 |    5 |    4 |    1 |        1
3 |      2 |    6 |    8 |    1 |        2
4 |      2 |   10 |   10 |    1 |        2
5 |      2 |    9 |    9 |    1 |        3
6 |      2 |   11 |   11 |    1 |        3
7 |      2 |   13 |   14 |    1 |        3
8 |     13 |   13 |   -1 |    0 |        0
(8 rows)

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost FROM edge_table',
array[2,13], 3, equicost:=true
);
seq | from_v | node | edge | cost | agg_cost
-----+--------+------+------+------+----------
1 |      2 |    2 |   -1 |    0 |        0
2 |      2 |    5 |    4 |    1 |        1
3 |      2 |    6 |    8 |    1 |        2
4 |      2 |   10 |   10 |    1 |        2
5 |      2 |    9 |    9 |    1 |        3
6 |      2 |   11 |   11 |    1 |        3
7 |     13 |   13 |   -1 |    0 |        0
(7 rows)


Example: For queries marked as undirected with cost column

The examples in this section use the following Network for queries marked as undirected and only cost column is used

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost FROM edge_table',
2, 3, false
);
seq | node | edge | cost | agg_cost
-----+------+------+------+----------
1 |    2 |   -1 |    0 |        0
2 |    1 |    1 |    1 |        1
3 |    5 |    4 |    1 |        1
4 |    6 |    8 |    1 |        2
5 |    8 |    7 |    1 |        2
6 |   10 |   10 |    1 |        2
7 |    3 |    5 |    1 |        3
8 |    7 |    6 |    1 |        3
9 |    9 |    9 |    1 |        3
10 |   11 |   12 |    1 |        3
11 |   13 |   14 |    1 |        3
(11 rows)

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost FROM edge_table',
13, 3, false
);
seq | node | edge | cost | agg_cost
-----+------+------+------+----------
1 |   13 |   -1 |    0 |        0
2 |   10 |   14 |    1 |        1
3 |    5 |   10 |    1 |        2
4 |   11 |   12 |    1 |        2
5 |    2 |    4 |    1 |        3
6 |    6 |    8 |    1 |        3
7 |    8 |    7 |    1 |        3
8 |   12 |   13 |    1 |        3
(8 rows)

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost FROM edge_table',
array[2,13], 3, false
);
seq | from_v | node | edge | cost | agg_cost
-----+--------+------+------+------+----------
1 |      2 |    2 |   -1 |    0 |        0
2 |      2 |    1 |    1 |    1 |        1
3 |      2 |    5 |    4 |    1 |        1
4 |      2 |    6 |    8 |    1 |        2
5 |      2 |    8 |    7 |    1 |        2
6 |      2 |   10 |   10 |    1 |        2
7 |      2 |    3 |    5 |    1 |        3
8 |      2 |    7 |    6 |    1 |        3
9 |      2 |    9 |    9 |    1 |        3
10 |      2 |   11 |   12 |    1 |        3
11 |      2 |   13 |   14 |    1 |        3
12 |     13 |   13 |   -1 |    0 |        0
13 |     13 |   10 |   14 |    1 |        1
14 |     13 |    5 |   10 |    1 |        2
15 |     13 |   11 |   12 |    1 |        2
16 |     13 |    2 |    4 |    1 |        3
17 |     13 |    6 |    8 |    1 |        3
18 |     13 |    8 |    7 |    1 |        3
19 |     13 |   12 |   13 |    1 |        3
(19 rows)

SELECT * FROM pgr_drivingDistance(
'SELECT id, source, target, cost FROM edge_table',
array[2,13], 3, false, equicost:=true
);
seq | from_v | node | edge | cost | agg_cost
-----+--------+------+------+------+----------
1 |      2 |    2 |   -1 |    0 |        0
2 |      2 |    1 |    1 |    1 |        1
3 |      2 |    5 |    4 |    1 |        1
4 |      2 |    6 |    8 |    1 |        2
5 |      2 |    8 |    7 |    1 |        2
6 |      2 |    3 |    5 |    1 |        3
7 |      2 |    7 |    6 |    1 |        3
8 |      2 |    9 |    9 |    1 |        3
9 |     13 |   13 |   -1 |    0 |        0
10 |     13 |   10 |   14 |    1 |        1
11 |     13 |   11 |   12 |    1 |        2
12 |     13 |   12 |   13 |    1 |        3
(12 rows)