# pgr_withPointsDD - Proposed¶

pgr_withPointsDD - Returns the driving distance from a starting point.

Warning

Proposed functions for next mayor release.

• They are not officially in the current release.

• They will likely officially be part of the next mayor release:

• The functions make use of ANY-INTEGER and ANY-NUMERICAL

• Name might not change. (But still can)

• Signature might not change. (But still can)

• Functionality might not change. (But still can)

• pgTap tests have being done. But might need more.

• Documentation might need refinement.

Availability

• Version 2.2.0

• New proposed function

## Description¶

Modify the graph to include points and using Dijkstra algorithm, extracts all the nodes and points that have costs less than or equal to the value **distance** from the starting point. The edges extracted will conform the corresponding spanning tree.

## Signatures¶

pgr_withPointsDD(Edges SQL, Points SQL, Root vid, distance
[, directed] [, driving_side] [, details])
pgr_withPointsDD(Edges SQL, Points SQL, Root vids, distance
[, directed] [, driving_side] [, details] [, equicost])
RETURNS SET OF (seq, [start_vid,] node, edge, cost, agg_cost)

### Single vertex¶

pgr_withPointsDD(Edges SQL, Points SQL, Root vid, distance
[, directed] [, driving_side] [, details])
RETURNS SET OF (seq, node, edge, cost, agg_cost)
Example:

Right side driving topology, from point $$1$$ within a distance of $$3.3$$ with details.

SELECT * FROM pgr_withPointsDD(
'SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id',
'SELECT pid, edge_id, fraction, side from pointsOfInterest',
-1, 3.3,
driving_side => 'r',
details => true);
seq | node | edge | cost | agg_cost
-----+------+------+------+----------
1 |   -1 |   -1 |    0 |        0
2 |    5 |    1 |  0.4 |      0.4
3 |    6 |    1 |    1 |      1.4
4 |   -6 |    4 |  0.7 |      2.1
5 |    7 |    4 |  0.3 |      2.4
(5 rows)



### Multiple vertices¶

pgr_withPointsDD(Edges SQL, Points SQL, Root vids, distance
[, directed] [, driving_side] [, details] [, equicost])
RETURNS SET OF (seq, start_vid, node, edge, cost, agg_cost)
Example:

From point $$1$$ and vertex $$16$$ within a distance of $$3.3$$ with equicost on a directed graph

SELECT * FROM pgr_withPointsDD(
'SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id',
'SELECT pid, edge_id, fraction, side from pointsOfInterest',
ARRAY[-1, 16], 3.3,
driving_side => 'l',
equicost => true);
seq | start_vid | node | edge | cost | agg_cost
-----+-----------+------+------+------+----------
1 |        -1 |   -1 |   -1 |    0 |        0
2 |        -1 |    6 |    1 |  0.6 |      0.6
3 |        -1 |    7 |    4 |    1 |      1.6
4 |        -1 |    5 |    1 |    1 |      1.6
5 |        -1 |    3 |    7 |    1 |      2.6
6 |        -1 |    8 |   10 |    1 |      2.6
7 |        16 |   16 |   -1 |    0 |        0
8 |        16 |   11 |    9 |    1 |        1
9 |        16 |   15 |   16 |    1 |        1
10 |        16 |   17 |   15 |    1 |        1
11 |        16 |   10 |    3 |    1 |        2
12 |        16 |   12 |   11 |    1 |        2
(12 rows)



## Parameters¶

Column

Type

Description

Edges SQL

TEXT

Edges SQL as described below

Points SQL

TEXT

Points SQL as described below

Root vid

BIGINT

Identifier of the root vertex of the tree.

• Negative values represent a point

Root vids

ARRAY[ANY-INTEGER]

Array of identifiers of the root vertices.

• Negative values represent a point

• $$0$$ values are ignored

• For optimization purposes, any duplicated value is ignored.

distance

FLOAT

Upper limit for the inclusion of a node in the result.

### Optional parameters¶

Column

Type

Default

Description

directed

BOOLEAN

true

• When true the graph is considered Directed

• When false the graph is considered as Undirected.

### With points optional parameters¶

Parameter

Type

Default

Description

driving_side

CHAR

b

Value in [r, l, b] indicating if the driving side is:

• r for right driving side.

• l for left driving side.

• b for both.

details

BOOLEAN

false

• When true the results will include the points that are in the path.

• When false the results will not include the points that are in the path.

### Driving distance optional parameters¶

Column

Type

Default

Description

equicost

BOOLEAN

true

• When true the node will only appear in the closest from_v list.

• When false which resembles several calls using the single starting point signatures. Tie brakes are arbitrary.

## Inner Queries¶

### Edges SQL¶

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)

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

ANY-NUMERICAL:

SMALLINT, INTEGER, BIGINT, REAL, FLOAT

### Points SQL¶

Parameter

Type

Default

Description

pid

ANY-INTEGER

value

Identifier of the point.

• Use with positive value, as internally will be converted to negative value

• If column is present, it can not be NULL.

• If column is not present, a sequential negative value will be given automatically.

edge_id

ANY-INTEGER

Identifier of the “closest” edge to the point.

fraction

ANY-NUMERICAL

Value in <0,1> that indicates the relative postition from the first end point of the edge.

side

CHAR

b

Value in [b, r, l, NULL] indicating if the point is:

• In the right r,

• In the left l,

• In both sides b, NULL

Where:

ANY-INTEGER:

SMALLINT, INTEGER, BIGINT

ANY-NUMERICAL:

SMALLINT, INTEGER, BIGINT, REAL, FLOAT

## Result Columns¶

Returns SET OF (seq, [start_vid,] node, edge, cost, agg_cost)

Parameter

Type

Description

seq

BIGINT

Sequential value starting from $$1$$.

[start_vid]

BIGINT

Identifier of the root vertex.

node

BIGINT

Identifier of node within the limits from from_v.

edge

BIGINT

Identifier of the edge used to arrive to node.

• $$0$$ when node = from_v.

cost

FLOAT

Cost to traverse edge.

agg_cost

FLOAT

Aggregate cost from from_v to node.

Where:

ANY-INTEGER:

SMALLINT, INTEGER, BIGINT

ANY-NUMERIC:

SMALLINT, INTEGER, BIGINT, REAL, FLOAT, NUMERIC

### Driving side does not matter¶

From point $$1$$ within a distance of $$3.3$$, does not matter driving side, with details.

SELECT * FROM pgr_withPointsDD(
'SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id',
'SELECT pid, edge_id, fraction, side from pointsOfInterest',
-1, 3.3,
driving_side => 'b',
details => true);
seq | node | edge | cost | agg_cost
-----+------+------+------+----------
1 |   -1 |   -1 |    0 |        0
2 |    5 |    1 |  0.4 |      0.4
3 |    6 |    1 |  0.6 |      0.6
4 |   -6 |    4 |  0.7 |      1.3
5 |    7 |    4 |  0.3 |      1.6
6 |    3 |    7 |    1 |      2.6
7 |    8 |   10 |    1 |      2.6
8 |   11 |    8 |    1 |      2.6
9 |   -3 |   12 |  0.6 |      3.2
10 |   -4 |    6 |  0.7 |      3.3
(10 rows)