Bd astar output standarization (#2523)

* [bdAstar] standarizing output columns

NEWS

@@ -3,14 +3,25 @@ pgRouting 3.6.0 Release Notes
 
 **Official functions changes**
 
-* aStar
+* `2516 <https://github.com/pgRouting/pgrouting/pull/2516>` Standarize output
+  pgr_aStar
 
   * Standarizing output columns to |short-generic-result|
 
     * ``pgr_aStar`` (`One to One`) added ``start_vid`` and ``end_vid`` columns.
     * ``pgr_aStar`` (`One to Many`) added ``end_vid`` column.
     * ``pgr_aStar`` (`Many to One`) added ``start_vid`` column.
 
+* `2523 <https://github.com/pgRouting/pgrouting/pull/2523>` Standarize output
+  pgr_bdAstar
+
+  * Standarizing output columns to |short-generic-result|
+
+    * ``pgr_bdAstar`` (`One to One`) added ``start_vid`` and ``end_vid`` columns.
+    * ``pgr_bdAstar`` (`One to Many`) added ``end_vid`` column.
+    * ``pgr_bdAstar`` (`Many to One`) added ``start_vid`` column.
+
+
 **C/C++ code enhancements**
 
 * `2504 <https://github.com/pgRouting/pgrouting/pull/2504>` To C++ pg data get,

doc/astar/pgr_aStar.rst

@@ -22,7 +22,7 @@
 
 .. rubric:: Availability
 
-* Version 3.5.0
+* Version 3.6.0
 
   * Standarizing output columns to |short-generic-result|
 
@@ -73,9 +73,7 @@ Description
   * `pgr_aStar(` `One to Many`_ `)`
   * `pgr_aStar(` `Many to One`_ `)`
   * `pgr_aStar(` `Many to Many`_ `)`
-
-* ``start_vid`` and ``end_vid`` in the result is used to distinguish to which
-  path it belongs.
+  * `pgr_aStar(` `Combinations`_ `)`
 
 Signatures
 -------------------------------------------------------------------------------

doc/bdAstar/pgr_bdAstar.rst

@@ -22,6 +22,14 @@
 
 .. rubric:: Availability
 
+* Version 3.6.0
+
+  * Standarizing output columns to |short-generic-result|
+
+    * ``pgr_bdAstar`` (`One to One`_) added ``start_vid`` and ``end_vid`` columns.
+    * ``pgr_bdAstar`` (`One to Many`_) added ``end_vid`` column.
+    * ``pgr_bdAstar`` (`Many to One`_) added ``start_vid`` column.
+
 * Version 3.2.0
 
   * New **proposed** signature:
@@ -48,7 +56,6 @@
 
   * **Official** ``pgr_bdAstar`` (`One to One`_)
 
-
 Description
 -------------------------------------------------------------------------------
 
@@ -64,9 +71,7 @@ Description
   * `pgr_bdAstar(` `One to Many`_ `)`
   * `pgr_bdAstar(` `Many to One`_ `)`
   * `pgr_bdAstar(` `Many to Many`_ `)`
-
-* ``start_vid`` and ``end_vid`` in the result is used to distinguish to which
-  path it belongs.
+  * `pgr_bdAstar(` `Combinations`_ `)`
 
 Signatures
 -------------------------------------------------------------------------------
@@ -83,7 +88,7 @@ Signatures
    | pgr_bdAstar(`Edges SQL`_, `Combinations SQL`_, [**options**])
    | **options:** ``[directed, heuristic, factor, epsilon]``
 
-   | RETURNS SET OF |old-generic-result|
+   | RETURNS SET OF |short-generic-result|
    | OR EMPTY SET
 
 Optional parameters are `named parameters` and have a default value.
@@ -100,7 +105,7 @@ One to One
    | pgr_bdAstar(`Edges SQL`_, **start vid**, **end vid**, [**options**])
    | **options:** ``[directed, heuristic, factor, epsilon]``
 
-   | RETURNS SET OF |result-1-1|
+   | RETURNS SET OF |short-generic-result|
    | OR EMPTY SET
 
 :Example: From vertex :math:`6` to vertex :math:`12` on a **directed** graph
@@ -122,7 +127,7 @@ One to Many
    | pgr_bdAstar(`Edges SQL`_, **start vid**, **end vids**, [**options**])
    | **options:** ``[directed, heuristic, factor, epsilon]``
 
-   | RETURNS SET OF |result-1-m|
+   | RETURNS SET OF |short-generic-result|
    | OR EMPTY SET
 
 :Example: From vertex :math:`6` to vertices :math:`\{10, 12\}` on a **directed**
@@ -144,7 +149,7 @@ Many to One
    | pgr_bdAstar(`Edges SQL`_, **start vids**, **end vid**, [**options**])
    | **options:** ``[directed, heuristic, factor, epsilon]``
 
-   | RETURNS SET OF |result-m-1|
+   | RETURNS SET OF |short-generic-result|
    | OR EMPTY SET
 
 :Example: From vertices :math:`\{6, 8\}` to vertex :math:`10` on an

doc/src/migration.rst

@@ -105,6 +105,73 @@ Signatures to be migrated:
     the function ``my_dijkstra`` returns the new additional columns of
     ``pgr_dijkstra``.
 
+Migration of ``pgr_bdAstar``
+-------------------------------------------------------------------------------
+
+Starting from `v3.6.0 <https://docs.pgrouting.org/3.6/en/migration.html>`__
+
+Signatures to be migrated:
+
+* ``pgr_bdAstar`` (`One to One`)
+* ``pgr_bdAstar`` (`One to Many`)
+* ``pgr_bdAstar`` (`Many to One`)
+
+:Before Migration:
+
+* Output columns were |old-generic-result|
+
+  * Depending on the overload used, the columns ``start_vid`` and ``end_vid``
+    might be missing:
+
+    * ``pgr_bdAstar`` (`One to One`) does not have ``start_vid`` and ``end_vid``.
+    * ``pgr_bdAstar`` (`One to Many`) does not have ``start_vid``.
+    * ``pgr_bdAstar`` (`Many to One`) does not have ``end_vid``.
+
+:Migration:
+
+* Be aware of the existance of the additional columns.
+
+* In ``pgr_bdAstar`` (`One to One`)
+
+  * ``start_vid`` contains the **start vid** parameter value.
+  * ``end_vid`` contains the **end vid** parameter value.
+
+.. literalinclude:: migration.queries
+   :start-after: --bdastar1
+   :end-before: --bdastar2
+
+* In ``pgr_bdAstar`` (`One to Many`)
+
+  * ``start_vid`` contains the **start vid** parameter value.
+
+.. literalinclude:: migration.queries
+   :start-after: --bdastar2
+   :end-before: --bdastar3
+
+* In ``pgr_bdAstar`` (`Many to One`)
+
+  * ``end_vid`` contains the **end vid** parameter value.
+
+.. literalinclude:: migration.queries
+   :start-after: --bdastar3
+   :end-before: --bdastar4
+
+* If needed filter out the added columns, for example:
+
+.. literalinclude:: migration.queries
+   :start-after: --bdastar4
+   :end-before: --bdastar5
+
+* If needed add the new columns, similar to the following example where
+  ``pgr_dijkstra`` is used, and the function had to be modified to be able to
+  return the new columns:
+
+  * In `v3.0 <https://docs.pgrouting.org/3.0/en/contraction-family.html#case-1-both-source-and-target-belong-to-the-contracted-graph>`__
+    the function ``my_dijkstra`` uses ``pgr_dijkstra``.
+  * Starting from `v3.5 <https://docs.pgrouting.org/3.5/en/contraction-family.html#case-1-both-source-and-target-belong-to-the-contracted-graph>`__
+    the function ``my_dijkstra`` returns the new additional columns of
+    ``pgr_dijkstra``.
+
 
 Migration of ``pgr_dijkstra``
 -------------------------------------------------------------------------------

doc/src/release_notes.rst

@@ -24,14 +24,25 @@ pgRouting 3.6.0 Release Notes
 
 .. rubric:: Official functions changes
 
-* aStar
+* `2516 <https://github.com/pgRouting/pgrouting/pull/2516>` Standarize output
+  pgr_aStar
 
   * Standarizing output columns to |short-generic-result|
 
     * ``pgr_aStar`` (`One to One`) added ``start_vid`` and ``end_vid`` columns.
     * ``pgr_aStar`` (`One to Many`) added ``end_vid`` column.
     * ``pgr_aStar`` (`Many to One`) added ``start_vid`` column.
 
+* `2523 <https://github.com/pgRouting/pgrouting/pull/2523>` Standarize output
+  pgr_bdAstar
+
+  * Standarizing output columns to |short-generic-result|
+
+    * ``pgr_bdAstar`` (`One to One`) added ``start_vid`` and ``end_vid`` columns.
+    * ``pgr_bdAstar`` (`One to Many`) added ``end_vid`` column.
+    * ``pgr_bdAstar`` (`Many to One`) added ``start_vid`` column.
+
+
 .. rubric:: C/C++ code enhancements
 
 * `2504 <https://github.com/pgRouting/pgrouting/pull/2504>` To C++ pg data get,

docqueries/bdAstar/doc-pgr_bdAstar.result

@@ -9,12 +9,12 @@ SELECT * FROM pgr_bdAstar(
   6, 12,
   directed => true, heuristic => 2
 );
- seq | path_seq | node | edge | cost | agg_cost
------+----------+------+------+------+----------
-   1 |        1 |    6 |    4 |    1 |        0
-   2 |        2 |    7 |   10 |    1 |        1
-   3 |        3 |    8 |   12 |    1 |        2
-   4 |        4 |   12 |   -1 |    0 |        3
+ seq | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
+-----+----------+-----------+---------+------+------+------+----------
+   1 |        1 |         6 |      12 |    6 |    4 |    1 |        0
+   2 |        2 |         6 |      12 |    7 |   10 |    1 |        1
+   3 |        3 |         6 |      12 |    8 |   12 |    1 |        2
+   4 |        4 |         6 |      12 |   12 |   -1 |    0 |        3
 (4 rows)
 
 /* -- q3 */
@@ -24,18 +24,18 @@ SELECT * FROM pgr_bdAstar(
   6, ARRAY[10, 12],
   heuristic => 3, factor := 3.5
 );
- seq | path_seq | end_vid | node | edge | cost | agg_cost
------+----------+---------+------+------+------+----------
-   1 |        1 |      10 |    6 |    4 |    1 |        0
-   2 |        2 |      10 |    7 |    8 |    1 |        1
-   3 |        3 |      10 |   11 |    9 |    1 |        2
-   4 |        4 |      10 |   16 |   16 |    1 |        3
-   5 |        5 |      10 |   15 |    3 |    1 |        4
-   6 |        6 |      10 |   10 |   -1 |    0 |        5
-   7 |        1 |      12 |    6 |    4 |    1 |        0
-   8 |        2 |      12 |    7 |    8 |    1 |        1
-   9 |        3 |      12 |   11 |   11 |    1 |        2
-  10 |        4 |      12 |   12 |   -1 |    0 |        3
+ seq | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
+-----+----------+-----------+---------+------+------+------+----------
+   1 |        1 |         6 |      10 |    6 |    4 |    1 |        0
+   2 |        2 |         6 |      10 |    7 |    8 |    1 |        1
+   3 |        3 |         6 |      10 |   11 |    9 |    1 |        2
+   4 |        4 |         6 |      10 |   16 |   16 |    1 |        3
+   5 |        5 |         6 |      10 |   15 |    3 |    1 |        4
+   6 |        6 |         6 |      10 |   10 |   -1 |    0 |        5
+   7 |        1 |         6 |      12 |    6 |    4 |    1 |        0
+   8 |        2 |         6 |      12 |    7 |    8 |    1 |        1
+   9 |        3 |         6 |      12 |   11 |   11 |    1 |        2
+  10 |        4 |         6 |      12 |   12 |   -1 |    0 |        3
 (10 rows)
 
 /* -- q4 */
@@ -45,14 +45,14 @@ SELECT * FROM pgr_bdAstar(
   ARRAY[6, 8], 10,
   false, heuristic => 4
 );
- seq | path_seq | start_vid | node | edge | cost | agg_cost
------+----------+-----------+------+------+------+----------
-   1 |        1 |         6 |    6 |    2 |    1 |        0
-   2 |        2 |         6 |   10 |   -1 |    0 |        1
-   3 |        1 |         8 |    8 |   10 |    1 |        0
-   4 |        2 |         8 |    7 |    4 |    1 |        1
-   5 |        3 |         8 |    6 |    2 |    1 |        2
-   6 |        4 |         8 |   10 |   -1 |    0 |        3
+ seq | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
+-----+----------+-----------+---------+------+------+------+----------
+   1 |        1 |         6 |      10 |    6 |    2 |    1 |        0
+   2 |        2 |         6 |      10 |   10 |   -1 |    0 |        1
+   3 |        1 |         8 |      10 |    8 |   10 |    1 |        0
+   4 |        2 |         8 |      10 |    7 |    4 |    1 |        1
+   5 |        3 |         8 |      10 |    6 |    2 |    1 |        2
+   6 |        4 |         8 |      10 |   10 |   -1 |    0 |        3
 (6 rows)
 
 /* -- q5 */

docqueries/src/migration.result

@@ -719,5 +719,71 @@ SELECT seq, path_seq, node, edge, cost, agg_cost FROM pgr_aStar(
 (6 rows)
 
 /* --astar5 */
+/* --bdastar1 */
+SELECT * FROM pgr_aStar(
+  $$SELECT id, source, target, cost, reverse_cost, x1, y1, x2, y2 FROM edges$$,
+  6, 10);
+ seq | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
+-----+----------+-----------+---------+------+------+------+----------
+   1 |        1 |         6 |      10 |    6 |    4 |    1 |        0
+   2 |        2 |         6 |      10 |    7 |    8 |    1 |        1
+   3 |        3 |         6 |      10 |   11 |    9 |    1 |        2
+   4 |        4 |         6 |      10 |   16 |   16 |    1 |        3
+   5 |        5 |         6 |      10 |   15 |    3 |    1 |        4
+   6 |        6 |         6 |      10 |   10 |   -1 |    0 |        5
+(6 rows)
+
+/* --bdastar2 */
+SELECT * FROM pgr_aStar(
+  $$SELECT id, source, target, cost, reverse_cost, x1, y1, x2, y2 FROM edges$$,
+  6, ARRAY[3, 10]);
+ seq | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
+-----+----------+-----------+---------+------+------+------+----------
+   1 |        1 |         6 |       3 |    6 |    4 |    1 |        0
+   2 |        2 |         6 |       3 |    7 |    7 |    1 |        1
+   3 |        3 |         6 |       3 |    3 |   -1 |    0 |        2
+   4 |        1 |         6 |      10 |    6 |    4 |    1 |        0
+   5 |        2 |         6 |      10 |    7 |    8 |    1 |        1
+   6 |        3 |         6 |      10 |   11 |    9 |    1 |        2
+   7 |        4 |         6 |      10 |   16 |   16 |    1 |        3
+   8 |        5 |         6 |      10 |   15 |    3 |    1 |        4
+   9 |        6 |         6 |      10 |   10 |   -1 |    0 |        5
+(9 rows)
+
+/* --bdastar3 */
+SELECT * FROM pgr_aStar(
+  $$SELECT id, source, target, cost, reverse_cost, x1, y1, x2, y2 FROM edges$$,
+  ARRAY[3, 6], 10);
+ seq | path_seq | start_vid | end_vid | node | edge | cost | agg_cost
+-----+----------+-----------+---------+------+------+------+----------
+   1 |        1 |         3 |      10 |    3 |    7 |    1 |        0
+   2 |        2 |         3 |      10 |    7 |    8 |    1 |        1
+   3 |        3 |         3 |      10 |   11 |    9 |    1 |        2
+   4 |        4 |         3 |      10 |   16 |   16 |    1 |        3
+   5 |        5 |         3 |      10 |   15 |    3 |    1 |        4
+   6 |        6 |         3 |      10 |   10 |   -1 |    0 |        5
+   7 |        1 |         6 |      10 |    6 |    4 |    1 |        0
+   8 |        2 |         6 |      10 |    7 |    8 |    1 |        1
+   9 |        3 |         6 |      10 |   11 |    9 |    1 |        2
+  10 |        4 |         6 |      10 |   16 |   16 |    1 |        3
+  11 |        5 |         6 |      10 |   15 |    3 |    1 |        4
+  12 |        6 |         6 |      10 |   10 |   -1 |    0 |        5
+(12 rows)
+
+/* --bdastar4 */
+SELECT seq, path_seq, node, edge, cost, agg_cost FROM pgr_aStar(
+  $$SELECT id, source, target, cost, reverse_cost, x1, y1, x2, y2 FROM edges$$,
+  6, 10);
+ seq | path_seq | node | edge | cost | agg_cost
+-----+----------+------+------+------+----------
+   1 |        1 |    6 |    4 |    1 |        0
+   2 |        2 |    7 |    8 |    1 |        1
+   3 |        3 |   11 |    9 |    1 |        2
+   4 |        4 |   16 |   16 |    1 |        3
+   5 |        5 |   15 |    3 |    1 |        4
+   6 |        6 |   10 |   -1 |    0 |        5
+(6 rows)
+
+/* --bdastar5 */
 ROLLBACK;
 ROLLBACK

docqueries/src/migration.test.sql

@@ -244,3 +244,20 @@ SELECT seq, path_seq, node, edge, cost, agg_cost FROM pgr_aStar(
   $$SELECT id, source, target, cost, reverse_cost, x1, y1, x2, y2 FROM edges$$,
   6, 10);
 /* --astar5 */
+/* --bdastar1 */
+SELECT * FROM pgr_aStar(
+  $$SELECT id, source, target, cost, reverse_cost, x1, y1, x2, y2 FROM edges$$,
+  6, 10);
+/* --bdastar2 */
+SELECT * FROM pgr_aStar(
+  $$SELECT id, source, target, cost, reverse_cost, x1, y1, x2, y2 FROM edges$$,
+  6, ARRAY[3, 10]);
+/* --bdastar3 */
+SELECT * FROM pgr_aStar(
+  $$SELECT id, source, target, cost, reverse_cost, x1, y1, x2, y2 FROM edges$$,
+  ARRAY[3, 6], 10);
+/* --bdastar4 */
+SELECT seq, path_seq, node, edge, cost, agg_cost FROM pgr_aStar(
+  $$SELECT id, source, target, cost, reverse_cost, x1, y1, x2, y2 FROM edges$$,
+  6, 10);
+/* --bdastar5 */