User data models restrictions on the road network. Currently, there are two kinds of user data in the routing engine: restricted driving maneuvers (turn restrictions) and trucking user data.
User data is versioned. When user data is partitioned, the routing engine data version from the SDO_ROUTER_DATA_VERSION table is stored in the user data BLOBs. When user data is brought into the cache, the version stored in the user data partition must be compatible with the version in the SDO_ROUTER_DATA_VERSION table.
Partitioning user data is generally a very fast operation. It can be done as part of the partitioning the routing engine data or, if the routing engine data is already partitioned, as a standalone operation. In both cases the user data partitioning uses the partitioned routing engine data as a guide, substantially speeding up the partitioning operation.
The number of user data partitions is equal to or less than the number of routing engine data partitions. If there is no user data associated with a routing engine data partition, then no user data partition is produced. User data local partitions move into and out of the cache with their associated routing engine data partition. The user data highway partition is loaded at routing engine startup and remains resident in the cache.
In Release 12c the restricted driving maneuver user data is part of the routing engine ODF data shipped by data vendors. Trucking user data is not shipped with the routing engine ODF data and must be purchased separately. When a Release 12c or later routing engine starts, it detects and uses any available user data. All versions of the routing engine before Release 12c do not detect the user data and will only use routing engine data to compute the routes.
This section includes the following topics:
A restricted driving maneuver can be as simple as not allowing movement from one edge to another, such as a simple turn restriction that does not allow a left turn. Or it might be a highly complex maneuver involving many edges, such as a no U-turn restriction on a road divided with a median where there is a start edge, an edge over the median, and the edge on the road going the other direction.
The routing engine uses three tables for restricted driving maneuvers. The first two tables, ROUTER_NAV_STRAND and ROUTER_CONDITION contain the raw data to build the restricted maneuvers user data.
The final table, ROUTER_TURN_RESTRICTION_DATA, contains the partitioned restricted maneuver user data stored in BLOB format. Partitioning the restricted maneuver data allows it to move in and out of the cache with the routing engine data of the same partition.
In Release 12c the restricted driving maneuver user data is part of the ODF data shipped by the data vendors. When a Release 12c routing engine starts, it detects and uses the turn restriction user data. If a Release 11grouting engine starts, it will not detect the user data and will only use routing engine data to compute the routes.
Because the restricted driving maneuver user data is part of the ODF data set, it is already partitioned. Generally, there is no reason to repartition this user data. However, if the routing engine data is repartitioned, the user data will also be repartitioned. It is also possible to repartition the turn restriction user data without having to repartition the routing engine data by re-creating the restricted driving maneuver user data.
Syntax:
SDO_ROUTER_PARTITION.CREATE_TURN_RESTRICTION_DATA(
LOG_FILE_NAME IN VARCHAR2 := 'sdo_router_partition.log',
CLEANUP IN BOOLEAN DEFAULT TRUE);
The CREATE_TURN_RESTRICTION_DATA procedure must be run from a routing engine schema that contains the restricted driving maneuver raw data tables ROUTER_NAV_STRAND and ROUTER_CONDITION. This procedure partitions the restricted driving maneuver data and creates the ROUTER_TURN_RESTRICTION_DATA table containing the turn restriction user data in BLOB format. Turn restriction user data creation requires access to the data version so the SDO_ROUTER_DATA_VERSION table must exist in the routing engine schema.
The LOG_FILE_NAME parameter is the name of the log file written during turn restriction generation. This log file is created in the SDO_ROUTER_LOG_DIR directory. You can choose a log file name or use the default partitioning log file sdo_router_partition.log.
The CLEANUP parameter is used for debugging. By default, all of the intermediate tables created during turn restriction generation are cleaned up. If there is problem with turn restriction generation, leaving these tables in place can provide substantial debugging information.
Syntax:
SDO_ROUTER_PARTITION.DUMP_TURN_RESTRICTION_DATA(
LOG_FILE_NAME IN VARCHAR2 := 'sdo_router_partition.log',
START_PID IN NUMBER DEFAULT 0,
END_PID IN NUMBER DEFAULT -1,
DUMP_SOFT_RESTRICTIONS IN BOOLEAN DEFAULT FALSE);
The DUMP_TURN_RESTRICTION_DATA procedure dumps the contents of the turn restriction user data partition BLOBs. This procedure unpacks a BLOB, formats the data, and writes it to a log file. A single call to this procedure can dump a single partition or a contiguous range of partitions. This range is defined from START_PID to END_PID, inclusive. The default is to dump all partitions. A non-contiguous range of partitions cannot be dumped in a single call.
The LOG_FILE_NAME parameter specifies the name of the log file written when dumping turn restriction user data partitions. This log file is created in the SDO_ROUTER_LOG_DIR directory. You can choose a log file name or write to the default partitioning log file sdo_router_partition.log.
The START_PID parameter is the ID of the first partition to dump. The default START_PID is 0. The START_PID must be less than or equal to END_PID.
The END_PID parameter is the ID of the last partition to dump. The default END_PID is -1, which is converted to the highest partition ID in the data set. If the start and end PID values are equal, a single partition is dumped. If END_PID is less than START_PID, an error message is written to the log.
The DUMP_SOFT_RESTRICTIONS parameter controls how the turn restriction data is dumped. In turn restrictions that have more than two edges, a soft restriction is a series of edges that partially describe the turn restriction. This is a debugging parameter and should generally be left set to its default value, FALSE.
Syntax:
SDO_ROUTER_PARTITION.CREATE_TRUCKING_DATA(
LOG_FILE_NAME IN VARCHAR2 := ' sdo_router_partition.log',
CLEANUP IN BOOLEAN DEFAULT TRUE);
The CREATE_TRUCKING_DATA procedure must be run from a routing engine schema that contains the raw trucking data table ROUTER_TRANSPORT. This procedure partitions the trucking data and creates the ROUTER_TRUCKING_DATA table containing the trucking user data in BLOB format. Trucking user data creation requires access to the data version, so the SDO_ROUTER_DATA_VERSION table must exist in the routing engine schema.
The LOG_FILE_NAME parameter is the name of the log file written during trucking restriction generation. This log file is created in the SDO_ROUTER_LOG_DIR directory. You can choose a log file name or use the default partitioning log file sdo_router_partition.log.
The CLEANUP parameter is used for debugging. By default, all of the intermediate tables created during trucking restriction generation are cleaned up. If there is problem with trucking restriction generation, leaving these tables in place can provide substantial debugging information.
Syntax:
SDO_ROUTER_PARTITION.DUMP_TRUCKING_DATA(
LOG_FILE_NAME IN VARCHAR2 := ' sdo_router_partition.log',
START_PID IN NUMBER DEFAULT 0,
END_PID IN NUMBER DEFAULT -1,
SKIP_UNSUPPORTED IN BOOLEAN DEFAULT TRUE);
The DUMP_TRUCKING_DATA procedure dumps the contents of the trucking restriction user data partition BLOBs. This procedure unpacks a BLOB, formats the data, and writes it to a log file. A single call to this procedure can dump a single partition or a contiguous range of partitions. This range is defined from START_PID to END_PID, inclusive. The default is to dump all partitions. A non-contiguous range of partitions cannot be dumped in a single call.
The LOG_FILE_NAME parameter specifies the name of the log file written when dumping trucking restriction user data partitions. This log file is created in the SDO_ROUTER_LOG_DIR directory. You can choose a log file name or write to the default partitioning log file sdo_router_partition.log.
The START_PID parameter is the ID of the first partition to dump. The default START_PID is 0. The START_PID must be less than or equal to END_PID.
The END_PID parameter is the ID of the last partition to dump. The default END_PID is -1, which is converted to the highest partition ID in the data set. If the start and end PID values are equal, a single partition is dumped. If END_PID is less than START_PID, an error message is written to the log.
The SKIP_UNSUPPORTED parameter controls how the trucking restriction data is dumped. The user data contains a number of restrictions included for future work but not currently supported. Setting SKIP_UNSUPPORTED to TRUE (the default) only dumps currently supported trucking restrictions. Setting SKIP_UNSUPPORTED to FALSE causes all trucking restrictions to be dumped.
This section presents examples of operations involving user data. The data set in these examples is the road network data for a radius of 100 miles around the center of San Francisco. This data set contains about 520,000 nodes and 1,200,00 edges, including 82,000 edges with truck restrictions and 30,000 edges with restricted driving maneuvers.
This section contains examples of the following:
Example E-8 rebuilds the turn restriction user data. Because cleanup is set to FALSE, the intermediate tables used to rebuild the turn restriction user data will not be deleted. (To delete these tables execute the SDO_ROUTER_PARTITION.CLEANUP_ROUTER Procedure.)
Example E-8 Rebuilding the Turn Restriction User Data
EXEC SDO_ROUTER_PARTITION.CREATE_TURN_RESTRICTION_DATA(
'rebuild_turn_restriction_data.log', FALSE);
******** Begin generation of turn restriction user data
** Logfile ___location: /scratch/logs/rebuild_turn_restriction_data.log
[INFO] Generating turn restriction user data for 995 partitions, data version (12.1.0.1.2)
[INFO] SQL String: CREATE TABLE new_turn_restriction_data(partition_id NUMBER, num_edges NUMBER, turn_restriction_data BLOB) LOB(turn_restriction_data) STORE AS (STORAGE (INITIAL 512K NEXT 128K MAXEXTENTS UNLIMITED) CHUNK 32768 NOCACHE NOLOGGING)
[INFO] ---- Writing 573 edges for partition 0
[INFO] ---- Writing 16 edges for partition 1
[INFO] ---- Writing 10 edges for partition 2
*** Note that partition 3 contains no turn restriction user data
[INFO] ---- Writing 8 edges for partition 4
[INFO] ---- Writing 23 edges for partition 5
[INFO] ---- Writing 39 edges for partition 6
*** Many more Writing partition messages
[INFO] ---- Writing 4 edges for partition 1023
[INFO] ---- Writing 11 edges for partition 1024
INFO: creating the final turn restriction user data table
INFO: create index rtrud_p_idx on router_turn_restriction_data table
******** Completed generation of turn restriction user dataExample E-9 dumps all of the hard turn restriction user data BLOBS. (Dumping soft restrictions produces much larger dump files and is only useful when debugging problems in the turn restrictions constraints.)
Example E-9 Dumping All Hard Turn Restriction User Data BLOBs
EXEC SDO_ROUTER_PARTITION.DUMP_TURN_RESTRICTION_DATA(
'dump_all_turn_restrictions.log');
******** Beginning turn restriction dump
** Logfile ___location: /scratch/logs/dump_all_turn_restrictions.log
** Routeserver data version: 12.1.0.1.2 (A)
** Start partition id: 0
** End partition id: 1024
** Dumping soft restrictions: FALSE
Starting turn restriction dump for partition 0, blob length 19956 bytes
Data version: 12.1.0.1.2
Partition 0 has 573 edges with turn restrictions (B)
edge id -937799058 has 1 turn restrictions
Restriction Type/Attributes: Hard/None
AppliesTo(959): Trucks, Through Traffic, Taxies, Motorcycles,
Emergency Vehicles, Delivery Vehicles, Carpools,
Buses, Automobiles
Subpath(1): 24501308
*******************************
edge id -936524317 has 2 turn restrictions (C)
Restriction Type/Attributes: Hard/None
AppliesTo(943): Trucks, Through Traffic, Taxies, Motorcycles,
Delivery Vehicles, Carpools, Buses, Automobiles
Subpath(1): -724922777
-------
Restriction Type/Attributes: Hard/None
AppliesTo(959): Trucks, Through Traffic, Taxies, Motorcycles,
Emergency Vehicles, Delivery Vehicles, Carpools,
Buses, Automobiles
Subpath(1): 936524317
*******************************
edge id -932185370 has 2 turn restrictions
Restriction Type/Attributes: Hard/None
AppliesTo(1023): All Vehicles
Subpath(1): 836074944
-------
Restriction Type/Attributes: Hard/None
AppliesTo(1023): All Vehicles
Subpath(1): -24638792
*******************************
edge id 834380593 has 1 turn restrictions (D)
Restriction Type/Attributes: Hard/None
AppliesTo(943): Trucks, Through Traffic, Taxies, Motorcycles,
Delivery Vehicles, Carpools, Buses, Automobiles
Subpath(4): 112065672, -112065610, -112008660, -834380591
*******************************
*** Dump of the remaining restrictions in Partition 0
Starting turn restriction dump for partition 1, blob length 520 bytes
Partition 1 has 16 edges with turn restrictions (E)
edge id -806530190 has 1 turn restrictions
Restriction Type/Attributes: Hard/None
AppliesTo(703): Trucks, Taxies, Motorcycles, Emergency Vehicles,
Delivery Vehicles, Carpools, Buses, Automobiles
Subpath(1): 120865027
*******************************
*** Dump of the remaining restrictions in Partition 1 through 1024
In Example E-9:
(A): The standard user dump header contains the ___location of the log file and the parameters used in the dump. It also contains the routing engine data version as queried from the SDO_ROUTER_DATA_VERSION table. This data version must match the data version stored in the header of the partition 0 BLOB.
(B): In the BLOB header section for the partition 0 BLOB, all turn restriction user data BLOB headers contain the partition ID, length of the BLOB in bytes, and number of edges with turn restrictions on them. The BLOB header for partition 0 also contains the user data version. This version must match the data version found in the SDO_ROUTER_DATA_VERSION table.
(C): In the dump of the turn restrictions for edge -936524317., this edge has two simple turn restrictions associated with it. Both restrictions are simple turn restrictions that do not allow movement from the single edge in the subpath to edge -936524317. Also note the difference in the vehicles to which the restrictions apply: the first restriction does not apply to emergency vehicles, but the second restriction does apply to emergency vehicles.
(D): Edge 834380593 has only one turn restriction, but the restriction being described is much more complicated than a simple turn. If the subpath immediately previous to edge 834380593 matches the subpath that starts at edge -834380591 and goes through edges -112008660, -112065610, 112065672 in precisely that order, then the maneuver is not allowed. If the subpath to the current edge is missing one of the listed subpath edges or if the edges in the subpath are in a different order, then the maneuver is allowed.
(E): In the BLOB header for local partitions, all turn restriction user data BLOB headers contain the partition ID, length of the BLOB in bytes, and number of edges with turn restrictions on them.
Example E-10 rebuilds the trucking user data. Since cleanup is using the default value of TRUE the intermediate tables used to rebuild the turn restriction user data are deleted when the build completes.
Example E-10 Rebuilding the Trucking User Data
EXEC SDO_ROUTER_PARTITION.CREATE_TRUCKING_DATA(
'rebuild_trucking_data.log');
******** Begin generation of trucking user data
** Logfile ___location:/scratch/logs/rebuild_trucking_data.log
[INFO] Generating trucking user data for 974 partitions,
data version (12.1.0.1.2) (A)
[INFO] SQL String: CREATE TABLE new_trucking_data
(partition_id NUMBER, num_edges NUMBER, trucking_data BLOB) LOB(trucking_data) STORE AS (STORAGE (INITIAL 512K NEXT 128K MAXEXTENTS UNLIMITED) CHUNK 32768 NOCACHE NOLOGGING)
INFO: creating the final trucking user data table
INFO: create index rtud_p_idx on router_trucking_data table
******** Completed generation of trucking user data
In Example E-10:
(A): Note that there are only 974 partitions of trucking user data compared to the 1023 local partitions (see the output in Example E-9) of routing engine data. If a partition is missing in the user data output, this means there is no trucking data for the associated routing engine data partition.
Example E-11 dumps the trucking user data restrictions. This example dumps the supported restrictions for partitions 0 through 25. In the dump, Main Type is type of restriction, Subtype is the reason for the restriction, and Value is the means to measure the restriction. For example, a height restriction is a Main Type, the Subtype can be a thing like Bridge or Tunnel or can be Unknown, and Value can be a measure (always metric) like meters for height and width or metric tons for weight. Value can also be 0 for some restrictions (for example legal restrictions) that cannot be physically measured.
Example E-11 Dumping the Trucking User Data Restrictions
EXEC SDO_ROUTER_PARTITION.DUMP_TRUCKING_DATA(
'dump_trucking_data0-25.log', 0, 25);
******** Beginning trucking data dump
** Logfile ___location: /scratch/logs/dump_trucking_data0-25.log
** Routeserver data version: 12.1.0.1.2 (A)
** Start partition id: 0
** End partition id: 25
Starting truck data dump for partition 0, blob length 1019048 bytes
Data version: 12.1.0.1.2
Partition 0 has 21808 edges with truck data (B)
edge id -939054768 has 4 truck restrictions
Main Type(10): Physical Height Restriction
Sub-type(99): Unknown
Value: 4.65
*******************************
edge id -854677940 has 3 truck restrictions
Main Type(10): Physical Height Restriction
Sub-type(1): Bridge
Value: 4.67
*******************************
edge id -929320205 has 4 truck restrictions (C)
Main Type(10): Physical Height Restriction
Sub-type(2): Tunnel
Value: 4.27
-------
Main Type(20): Physical Weight Restriction
Sub-type(99): Unknown
Value: 4.08
*******************************
*** The rest of the trucking data for edges in partition 0
Starting truck data dump for partition 2, blob length 296 bytes
(D)
Starting truck data dump for partition 3, blob length 3272 bytes
Partition 3 has 91 edges with truck data
edge id -811551125 has 1 truck restrictions
Main Type(50): Legal Restriction
Sub-type(22): All trailers forbidden
Value: 0.0
*******************************
edge id 105439903 has 1 truck restrictions
Main Type(20): Physical Weight Restriction
Sub-type(99): Unknown
Value: 9.07
*******************************
edge id -105491810 has 1 truck restrictions (E)
Main Type(50): Legal Restriction
Sub-type(21): All trucks forbidden
Value: 0.0
*******************************
edge id -105449802 has 1 truck restrictions
Main Type(50): Legal Restriction
Sub-type(26): All trucks forbidden except deliveries and residents
Value: 0.0
*******************************
*** The rest of the trucking data for edges in partitions 3 through 25
In Example E-11:
(A): The standard user dump header contains the ___location of the log file and the parameters used in the dump. It also contains the routing engine data version as queried from the SDO_ROUTER_DATA_VERSION table. This data version must match the data version stored in the header of the partition 0 BLOB.
(B): In the BLOB header section for the partition 0 BLOB, all turn restriction user data BLOB headers contain the partition ID, length of the BLOB in bytes, and number of edges with turn restrictions on them. The BLOB header for partition 0 also contains the user data version. This version must match the data version found in the SDO_ROUTER_DATA_VERSION table.
Edge -939054768 is listed as having 4 truck restrictions, but only one is listed. The other three restrictions are there, but are currently unsupported in the routing engine. To see these restrictions, set the SKIP_UNSUPPORTED to FALSE when requesting the dump.
For edge -929320205 the Height restriction is because of a Bridge. Edge -939054768 also has a Height restriction, but there is no Subtype specified to explain why.
(C): This is an example of an edge that has multiple restrictions on it, in this case both a height and weight restriction expressed in meters and metric tons.
(D): Two things to note here: (1) partition 1 is missing, which means there is no trucking user data for partition 1; and (2) a partition header was printed for partition 2 but there is no data dumped, which means that there are trucking restrictions for partition 2 but the routing engine currently supports none of them.
(E): This is an example of two kinds of legal restrictions that can be modeled. (1) Edge -105491810 is an example of an exclusive legal restriction. There is a legal restriction on the edge that forbids all trucks. (2) Edge -105449802 is an example of an inclusive legal restriction. There is a legal restriction that excludes trucks on the edge but also lists an exception for delivery and resident trucks.