Network Graphs

Kinetica provides support for graph creation and management in SQL. Graphs represent topological relationships (both geospatial and non-geospatial) via nodes that are connected by edges.

Graph features accessible via SQL include:

CREATE GRAPH

Creates a new graph. The nodes and edges of a graph are optionally weighted and/or restricted to aid in calculating various ways to traverse the graph. Graphs comprise a maximum of four components that each have unique specifications and ways they can be combined to define the graph. Review Components and Identifiers and Identifier Combinations for more information.

CREATE GRAPH Syntax



1
2
3
4
5
6
7
8


CREATE [OR REPLACE] [DIRECTED] GRAPH [<schema name>.]<graph name>
(
    EDGES => INPUT_TABLE(<select statement>),
    [NODES => INPUT_TABLE(<select statement>)],
    [WEIGHTS => INPUT_TABLE(<select statement>)],
    [RESTRICTIONS => INPUT_TABLE(<select statement>)],
    [OPTIONS => <KV_PAIRS>('<option key>' = '<option value>'[,...])]
)

Parameters Description

OR REPLACE Any existing graph with the same name will be dropped before creating this one

DIRECTED Optional keyword used to create the graph as directed

<schema name> Name of the schema that will contain the created graph; if no schema is specified, the graph will be created in the calling user's default schema

<graph name> Name of the graph, which can be referenced in subsequent commands

EDGES Graph component, provided as table column names, expressions, or constants using the SQL INPUT TABLE function, to use for identifying the edges of the graph; review Components and Identifiers and Identifier Combinations for more information

NODES Optional graph component, provided as column names, expressions, or constants using the SQL INPUT TABLE function, to use for identifying the nodes of the graph; review Components and Identifiers and Identifier Combinations for more information

WEIGHTS Optional graph component, provided as column names, expressions, or constants using the SQL INPUT TABLE function, to use for identifying the weights of the graph; review Components and Identifiers and Identifier Combinations for more information

RESTRICTIONS Optional graph component, provided as column names, expressions, or constants using the SQL INPUT TABLE function, to use for identifying the restrictions of the graph; review Components and Identifiers and Identifier Combinations for more information

OPTIONS

Optional indicator that a list of connection option/value assignments will follow, passed as a comma-delimited list of key/value pairs to the KV_PAIRS function

Option	Description
`restriction_threshold_value`	Value-based restriction comparison. Any node or edge with a `VALUECOMPARED` value greater than the specified value will not be included in the graph.
`merge_threshold`	If node geospatial positions are input (e.g., `POINT(X Y)`), determines the minimum separation allowed between unique nodes. If nodes are within the tolerance of each other, they will be merged as a single node. The default value is `1.0E-4`.
`min_x`	Minimum x (longitude) value for spatial graph associations. The default value is `-180.0`.
`max_x`	Maximum x (longitude) value for spatial graph associations. The default value is `180.0`.
`min_y`	Minimum y (latitude) value for spatial graph associations. The default value is `-90.0`.
`max_y`	Maximum y (latitude) value for spatial graph associations. The default value is `90.0`.
`recreate`	If set to true and the graph already exists, the graph is deleted and recreated. The default value is false.
`modify`	If set to true, `recreate` is set to true, and the graph already exists, the graph is updated with the given components. The default value is false.
`export_create_results`	If set to true, returns the graph topology in the response as arrays. The default value is false.
`enable_graph_draw`	If set to true, adds an `EDGE_WKTLINE` column identifier to the specified `graph_table` so the graph can be viewed via WMS; for social and non-geospatial graphs, the `EDGE_WKTLINE` column identifier will be populated with spatial coordinates derived from a flattening layout algorithm so the graph can still be viewed. The default value is false.
`save_persist`	If set to true, the graph will be saved in the persist directory (see the config reference for more information). If set to false, the graph will be removed when the graph server is shutdown. The default value is false.
`sync_db`	If set to true and `save_persist` is true, the graph will be fully reconstructed upon a database restart and be updated to align with any source table(s) updates made since the creation of the graph. If dynamic graph updates upon table inserts are desired, use `add_table_monitor` instead. The default value is false.
`add_table_monitor`	Adds a table monitor to every table used in the creation of the graph; this table monitor will trigger the graph to update dynamically upon inserts to the source table(s). Note that upon database restart, if `save_persist` is also set to true, the graph will be fully reconstructed and the table monitors will be reattached. For more details on table monitors, see Table Monitors. The default value is false.
`graph_table`	If specified, the created graph is also created as a table with the given name, in [schema_name.]table_name format, using standard name resolution rules and meeting table naming criteria. The table will have the following identifier columns: `EDGE_ID`, `EDGE_NODE1_ID`, `EDGE_NODE2_ID`. If left blank, no table is created. The default value is blank.
`remove_label_only`	When `RESTRICTIONS` is specified, if set to true this will NOT delete the entity but only the label associated with the entity. Otherwise (default), it'll delete the label AND the entity. The default value is false.
`add_turns`	Adds dummy "pillowed" edges around intersection nodes where there are more than three edges so that additional weight penalties can be imposed by the solve endpoints (increases the total number of edges). The default value is false.
`turn_angle`	Value in degrees modifies the thresholds for attributing right, left, sharp turns, and sections. It is the vertical deviation angle from the incoming edge to the intersection node. The larger the value, the larger the threshold for sharp turns and intersections; the smaller the value, the larger the threshold for right and left turns; `0` < `turn_angle` > `90`. The default value is `60`.
`server_id`	Indicates which graph server(s) to send the request to. Default is to send to the server with the most available memory.
`use_rtree`	Use a range tree structure to accelerate and improve the accuracy of snapping, especially to edges.

To create a graph featuring edges and weights:

CREATE GRAPH with Edges Example



 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


CREATE GRAPH sample_graph (
  EDGES => INPUT_TABLE(
    SELECT 
      id AS ID, 
      wktline AS WKTLINE 
    FROM example_geospatial.sample_map
  ),
  WEIGHTS => INPUT_TABLE(
    SELECT 
      id AS EDGE_ID, 
      cost AS VALUESPECIFIED 
    FROM example_geospatial.sample_map
  ),
  OPTIONS => KV_PAIRS(
    'enable_graph_draw' = 'true', 
    'recreate' = 'true', 
    'graph_table' = 'example_geospatial.sample_graph_table'
  )
)

To create a graph featuring nodes, edges, and weights:

CREATE GRAPH with Nodes & Edges Example



 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


CREATE GRAPH big_cities_graph (
  NODES => INPUT_TABLE(
    SELECT
      city_location AS WKTPOINT 
    FROM example_geospatial.big_cities
  ),
  EDGES => INPUT_TABLE(
    SELECT 
      city1_location AS NODE1_WKTPOINT, 
      city2_location AS NODE2_WKTPOINT 
    FROM example_geospatial.big_cities_map
  ),
  WEIGHTS => INPUT_TABLE(
    SELECT
      (REMOVE_NULLABLE(ST_MAKELINE(city1_location, city2_location))) AS EDGE_WKTLINE,
      trip_time AS VALUESPECIFIED
    FROM example_geospatial.big_cities_map
  ),
  OPTIONS => KV_PAIRS(
    'enable_graph_draw' = 'true', 
    'recreate' = 'true', 
    'graph_table' = 'example_geospatial.big_cities_graph_table'
  )
)

SOLVE_GRAPH

Solves an existing graph using one of the supported solver types. The SOLVE GRAPH function can be called either within a SELECT statement as a table function or within an EXECUTE FUNCTION call.

SOLVE_GRAPH Table Function Syntax



 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


SELECT * FROM TABLE (
    SOLVE_GRAPH
    (
        GRAPH => '[<schema name>.]<graph name>',
        SOLVER_TYPE => '<solver type>',
        SOURCE_NODES => INPUT_TABLE(<select statement>),
        [DESTINATION_NODES => INPUT_TABLE(<select statement>)],
        [WEIGHTS_ON_EDGES => INPUT_TABLE(<select statement>)],
        [RESTRICTIONS => INPUT_TABLE(<select statement>)],
        [OPTIONS => <KV_PAIRS>('<option name>' = '<option value>'[,...])]
    )
)

SOLVE_GRAPH EXECUTE FUNCTION Syntax



 1
 2
 3
 4
 5
 6
 7
 8
 9
10


EXECUTE FUNCTION SOLVE_GRAPH(
    GRAPH => '[<schema name>.]<graph name>',
    SOLVER_TYPE => '<solver type>',
    SOURCE_NODES => INPUT_TABLE(<select statement>),
    SOLUTION_TABLE => '[<schema name>.]<table name>',
    [DESTINATION_NODES => INPUT_TABLE(<select statement>),]
    [WEIGHTS_ON_EDGES => INPUT_TABLE(<select statement>),]
    [RESTRICTIONS => INPUT_TABLE(<select statement>),]
    [OPTIONS => <KV_PAIRS>('<option name>' = '<option value>'[,...])
)

Parameters Description

GRAPH Name of the graph to solve

SOLVER_TYPE

The type of solver to use for the operation.

Solver	Description	CPU Parallel
`ALLPATHS`	Determines all reasonable paths between a source and destination pair.	X
`BACKHAUL_ROUTING`	Determines the optimal routes between remote asset nodes and fixed asset nodes.	X
`CENTRALITY`	Calculates the degree of a node to depict how many pairs of individuals that would have to go through the node to reach one another in the minimum number of hops. Also known as betweenness.	X
`CLOSENESS`	Calculates the centrality closeness score per node as the sum of the inverse shortest path costs to all nodes in the graph.	X
`INVERSE_SHORTEST_PATH`	Determines the shortest path downstream using multiple technician routing.	X
`MULTIPLE_ROUTING`	Calculates the shortest possible route between the nodes and returns to the origin node -- also known as the traveling salesman.	X
`PAGE_RANK`	Calculates how connected the nodes are and determines which nodes are the most important. Weights are not required.	X
`PROBABILITY_RANK`	Calculates the probability of a node being connected to another node using hidden Markov chains.	X
`SHORTEST_PATH`	Determines the shortest path upstream between given source(s) and destination(s).	X
`STATS_ALL`	Calculates graph statistics such as graph diameter, longest pairs, vertex valences, topology numbers, average and max cluster sizes, etc.	X

SOURCE_NODES The node(s) used as the origin point(s) for the solution specified using the SQL INPUT TABLE function

SOLUTION_TABLE Only applicable when using EXECUTE FUNCTION syntax. Name of the table to store the solution in [schema_name.]table_name format, using standard name resolution rules and meeting table naming criteria

DESTINATION_NODES The node(s) used as the destination point(s) for the solution specified using the SQL INPUT TABLE function

WEIGHTS_ON_EDGES Additional weights to apply to the edges of an existing graph specified using the SQL INPUT TABLE function; review Components and Identifiers and Identifier Combinations for more information

RESTRICTIONS Additional restrictions to apply to the nodes/edges of an existing graph specified using the SQL INPUT TABLE function; review Components and Identifiers and Identifier Combinations for more information

OPTIONS

Optional indicator that a comma-delimited list of connection option/value assignments will follow.

Option	Description
`max_solution_radius`	For `SHORTEST_PATH` and `INVERSE_SHORTEST_PATH` solvers only. Sets the maximum solution cost radius, which ignores the `DESTINATION_NODES` list and instead outputs the nodes within the radius sorted by ascending cost. If set to `0.0` (the default), the setting is ignored
`min_solution_radius`	For `SHORTEST_PATH` and `INVERSE_SHORTEST_PATH` solvers only. Applicable only when `max_solution_radius` is set. Sets the minimum solution cost radius, which ignores the `DESTINATION_NODES` list and instead outputs the nodes within the radius sorted by ascending cost. If set to `0.0` (the default), the setting is ignored
`max_solution_targets`	For `SHORTEST_PATH` and `INVERSE_SHORTEST_PATH` solvers only. Sets the maximum number of solution targets, which ignores the `DESTINATION_NODES` list and instead outputs no more than n number of nodes sorted by ascending cost where n is equal to the setting value. If set to `0` (the default), the setting is ignored
`export_solve_results`	Returns solution results inside the `result_per_destination_node` array in the response if set to `true`. The default is `false`.
`remove_previous_restrictions`	Ignore the restrictions applied to the graph during the creation stage and only use the restrictions specified in this request if set to `true`. The default value is `false`.
`restriction_threshold_value`	Value-based restriction comparison. Any node or edge with a `VALUECOMPARED` value greater than the specified value will not be included in the solution.
`uniform_weights`	When specified, assigns the given value to all the edges in the graph. Note that weights provided using `weights_on_edges` will override this value.
`left_turn_penalty`	This will add an additional weight over the edges labelled as `left_turn` if the `add_turn` option was invoked during graph creation. The default value is `0.0`.
`right_turn_penalty`	This will add an additional weight over the edges labelled as `right_turn` if the `add_turn` option was invoked during graph creation. The default value is `0.0`.
`intersection_penalty`	This will add an additional weight over the edges labelled as `intersection` if the `add_turn` option was invoked during graph creation. The default value is `0.0`.
`sharp_turn_penalty`	This will add an additional weight over the edges labelled as `sharp_turn` or `u_turn` if the `add_turn` option was invoked during graph creation. The default value is `0.0`.
`num_best_paths`	For `MULTIPLE_ROUTING` solver only. Sets the number of shortest paths computed from each node. This is the heuristic criterion. If set to `0` (the default), the number will be determined automatically by the solver. Users may want to override this parameter to speed up the solver.
`max_num_combinations`	For `MULTIPLE_ROUTING` solver only. Sets the cap on the combinatorial sequence generated. If the default value (`2000000`) is overridden, it potentially speed up the solver.
`accurate_snaps`	Valid for single source destination pair solves if points are described as `WKPOINT` identifiers. When set to `true` (default), the solver will snap to the nearest node of the defined graph; otherwise, the solver will search for the closest entity that could be part of an edge in the defined graph. For the latter case (`false`), the solver modifies the resulting cost with the weights proportional to the ratio of the snap location within the edge. If the value is `false`, performance may be adversely affected, though the accuracy of the calculation may only improve by 1%.
`output_edge_path`	If set to `true`, concatenated edge IDs will be added as an `EDGE_PATH` column to the solution table for each source and target pair in the `SHORTEST_PATH` solves. The default value is `false`
`output_wkt_path`	If set to `true`, WKT line segments will be added as a `WKTROUTE` column to the solution table for each source and target pair in `SHORTEST_PATH` solves. The default value is `true`.
`server_id`	Indicates which graph server(s) to send the request to. Default is to send to the server, amongst those containing the corresponding graph, that has the most computational bandwidth. For `SHORTEST_PATH` solver, the input is split among the server containing the corresponding graph.
`convergence_limit`	For `PAGE_RANK` solver only; maximum percent relative threshold on the pagerank scores of each node between consecutive iterations to satisfy convergence. Default value is 1%.
`max_iterations`	For `PAGE_RANK` solver only; maximum number of pagerank iterations for satisfying convergence. Default value is 100.
`max_runs`	For `CENTRALITY` solver only; sets the maximum number of shortest path runs; maximum possible value is the number of nodes in the graph. Default value of 0 enables this value to be auto computed by the solver.
`output_clusters`	For `STATS_ALL` solver only; the cluster index for each node will be inserted as an additional column in the output.

To solve a graph using the SHORTEST_PATH solver and the table function syntax:

SOLVE_GRAPH Table Function Example



 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


SELECT * FROM TABLE(
  SOLVE_GRAPH(
    GRAPH => 'sample_graph',
    SOLVER_TYPE => 'SHORTEST_PATH',
    SOURCE_NODES => INPUT_TABLE(SELECT ST_GEOMFROMTEXT('POINT(0 0)') AS WKTPOINT),
    DESTINATION_NODES => INPUT_TABLE(SELECT ST_GEOMFROMTEXT('POINT(-5 -5)') AS WKTPOINT),
    OPTIONS => KV_PAIRS(
      'export_solve_results' = 'true',
      'output_edge_path' = 'true'
    )
  )
)

To solve a graph using the SHORTEST_PATH solver and the EXECUTE FUNCTION syntax (note the additional SOLUTION_TABLE parameter):

SOLVE_GRAPH EXECUTE FUNCTION Example



 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


EXECUTE FUNCTION SOLVE_GRAPH(
  GRAPH => 'sample_graph',
  SOLVER_TYPE => 'SHORTEST_PATH',
  SOURCE_NODES => INPUT_TABLE(SELECT ST_GEOMFROMTEXT('POINT(0 0)') AS WKTPOINT),
  DESTINATION_NODES => INPUT_TABLE(SELECT ST_GEOMFROMTEXT('POINT(-5 -5)') AS WKTPOINT),
  SOLUTION_TABLE => 'sample_graph_solved_shortest_path',
  OPTIONS => KV_PAIRS(
    'export_solve_results' = 'true',
    'output_edge_path' = 'true'
  )
)

QUERY_GRAPH

Queries an existing graph using unique query identifiers and combinations. The QUERY_GRAPH function can be called either within a SELECT statement as a table function or within an EXECUTE FUNCTION call.

QUERY_GRAPH Table Function Syntax



 1
 2
 3
 4
 5
 6
 7
 8
 9
10


SELECT * FROM TABLE(
    QUERY_GRAPH
    (
        GRAPH => '[<schema name>.]<graph name>',
        QUERIES => INPUT_TABLE(<select statement>),
        RINGS => <integer>,
        [RESTRICTIONS => INPUT_TABLE(<select statement>),]
        [OPTIONS => <KV_PAIRS>('<option name>' = '<option value>'[,...])]
    )
)

QUERY_GRAPH EXECUTE FUNCTION Syntax



1
2
3
4
5
6
7
8


EXECUTE FUNCTION QUERY_GRAPH(
    GRAPH => '[<graph schema name>.]<graph name>',
    QUERIES => INPUT_TABLE(<select statement>),
    ADJACENCY_TABLE => '[<table schema name>.]<table name>',
    RINGS => <integer>,
    [RESTRICTIONS => INPUT_TABLE(<select statement>),]
    [OPTIONS => <KV_PAIRS>('<option name>' = '<option value>'[,...])]
)

Parameters Description

GRAPH Name of the graph to query

QUERIES Nodes or edges to be queried specified using the SQL INPUT TABLE function; review Query Identifiers and Query Identifier Combinations for more information

ADJACENCY_TABLE Only applicable when using EXECUTE FUNCTION syntax. Name of the table to store the resulting adjacencies in [schema_name.]table_name format, using standard name resolution rules and meeting table naming criteria

RINGS Sets the number of rings around the node to query for adjacency

OPTIONS

Optional indicator that a comma-delimited list of connection option/value assignments will follow.

Option	Description
`force_undirected`	If set to `true`, all inbound and outbound edges relative to the node will be returned. If set to `false`, only outbound edges relative to the node will be returned. This parameter is only applicable if the graph is directed and when querying nodes. Consult Directed Graphs for more details. The default is `false`.
`limit`	When specified, limits the number of query results. Note that if `target_nodes_table` is provided, the size of the corresponding table will be limited by this value.
`target_nodes_table`	Name of the table to store the list of the final nodes reached during traversal, in [schema_name.]table_name format, using standard name resolution rules and meeting table naming criteria. If this value is left as the default, the table name will default to the provided `ADJACENCY_TABLE` value, if specified, plus a `_nodes` suffix, e.g., `<ADJACENCY_TABLE value>_nodes`. The default value is ''.
`restriction_threshold_value`	Value-based restriction comparison. Any node or edge with a `VALUECOMPARED` value greater than the specified value will not be included in the solution.
`export_query_results`	Returns query results in the response. If set to `true`, the output adjacency integer, string, or WKT array (depending on what was queried for) will be populated with the results. If set to `false`, none of the arrays will be populated. The default value is `false`.
`enable_graph_draw`	If set to true, adds a `QUERY_EDGE_WKTLINE` column identifier to the specified `ADJACENCY_TABLE` so the solution can be viewed via WMS; for social and non-geospatial solutions, the `QUERY_EDGE_WKTLINE` column identifier will be populated with spatial coordinates derived from a flattening layout algorithm so the solution can still be viewed. The default value is false.
`and_labels`	If set to `true`, the result of the query has entities that satisfy all of the target labels instead of any of the labels. The default value is `false`.
`server_id`	Indicates which graph server(s) to send the request to. Default is to send to the server, amongst those containing the corresponding graph, that has the most computational bandwidth.

To query a graph node within one ring using the table function syntax:

QUERY_GRAPH Table Function Example



 1
 2
 3
 4
 5
 6
 7
 8
 9
10


SELECT * FROM TABLE(
  QUERY_GRAPH(
    GRAPH => 'sample_graph',
    QUERIES => INPUT_TABLE(SELECT ST_GEOMFROMTEXT('POINT(0 0)') AS NODE_WKTPOINT),
    RINGS => 1,
    OPTIONS => KV_PAIRS(
      'enable_graph_draw' = 'true'
    )
  )
)

To query a different graph node within two rings using the execute function syntax (note the additional required ADJACENCY_TABLE parameter):

QUERY_GRAPH EXECUTE FUNCTION Example



 1
 2
 3
 4
 5
 6
 7
 8
 9
10


EXECUTE FUNCTION QUERY_GRAPH(
  GRAPH => 'sample_graph',
  QUERIES => INPUT_TABLE(SELECT ST_GEOMFROMTEXT('POINT(5 5)') AS NODE_WKTPOINT),
  RINGS => 2,
  ADJACENCY_TABLE => 'sample_graph_node_query2',
  OPTIONS => KV_PAIRS(
    'export_query_results' = 'true',
    'enable_graph_draw' = 'true'
  )
)

MATCH_GRAPH

Matches an existing graph to a dataset using one of the supported solver types and sample points which are defined using unique match identifiers and combinations. The MATCH_GRAPH function can be called either within a SELECT statement as a table function or within an EXECUTE FUNCTION call.

MATCH_GRAPH Table Function Syntax



1
2
3
4
5
6
7
8
9


SELECT * FROM TABLE(
    MATCH_GRAPH
    (
        GRAPH => '[<schema name>.]<graph name>',
        SAMPLE_POINTS => INPUT_TABLE(<select statement>),
        SOLVE_METHOD => '<solver type>',
        [OPTIONS => <KV_PAIRS>('<option name>' = '<option value>'[,...])]
    )
)

MATCH_GRAPH EXECUTE FUNCTION Syntax



1
2
3
4
5
6
7


EXECUTE FUNCTION MATCH_GRAPH(
    GRAPH => '[<graph schema name>.]<graph name>',
    SAMPLE_POINTS => INPUT_TABLE(<select statement>),
    SOLVE_METHOD => '<solver type>',
    SOLUTION_TABLE => '[<table schema name>.]<table name>',
    [OPTIONS => <KV_PAIRS>('<option name>' = '<option value>'[,...])]
)

Parameters Description

GRAPH Name of the graph to match

SAMPLE_POINTS Sample points used to match an underlying geospatial graph specified using the SQL INPUT TABLE function. Sample points are specified as identifiers, which are grouped into combinations.

SOLVE_METHOD

The type of solve method to use for the operation; review Match Identifier Combinations for more information.

Solver	Description	CPU Parallel
`MARKOV_CHAIN`	Matches sample points to the graph using the Hidden Markov Model (HMM)-based method, which conducts a range-tree closest-edge search to find the best combinations of possible road segments for each sample point to create the best route. The route is secured one point at a time, so the prediction is corrected after each point. This solution type is the most accurate, but also the most computationally intensive.	X
`MATCH_BATCH_SOLVES`	Matches each provided sample source and destination pair using the shortest path between the points.	X
`MATCH_LOOPS`	Matches closed loops (Eulerian paths) originating and ending at each graph node between min and max hops (levels).	X
`MATCH_OD_PAIRS`	Matches sample points to find the most probable path between origin and destination (OD) pairs with given cost constraints.	X
`MATCH_SUPPLY_DEMAND`	Matches sample generic supply depots to generic demand points using abstract transportation (referred to as trucks). Each route is determined by a truck's ability (size) to service demand at each demand point.	X

OPTIONS

Optional indicator that a comma-delimited list of connection option/value assignments will follow.

Option	Description
`gps_noise`	GPS noise value (in meters) to remove redundant sample points. Use `-1` to disable noise reduction. The default value (`5.0`) accounts for 95% of point variation (±5 meters)
`num_segments`	Maximum number of potentially matching road segments for each sample point. The default is `3`.
`search_radius`	Maximum search radius used when snapping sample points onto potentially matching surrounding segments. The default value (`0.001`) corresponds to approximately 100 meters.
`chain_width`	For the `MARKOV_CHAIN` solver only. Length of the sample points lookahead window within the Markov kernel; the larger the number, the more accurate the solution. The default value is `9`.
`source`	Optional WKT starting point from `SAMPLE_POINTS` for the solver. The default behavior for the endpoint is to use time to determine the starting point. The default value is `POINT NULL`.
`destination`	Optional WKT ending point from `SAMPLE_POINTS` for the solver. The default behavior for the endpoint is to use time to determine the destination point. The default value is `POINT NULL`.
`partial_loading`	For the `MATCH_SUPPLY_DEMAND` solver only. When `false` (non-default), trucks do not off-load at the demand (store) side if the remainder is less than the store's need.
`max_combinations`	For the `MATCH_SUPPLY_DEMAND` solver only. This is the cutoff for the number of generated combinations for sequencing the demand locations. The maximum number of combinations is `2000000`. The default value is `10000`.
`left_turn_penalty`	This will add an additional weight over the edges labeled as `left_turn` if the `add_turn` option was invoked during graph creation. The default value is `0.0`.
`right_turn_penalty`	This will add an additional weight over the edges labeled as `right_turn` if the `add_turn` option was invoked during graph creation. The default value is `0.0`.
`intersection_penalty`	This will add an additional weight over the edges labeled as `intersection` if the `add_turn` option was invoked during graph creation. The default value is `0.0`.
`sharp_turn_penalty`	This will add an additional weight over the edges labeled as `sharp_turn` or `u_turn` if the `add_turn` option was invoked during graph creation. The default value is `0.0`.
`aggregated_output`	For the `MATCH_SUPPLY_DEMAND` solver only. When set to `true` (default), each record in the output table shows a particular truck's scheduled cumulative round trip path (MULTILINESTRING) and the corresponding aggregated cost. Otherwise, each record shows a single scheduled truck route (LINESTRING) towards a particular demand location (store ID) with its corresponding cost.
`output_tracks`	For the `MATCH_SUPPLY_DEMAND` solver only. When it is `true` (non-default), the output will be in tracks format for all the round trips of each truck in which the timestamps are populated directly from the edge weights starting from their originating depots.
`max_trip_cost`	For the `MATCH_SUPPLY_DEMAND` solver only. If this constraint is greater than `0` (default), then the trucks will skip traveling from one demand location to another if the cost between them is greater than this number (distance or time). The default value means no check is performed.
`filter_folding_paths`	For the `MARKOV_CHAIN` solver only. When set to `true` (non-default), the paths per sequence combination is checked for folding over patterns and can significantly increase the execution time depending on the chain width and the number of GPS samples.
`unit_unloading_cost`	For the `MATCH_SUPPLY_DEMAND` solver only. The unit cost per load amount to be delivered. If this value is greater than `0` (default) then the additional cost of this unit load multiplied by the total dropped load will be added over to the trip cost to the demand location
`max_num_threads`	For the `MARKOV_CHAIN` solver only. If specified value is greater than `0` (default), the maximum number of threads will not be greater than the specified value. It can be lower due to the memory and number of cores available. The default value allows the algorithm to set the optimal number of threads within these constraints.
`truck_service_limit`	For the `MATCH_SUPPLY_DEMAND` solver only. If specified, any truck's total service cost (distance or time) will be limited by the specified value including multiple rounds of drop-off (if set). The default value is `0.0`.
`enable_truck_reuse`	For the `MATCH_SUPPLY_DEMAND` solver only. If set to `true` (non-default) all trucks can be scheduled for additional rounds of supply drop-off from their originating depots.
`max_truck_stops`	For the `MATCH_SUPPLY_DEMAND` solver only. If specified (greater than zero), a truck can at most have this many stops (demand locations) in one round trip. Otherwise, it is unlimited. If `enable_truck_reuse` is on, this condition will be applied separately at each round trip use of the same truck.
`server_id`	Indicates which graph server(s) to send the request to. Default is to send to the server, among those containing the corresponding graph, that has the most computational bandwidth.
`inverse_solve`	For the `MATCH_BATCH_SOLVES` solver only. Solves source-destination pairs using inverse shortest path solver.
`min_loop_level`	For the `MATCH_LOOPS` solver only. Finds closed loops around each node deducible not less than this minimal hop (level) deep.
`max_loop_level`	For the `MATCH_LOOPS` solver only. Finds closed loops around each node deducible not more than this maximal hop (level) deep.
`search_limit`	For the `MATCH_LOOPS` solver only. Searches within this limit of nodes per vertex to detect loops. The value zero means there is no limit.
`output_batch_size`	For the `MATCH_LOOPS` solver only. Uses this value as the batch size of the number of loops in flushing (inserting) to the output table.

To match a graph to its parent dataset using the table function syntax:

MATCH_GRAPH Table Function Example



 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


SELECT * FROM TABLE(
  MATCH_GRAPH(
    GRAPH => 'big_cities_graph',
    SAMPLE_POINTS => INPUT_TABLE(
      SELECT
        city1_location AS ORIGIN_WKTPOINT,
        city2_location AS DESTINATION_WKTPOINT,
        trip_time AS OD_TIME
      FROM example_geospatial.big_cities_map
    ),
    SOLVE_METHOD => 'match_od_pairs'
  )
)

To match the same graph to its parent set instead using the EXECUTE FUNCTION syntax (note the additional required SOLUTION_TABLE parameter):

MATCH_GRAPH EXECUTE FUNCTION Example



 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


EXECUTE FUNCTION MATCH_GRAPH(
  GRAPH => 'big_cities_graph',
  SAMPLE_POINTS => INPUT_TABLE(
    SELECT
      city1_location AS ORIGIN_WKTPOINT,
      city2_location AS DESTINATION_WKTPOINT,
      trip_time AS OD_TIME
    FROM example_geospatial.big_cities_map
  ),
  SOLVE_METHOD => 'match_od_pairs',
  SOLUTION_TABLE => 'big_cities_graph_matched'
)

ALTER GRAPH

Alters an existing graph.

ALTER GRAPH Syntax



1
2
3
4
5
6
7
8


ALTER GRAPH [<schema name>.]<graph name> MODIFY
(
    [EDGES => INPUT_TABLE(<select statement>),]
    [NODES => INPUT_TABLE(<select statement>),]
    [WEIGHTS => INPUT_TABLE(<select statement>),]
    [RESTRICTIONS => INPUT_TABLE(<select statement>),]
    [OPTIONS => <KV_PAIRS>('<option key>' = '<option value>'[,...])]
)

Parameters Description

<schema name> Name of the schema containing the graph to alter

<graph name> Name of the graph to alter

EDGES Graph component, provided as column names, expressions, or constants using the SQL INPUT TABLE function, to use for identifying the edges of the graph; review Components and Identifiers and Identifier Combinations for more information

NODES Graph component, provided as column names, expressions, or constants using the SQL INPUT TABLE function, to use for identifying the nodes of the graph; review Components and Identifiers and Identifier Combinations for more information

WEIGHTS Graph component, provided as column names, expressions, or constants using the SQL INPUT TABLE function, to use for identifying the weights of the graph; review Components and Identifiers and Identifier Combinations for more information

RESTRICTIONS Graph component, provided as column names, expressions, or constants using the SQL INPUT TABLE function, to use for identifying the restrictions of the graph; review Components and Identifiers and Identifier Combinations for more information

OPTIONS

Indicator that a list of connection option/value assignments will follow, passed as a comma-delimited list of key/value pairs to the KV_PAIRS function

Option	Description
`restriction_threshold_value`	Value-based restriction comparison. Any node or edge with a `VALUECOMPARED` value greater than the specified value will not be included in the graph.
`export_create_results`	If set to true, returns the graph topology in the response as arrays. The default value is false.
`enable_graph_draw`	If set to true, adds an 'EDGE_WKTLINE' column identifier to the specified `graph_table` so the graph can be viewed via WMS; for social and non-geospatial graphs, the `EDGE_WKTLINE` column identifier will be populated with spatial coordinates derived from a flattening layout algorithm so the graph can still be viewed. The default value is false.
`save_persist`	If set to true, the graph will be saved in the persist directory (see the config reference for more information). If set to false, the graph will be removed when the graph server is shutdown. The default value is false.
`add_table_monitor`	Adds a table monitor to every table used in the creation of the graph; this table monitor will trigger the graph to update dynamically upon inserts to the source table(s). Note that upon database restart, if `save_persist` is also set to true, the graph will be fully reconstructed and the table monitors will be reattached. For more details on table monitors, see Table Monitors. The default value is false.
`graph_table`	If specified, the created graph is also created as a table with the given name, in [schema_name.]table_name format, using standard name resolution rules and meeting table naming criteria. The table will have the following identifier columns: `EDGE_ID`, `EDGE_NODE1_ID`, `EDGE_NODE2_ID`. If left blank, no table is created. The default value is ''.
`remove_label_only`	When `RESTRICTIONS` is specified, if set to true this will NOT delete the entity but only the label associated with the entity. Otherwise (default), it'll delete the label AND the entity. The default value is false.
`add_turns`	Adds dummy "pillowed" edges around intersection nodes where there are more than three edges so that additional weight penalties can be imposed by the solve endpoints (increases the total number of edges). The default value is false.
`turn_angle`	Value in degrees modifies the thresholds for attributing right, left, sharp turns, and sections. It is the vertical deviation angle from the incoming edge to the intersection node. The larger the value, the larger the threshold for sharp turns and intersections; the smaller the value, the larger the threshold for right and left turns; `0` < `turn_angle` > `90`. The default value is `60`.

To alter the weights of a graph and allow it to survive a database restart:

ALTER GRAPH Example



 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


ALTER GRAPH big_cities_graph MODIFY (
  WEIGHTS => INPUT_TABLE(
    SELECT
      REMOVE_NULLABLE(ST_MAKELINE(city1_location, city2_location)) AS EDGE_WKTLINE,
      REMOVE_NULLABLE(ST_DISTANCE(city1_location, city2_location)) AS VALUESPECIFIED
    FROM example_geospatial.big_cities_map
  ),
  OPTIONS => KV_PAIRS(
    'save_persist' = 'true'
  )
)

DROP GRAPH

Removes an existing graph.

DROP GRAPH Syntax

1

DROP GRAPH [<schema name>.]<graph name>

Parameters	Description
`<schema name>`	Name of the schema containing the graph to remove
`<graph name>`	Name of the existing graph to drop.

To drop a graph, big_cities_graph:

DROP GRAPH Example

1

DROP GRAPH big_cities_graph

SHOW GRAPH

Outputs the request used to create one or more existing graphs.

SHOW GRAPH Syntax

1

SHOW GRAPH < [<schema name>.]<graph name> | <schema name> | * >

Listing options:

[<schema name>.]<graph name> - output the DDL statement of the given graph
<schema name>.* - output the DDL statements of all graphs under the given schema
* - output the DDL statements of all graphs

Parameters	Description
`<schema name>`	Name of the schema containing the graph(s) to show
`<graph name>`	Name of the existing graph for which the creation request will be output

Note

The response to SHOW GRAPH is a single-column result set with the creation request in the DDL column. The request shown will depend on the way in which the graph was created (SQL vs. API/REST):

SQL - output will be the SQL DDL statement used to create the graph
API/REST - output will be the JSON request, wrapped by the API or sent directly via REST, used to create the graph

For example, to output the creation request for a graph, big_cities_graph:

SHOW GRAPH Example

1

SHOW GRAPH big_cities_graph

DESCRIBE GRAPH

Outputs the configuration of one or more existing graphs.

DESCRIBE GRAPH Syntax

1

DESC[RIBE] GRAPH < [<schema name>.]<graph name> | <schema name> | * >

Listing options:

[<schema name>.]<stream name> - output the configuration of the given graph
<schema name>.* - output the configuration of all graphs under the given schema
* - output the configuration of all graphs

Parameters	Description
`<schema name>`	Name of the schema containing the graph(s) to describe
`<graph name>`	Name of the existing graph for which the configuration will be output

Note

The response to DESCRIBE GRAPH is a multi-column result set:

GRAPH_NAME - name of the graph
GRAPH_SERVER_ID - ID of the graph server on which the graph is hosted
DIRECTED - whether the graph's edges have directionality, or if, instead, they are bidirectional
NUM_NODES - number of nodes in the graph
NUM_EDGES - number of edges in the graph
NUM_BYTES - bytes of memory used by the graph
IS_PERSISTED - whether the graph will survive a database restart or not
IS_SYNC_DB - whether the graph is recreated from its source tables upon database startup or not
GRAPH_OWNER_USER_NAME - name of user who created the graph
GRAPH_OWNER_RESOURCE_GROUP - resource group for the graph; the effective resource group of the graph creator at the time it was created
RESOURCE_CAPACITY - allocated memory limit for this graph
IS_PARTITIONED - whether the graph is distributed across the available graph servers
HAS_INSERT_TABLE_MONITOR - whether the graph has an associated insert table monitor or not
ORIGINAL_REQUEST - request used to create the graph, similar to what is returned by SHOW GRAPH

To show the configuration for a graph, big_cities_graph:

DESCRIBE GRAPH Example

1

DESCRIBE GRAPH big_cities_graph