The routing engine uses routing engine data and user data. The routing engine data is stored in the EDGE, NODE, SIGN_POST, and PARTITION tables.
The routing engine data models a road network as a directed graph of nodes and edges. Partitioning breaks this road network into 2**N (2N) subgraphs (local partitions) and one highway partition. The nodes of the road network are partitioned topologically, so each local partition contains the same number of nodes. Each node in the network is in one and only one partition. An edge can be entirely within a partition, an internal edge, or a bridge two partitions (that is, a boundary edge). The partitions are stored in the database as BLOBs, so they can easily be read into and removed from a cache. This allows the routing engine to operate without needing the entire road network to be in memory.
Partitions 1 through N, local partitions, are all roughly the same size. Local partitions are read into the cache as needed when computing a route. These partitions remain in the cache until the cache is full, at which point the least used partitions are swapped out to make room for the partitions needed to compute the current route.
Partition 0 (zero), the highway partition, differs from local partitions in two respects:
It is not a topological partition of the road network. Instead, it is a subgraph of the road network containing only highway information. Because of this, the highway partition is much larger than a local partition.
It is read into the cache at routing engine start up and remains resident.
The road network is partitioned in three phases. The first phase partitions the data, computing the number of partitions needed and which partitions contain which nodes and edges. The second phase converts these partitions into BLOBs and writes them to the database. The final phase rebuilds the routing engine network, partitions any user data, and writes the user data BLOBs to the database.
Routing engine data is versioned. During the third phase of partitioning the routing engine version is written to the SDO_ROUTER_DATA_VERSION table and becomes the data version for this data set. If the data set is exported for use in another routing engine schema, this new routing engine's version must be compatible with the data version of the data set.
Routing engine data is provided by data vendors in the Oracle Data Format (ODF) and is already partitioned. Generally, there is no need for a customer to repartition the data. However, there may be cases, such as when performance testing different partition sizes or merging data sets, where you may want to repartition the routing engine data.
Note:
Repartitioning routing engine data can be a very time and resource intensive operation. Depending on the hardware being used, repartitioning a large data set, such as North America or the European Union, can easily run for a day or more.
This section includes the following topics:
Syntax:
SDO_ROUTER_PARTITION.PARTION_ROUTER(
LOG_FILE_NAME IN VARCHAR2 := 'sdo_router_partition.log',
MAX_V_NO IN NUMBER DEFAULT 10000,
DRIVING_SIDE IN VARCHAR2 := 'R',
NETWORK_NAME IN VARCHAR := 'ROUTER_NETWORK',
MAX_MEMORY IN NUMBER := 1.75,
CLEANUP IN BOOLEAN DEFAULT TRUE,
USE_SECUREFILES IN BOOLEAN DEFAULT TRUE,
GENERATE_11G_RESTRICTIONS IN BOOLEAN DEFAULT TRUE);
The PARTITION_ROUTER procedure must be run from a routing engine schema that contains routing engine Oracle Data Format data. This procedure partitions the road network and creates the PARTITION table containing the routing engine data in BLOB format.
The LOG_FILE_NAME parameter specifies the name of the log file written during routing engine partitioning. This log file is created in the SDO_ROUTER_LOG_DIR directory. Users can choose a log file name or use the default partitioning log file sdo_router_partition.log.
The MAX_V_NO parameter specifies the maximum number of nodes allowed in a partition. There must be at least (MAX_V_NO+1) nodes in the NODE table.
The DRIVING_SIDE parameter is a legacy parameter. Its only use was to generate Release 11g turn restrictions. Valid values are R (right side) and L (left side).The NETWORK_NAME parameter specifies the name of the routing engine network that is created during partitioning.
The MAX_MEMORY parameter specifies the maximum Java heap size, in gigabytes, available to the partitioning process. The default value of 1.75G is enough for most data sets. This parameter only needs to be adjusted when partitioning data sets that are much smaller or much larger than normal.
The CLEANUP parameter is used for debugging. By default, all of the intermediate tables created during the partitioning of the routing engine data are cleaned up. If there is problem while partitioning, leaving these tables in place (specifying CLEANUP=>FALSE) can provide substantial debugging information.
The USE_SECUREFILES parameter lets you create the routing engine's BLOBs in either BASICFILE or SECUREFILE format. Oracle recommends using the SECUREFILE format.
The GENERATE_11G_RESTRICTIONS parameter controls the generation of Release 11g turn restriction data. In Oracle Database Release 11g, basic turn restrictions were implemented and stored in the PARTITION table. In Oracle Database Release 12c, turn restrictions are expanded and are stored in a user data table, ROUTER_TURN_RESTRICTION_DATA. To allow data providers to ship data partitioned under Release 12c to users still using a Release 11g Route Server, both types of turn restrictions are generated by default. When repartitioning data under Oracle Release 12c, for a Release 12c Route Server, you may set this parameter to FALSE.
Syntax:
SDO_ROUTER_PARTITION.CLEANUP_ROUTER(
ALL_TABLES IN BOOLEAN DEFAULT TRUE);
The CLEANUP_ROUTER procedure resets the routing engine's state, ensuring that all the tables and indexes are in good order and all intermediate tables are deleted. This is useful if partitioning fails or if partitioning completed successfully with the CLEANUP flag set to FALSE.
The ALL_TABLES parameter controls what is reset. When set to FALSE, the routing engine is reset to a stable state but leaves the intermediate tables for debugging. This can be useful if partitioning failed. When set to TRUE, the routing engine is reset to a stable state and all intermediate tables used in partitioning are deleted. This can be useful when cleaning up after a successful PARTITION_ROUTER Procedure that was run with the CLEANUP parameter set to FALSE.
Syntax:
DUMP_PARTITIONS(
LOG_FILE_NAME IN VARCHAR2 := 'sdo_router_partition.log',
START_PID IN NUMBER DEFAULT 0,
END_PID IN NUMBER DEFAULT -1,
VERBOSE IN BOOLEAN DEFAULT FALSE);
The DUMP_PARTITIONS procedure dumps the contents of routing engine data partition BLOBs. This procedure unpacks a BLOB, formats the data, and writes it to a log file. A single running of 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 is the name of the log file written when dumping routing engine 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 VERBOSE parameter controls what data is dumped. The default value of FALSE dumps a summary of the partition information, including, the number of node and edges and the size of the BLOB. If this parameter is TRUE, in addition to the summary, all the information describing all the nodes and edges in the partition is dumped.
Syntax:
VALIDATE_PARTITIONS(
LOG_FILE_NAME IN VARCHAR2 := 'sdo_router_partition.log',
START_PID IN NUMBER DEFAULT 0,
END_PID IN NUMBER DEFAULT -1,
VERBOSE IN BOOLEAN DEFAULT FALSE);
The VALIDATE_PARTITIONS procedure validates the contents of routing engine data partition BLOBs. Validating all the partitions in a large dataset can take some time to run, but it is the fastest way to read every byte in every partition to ensure that the partitions are ready to be used for routing. Validation only needs to be run if you suspect that there may be a problem with the partitions. If validation is run, Oracle recommends running the initial validation on all partitions with the VERBOSE flag set to FALSE. If a problem is found, then rerun the validation on the problem partitions with VERBOSE set to true.
The LOG_FILE_NAME parameter is the name of the log file written while validating the routing engine 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 validate. 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 validate. 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 validated. If END_PID is less than START_PID, an error message is written to the log.
The VERBOSE parameter controls the level of detail of the validation messages. The default value of FALSE simply logs whether a partition passed or failed validation. If this parameter is TRUE, the validation of each element in the BLOB is logged.
Syntax:
GET_VERSION(
LOG_FILE_NAME IN VARCHAR2 := 'sdo_router_partition.log');
The GET_VERSION procedure queries the SDO_ROUTER_DATA_VERSION table to get the routing engine data version and writes the result to the log file. (An an alternative, you can use SQL to query the SDO_ROUTER_DATA_VERSION table.)
The LOG_FILE_NAME parameter is the name of the log file where the routing engine data version is written. 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.
This section contains examples of the following:
Example E-1 shows partitioning of a small data set. The data set in this example 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. To partition the routing engine data, execute the statement from within the routing engine schema.
Example E-1 Partitioning a Small Data Set
EXECUTE SDO_ROUTER_PARTITION.PARTITION_ROUTER( 'sdo_router_partition.log', 1000, 'R', 'ROUTER_SF_NET', .75, FALSE, FALSE, FALSE); ******** Beginning SDO Router partitioning ** Schema: ROUTER_SF_SCHEMA ** Logfile ___location:/scratch/logs/sdo_router_partition.log ** Nodes per partition: 1000 ** Driving side: R ** Router network name: ROUTER_SF_NET ** Max JVM Memory Size: .75GB (805306368 bytes) ** Cleanup temporary files: FALSE ** BLOBs stored in BASICFILE format ** Generating 11g turn restrictions: FALSE [This header is followed by extensive logging of the partitioning process.]
This example produces 1025 partitions, 1 highway partition, and 1024 local partitions. There are, on average, 516 nodes per partition. The driving side is set but is not used because Release 11g turn restrictions were not requested. The Java maximum heap size was set to three quarters of a gigabyte, more than enough to partition such a small data set. The partition BLOBs were written in Basicfile format, and when the partitioning completed the intermediate tables were not cleaned up.
To clean up the intermediate tables left behind by partitioning, enter the following:
EXECUTE SDO_ROUTER_PARTITION.CLEANUP_ROUTER()
Example E-2 shows partitioning of a full data set. The data set for this example is the entire North American road network. This data set contains about 30 million nodes and 74 million edges. To partition the routing engine data, execute the statement from within the routing engine schema.
Example E-2 Partitioning a Full Data Set
EXECUTE SDO_ROUTER_PARTITION.PARTITION_ROUTER( 'sdo_router_partition.log, 32000, 'R', 'ROUTER_NA_NET'); ******** Beginning SDO Router partitioning ** Schema: ROUTER_NA_SCHEMA ** Logfile ___location:/scratch/logs/sdo_router_partition.log ** Nodes per partition: 32000 ** Driving side: R ** Router network name: ROUTER_NA_NET ** Max JVM Memory Size: 1.75GB (1879048192 bytes) ** Cleanup temporary files: TRUE ** BLOBs stored in SECUREFILE format ** Generating 11g turn restrictions: TRUE [This header is followed by extensive logging of the partitioning process.] ++ Partitioning a data set of this size is time and resource intensive ++
This example produces 1025 partitions, 1 highway partition, and 1024 local partitions. There are, on average, 29443 nodes per partition. The driving side is set to 'Right Side' and is used to generate the requested Oracle 11g turn restrictions. The default Java heap size of 1.75 gigabytes is used. All routing engine data and user data BLOBs are stored in SECUREFILE format, and all intermediate tables are cleaned up after the successful partitioning.
Example E-3 shows a dump of partitions 0 through 3 with the default VERBOSE value (FALSE) from the San Francisco data set. Note the BLOB size difference between the highway and local partitions. Also note that the highway partition is completely self-contained so there are no outbound edges. Local partitions have outgoing edges that connect them to other local partitions.
Example E-3 Dumping the Contents of a Partition (VERBOSE = FALSE)
EXEC SDO_ROUTER_PARTITION.DUMP_PARTITIONS( 'dump_part0-3.log', 0, 3); ******** Beginning partition dump ** Logfile ___location: /scratch/logs/dump_part0-3.log ** Routeserver data version: 12.1.0.2.1 ** Start partition id: 0 ** End partition id: 3 ** Verbose mode: FALSE [INFO] Starting dump of partition 0 Number of Nodes: 19392 Number of Nonboundary Edges: 22706 Number of Outgoing Boundary Edges: 0 Number of Incoming Boundary Edges: 0 Stored Partition ID: 0 Blob Length: 1748332 [INFO] Starting dump of partition 1 Number of Nodes: 516 Number of Nonboundary Edges: 1190 Number of Outgoing Boundary Edges: 49 Number of Incoming Boundary Edges: 49 Stored Partition ID: 1 Blob Length: 81372 [INFO] Starting dump of partition 2 Number of Nodes: 516 Number of Nonboundary Edges: 1099 Number of Outgoing Boundary Edges: 68 Number of Incoming Boundary Edges: 68 Stored Partition ID: 2 Blob Length: 78388 [INFO] Starting dump of partition 3 Number of Nodes: 516 Number of Nonboundary Edges: 1101 Number of Outgoing Boundary Edges: 60 Number of Incoming Boundary Edges: 60 Stored Partition ID: 3 Blob Length: 77756
Example E-4 Dumping the Contents of a Partition (VERBOSE = TRUE)
Example E-4 shows a dump of partition 8 with VERBOSE set to TRUE from the San Francisco data set. Note that the outbound edges log the partition ID where they terminate, and the inbound edges log the partition ID where they originate.
EXEC SDO_ROUTER_PARTITION.DUMP_PARTITIONS( 'dump_part8.log', 8, 8, TRUE); ******** Beginning partition dump ** Logfile ___location:/scratch/logs/dump_part8.log ** Routeserver data version: 12.1.0.2.1 ** Start partition id: 8 ** End partition id: 8 ** Verbose mode: TRUE [INFO] Starting dump of partition 8 Number of Nodes: 517 Number of Non-boundary Edges: 1145 Number of Outgoing Boundary Edges: 37 Number of Incoming Boundary Edges: 37 Stored Partition ID: 8 Blob Length: 77957 Node information for partition 8: Node ID/X/Y/Highway: 84096388/-120.50809/37.98399/false In Edges(3): -120862233, -120862227, 120862232 Out Edges(3): -120862232, 120862227, 120862233 ******************************* Node ID/X/Y/Highway: 84098023/-120.4882/37.99961/true In Edges(3): -127829801, -120428259, 776737023 Out Edges(3): -776737023, 120428259, 127829801 ******************************* *** Node information for the other 515 nodes... Non-boundary Edge information for partition 8: Internal Edges(1145): Edge ID/Start Node ID/End Node ID: 910681077/942981443/206194644 Length/Speed Limit/Function Class: 130.3/5/5 ******************************* Edge ID/Start Node ID/End Node ID: -105461005/206194651/206194644 Length/Speed Limit/Function Class: 229.93/11/5 ******************************* *** Edge information for the other 1143 internal edges... Outbound Boundary Edges(37): Edge ID/Start Node ID/End Node ID: -724019630/253265936/810705655 End Node Partition ID/Length: 7/511.07 Speed Limit/Function Class: 26/2 ******************************* Edge ID/Start Node ID/End Node ID: -105462459/252152310/206193109 End Node Partition ID/Length: 7/814.68 Speed Limit/Function Class: 11/5 ******************************* *** Edge information for the other 35 outbound boundary edges... Inbound Boundary Edges(37): Edge ID/Start Node ID/End Node ID: 724019630/810705655/253265936 Start Node Partition ID/Length: 7/511.07 Speed Limit/Function Class: 26/2 ******************************* Edge ID/Start Node ID/End Node ID: 105462459/206193109/252152310 Start Node Partition ID/Length: 7/814.68 Speed Limit/Function Class: 11/5 ******************************* *** Edge information for the other 35 inbound boundary edges...
Example E-5 shows validation of the contents of all the partitions in the data set with the default VERBOSE value (FALSE).
Example E-5 Validating the Contents of Partitions (VERBOSE = FALSE)
EXEC SDO_ROUTER_PARTITION.VALIDATE_PARTITIONS( 'validate_all_partitions.log'); ******** Beginning partition validation ** Logfile ___location:/scratch/logs/validate_all_partitions.log ** Routeserver data version: 12.1.0.2.1 ** Start partition id: 0 ** End partition id: 1024 ** Verbose mode: FALSE [INFO] Starting validation of partition 0 [INFO] Starting validation of partition 1 [INFO] Starting validation of partition 2 … [INFO] Starting validation of partition 1022 [INFO] Starting validation of partition 1023 [INFO] Starting validation of partition 1024 [INFO] Partition validation complete
Example E-6 Validating the Contents of Partitions (VERBOSE = TRUE)
Example E-6 shows validation of the contents of partitions 7 and 8 with VERBOSE set to TRUE.
EXEC SDO_ROUTER_PARTITION.VALIDATE_PARTITIONS( 'validate_part7-8.log', 7, 8, TRUE); ******** Beginning partition validation ** Logfile ___location: /scratch/logs/validate_part7-8.log ** Routeserver data version: 12.1.0.2.1 ** Start partition id: 7 ** End partition id: 8 ** Verbose mode: TRUE [INFO] Starting validation of partition 7 Header node count: OK Header edge count: OK BLOB partition id: OK BLOB length: OK BLOB node count: OK BLOB information for 516 nodes: OK BLOB information for 1154 internal edges: OK BLOB information for 66 outbound boundary edges: OK BLOB information for 65 inbound boundary edges: OK [INFO] Starting validation of partition 8 Header node count: OK Header edge count: OK BLOB partition id: OK BLOB length: OK BLOB node count: OK BLOB information for 517 nodes: OK BLOB information for 1145 internal edges: OK BLOB information for 37 outbound boundary edges: OK BLOB information for 37 inbound boundary edges: OK [INFO] Partition validation complete
Example E-7 queries the routing engine data version number, writing the result to a log file.
SELECT * FROM sdo_router_data_version;
Example E-7 Querying the Routing Data Version
EXEC SDO_ROUTER_PARTITION.GET_VERSION('version.log');
INFO: Routeserver data version: 12.1.0.2.1
Alternatively, you could use the following SQL query to get the routing engine data version: