# pgRouting Manual (3.6)

## pgr_withPointsDD - Proposed

# `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.

Boost Graph Inside

Availability

Version 3.6.0

- Signature change: `driving_side` parameter changed from named optional to unnamed compulsory driving side.

  - `pgr_withPointsDD` (Single vertex)

  - `pgr_withPointsDD` (Multiple vertices)

- Standarizing output columns to `(seq, depth, start_vid, pred, node, edge, cost, agg_cost)`

  - `pgr_withPointsDD` (Single vertex)

    - Added `depth`, `pred` and `start_vid` column.

  - `pgr_withPointsDD` (Multiple vertices)

    - Added `depth`, `pred` columns.

- When `details` is `false`:

  - Only points that are visited are removed, that is, points reached within the distance are included

- Deprecated signatures

  - `pgr_withpointsdd(text,text,bigint,double precision,boolean,character,boolean)`

  - `pgr_withpointsdd(text,text,anyarray,double precision,boolean,character,boolean,boolean)`

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, driving side, [options A])
pgr_withPointsDD(Edges SQL, Points SQL, root vids, distance, driving side, [options B])
options A: `[directed, details]`
options B: `[directed, details, equicost]`
Returns set of `(seq, depth, start_vid, pred, node, edge, cost, agg_cost)`
OR EMPTY SET

### Single vertex

pgr_withPointsDD(Edges SQL, Points SQL, root vid, distance, driving side, [options])
options: `[directed, details]`
Returns set of `(seq, depth, start_vid, pred, node, edge, cost, agg_cost)`
OR EMPTY SET

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, 'r',
      details => true);
     seq | depth | start_vid | pred | node | edge | cost | agg_cost
    -----+-------+-----------+------+------+------+------+----------
       1 |     0 |        -1 |   -1 |   -1 |   -1 |    0 |        0
       2 |     1 |        -1 |   -1 |    5 |    1 |  0.4 |      0.4
       3 |     2 |        -1 |    5 |    6 |    1 |    1 |      1.4
       4 |     3 |        -1 |    6 |   -6 |    4 |  0.7 |      2.1
       5 |     4 |        -1 |   -6 |    7 |    4 |  0.3 |      2.4
    (5 rows)

### Multiple vertices

pgr_withPointsDD(Edges SQL, Points SQL, root vids, distance, driving side, [options])
options: `[directed, details, equicost]`
Returns set of `(seq, depth, start_vid, pred, node, edge, cost, agg_cost)`
OR EMPTY SET

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, 'l',
      equicost => true);
     seq | depth | start_vid | pred | node | edge | cost | agg_cost
    -----+-------+-----------+------+------+------+------+----------
       1 |     0 |        -1 |   -1 |   -1 |   -1 |    0 |        0
       2 |     1 |        -1 |   -1 |    6 |    1 |  0.6 |      0.6
       3 |     2 |        -1 |    6 |    7 |    4 |    1 |      1.6
       4 |     2 |        -1 |    6 |    5 |    1 |    1 |      1.6
       5 |     3 |        -1 |    7 |    3 |    7 |    1 |      2.6
       6 |     3 |        -1 |    7 |    8 |   10 |    1 |      2.6
       7 |     4 |        -1 |    8 |   -3 |   12 |  0.6 |      3.2
       8 |     4 |        -1 |    3 |   -4 |    6 |  0.7 |      3.3
       9 |     0 |        16 |   16 |   16 |   -1 |    0 |        0
      10 |     1 |        16 |   16 |   11 |    9 |    1 |        1
      11 |     1 |        16 |   16 |   15 |   16 |    1 |        1
      12 |     1 |        16 |   16 |   17 |   15 |    1 |        1
      13 |     2 |        16 |   15 |   10 |    3 |    1 |        2
      14 |     2 |        16 |   11 |   12 |   11 |    1 |        2
    (14 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.

driving side

`CHAR`

- Value in [`r`, `R`, `l`, `L`, `b`, `B`] indicating if the driving side is:

  - `r`, `R` for right driving side,

  - `l`, `L` for left driving side.

  - `b`, `B` for both.

- Valid values differ for directed and undirected graphs:

  - In directed graphs: [`r`, `R`, `l`, `L`].

  - In undirected graphs: [`b`, `B`].

Where:

ANY-INTEGER:

  SMALLINT, INTEGER, BIGINT

### 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
--- | --- | --- | ---

`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 `start_vid` list. Tie brakes are arbitrary.

- When `false` which resembles several calls using the single vertex signature.

## 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, depth, start_vid, pred, node, edge, cost, agg_cost)`

Parameter | Type | Description
--- | --- | ---
`seq` | `BIGINT` | Sequential value starting from \(1\).

`depth`

`BIGINT`

Depth of the `node`.

- \(0\) when `node` = `start_vid`.

- \(depth-1\) is the depth of `pred`

`start_vid` | `BIGINT` | Identifier of the root vertex.

`pred`

`BIGINT`

Predecessor of `node`.

- When `node` = `start_vid` then has the value `node`.

`node` | `BIGINT` | Identifier of `node` reached using `edge`.

`edge`

`BIGINT`

Identifier of the `edge` used to arrive from `pred` to `node`.

- \(-1\) when `node` = `start_vid`.

`cost` | `FLOAT` | Cost to traverse `edge`.
`agg_cost` | `FLOAT` | Aggregate cost from `start_vid` to `node`.

Where:

ANY-INTEGER:

  SMALLINT, INTEGER, BIGINT

ANY-NUMERIC:

  SMALLINT, INTEGER, BIGINT, REAL, FLOAT, NUMERIC

## Additional Examples

### Use pgr_findCloseEdges in the Points SQL.

Find the driving distance from the two closest locations on the graph of point (2.9, 1.8).

    SELECT * FROM pgr_withPointsDD(
      $e$ SELECT * FROM edges $e$,
      $p$ SELECT edge_id, round(fraction::numeric, 2) AS fraction, side
          FROM pgr_findCloseEdges(
            $$SELECT id, geom FROM edges$$,
            (SELECT ST_POINT(2.9, 1.8)),
            0.5, cap => 2)
      $p$,
      ARRAY[-1, -2], 2.3, 'r',
      details => true);
     seq | depth | start_vid | pred | node | edge | cost | agg_cost
    -----+-------+-----------+------+------+------+------+----------
       1 |     0 |        -2 |   -2 |   -2 |   -1 |    0 |        0
       2 |     1 |        -2 |   -2 |   11 |    8 |  0.1 |      0.1
       3 |     2 |        -2 |   11 |   16 |    9 |    1 |      1.1
       4 |     2 |        -2 |   11 |    7 |    8 |    1 |      1.1
       5 |     2 |        -2 |   11 |   12 |   11 |    1 |      1.1
       6 |     3 |        -2 |   12 |   17 |   13 |    1 |      2.1
       7 |     3 |        -2 |   16 |   15 |   16 |    1 |      2.1
       8 |     3 |        -2 |    7 |    8 |   10 |    1 |      2.1
       9 |     3 |        -2 |    7 |    6 |    4 |    1 |      2.1
      10 |     3 |        -2 |    7 |    3 |    7 |    1 |      2.1
      11 |     0 |        -1 |   -1 |   -1 |   -1 |    0 |        0
      12 |     1 |        -1 |   -1 |   11 |    5 |  0.2 |      0.2
      13 |     2 |        -1 |   11 |    7 |    8 |    1 |      1.2
      14 |     2 |        -1 |   11 |   12 |   11 |    1 |      1.2
      15 |     2 |        -1 |   11 |   16 |    9 |    1 |      1.2
      16 |     3 |        -1 |    7 |   -2 |    8 |  0.9 |      2.1
      17 |     3 |        -1 |   12 |   17 |   13 |    1 |      2.2
      18 |     3 |        -1 |   16 |   15 |   16 |    1 |      2.2
      19 |     3 |        -1 |    7 |    8 |   10 |    1 |      2.2
      20 |     3 |        -1 |    7 |    6 |    4 |    1 |      2.2
      21 |     3 |        -1 |    7 |    3 |    7 |    1 |      2.2
    (21 rows)

- Point \(-1\) corresponds to the closest edge from point \((2.9, 1.8)\).

- Point \(-2\) corresponds to the next close edge from point \((2.9, 1.8)\).

### 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, 'b',
      directed => false,
      details => true);
     seq | depth | start_vid | pred | node | edge | cost | agg_cost
    -----+-------+-----------+------+------+------+------+----------
       1 |     0 |        -1 |   -1 |   -1 |   -1 |    0 |        0
       2 |     1 |        -1 |   -1 |    5 |    1 |  0.4 |      0.4
       3 |     1 |        -1 |   -1 |    6 |    1 |  0.6 |      0.6
       4 |     2 |        -1 |    6 |   -6 |    4 |  0.7 |      1.3
       5 |     2 |        -1 |    6 |   10 |    2 |    1 |      1.6
       6 |     3 |        -1 |   -6 |    7 |    4 |  0.3 |      1.6
       7 |     3 |        -1 |   10 |   -5 |    5 |  0.8 |      2.4
       8 |     3 |        -1 |   10 |   15 |    3 |    1 |      2.6
       9 |     4 |        -1 |    7 |    3 |    7 |    1 |      2.6
      10 |     4 |        -1 |    7 |    8 |   10 |    1 |      2.6
      11 |     4 |        -1 |    7 |   11 |    8 |    1 |      2.6
      12 |     5 |        -1 |    8 |   -3 |   12 |  0.6 |      3.2
      13 |     5 |        -1 |    3 |   -4 |    6 |  0.7 |      3.3
    (13 rows)

## See Also

- pgr_drivingDistance

- pgr_alphaShape

- Sample Data

Indices and tables

- Index

- Search Page