IsoDistance

Description

An isodistance is a polygon representing specific distance intervals from a particular point extended out along all possible paths. The IsoDistance function returns an isodistance connecting a set of points that lie at a specified distance from the given starting point, considering every possible route.

The IsoDistance UDF uses the GetTravelBoundary operation of the Global Routing API to generate the isodistance. The GetTravelBoundary operations helps determine the drive or walk time or the distance boundary from a given location. This function generates polygons corresponding to an isodistance calculation. For more information, see the Global Routing SDK User Guide, which is also available on the Spectrum Spatial for Big Data documentation landing page.

Function Registration

create function IsoDistance as 'com.pb.bigdata.spatial.routing.hive.IsoDistance';

Syntax

IsoDistance(WriteableGeometry startPoint, Number|String cost, 
            Map<String, String> options, Map<String, String> propagationFactorOptions)

IsoDistance(WriteableGeometry startPoint, Array<Number|String> costs, 
            Map<String, String> options, Map<String, String> propagationFactorOptions)

Parameters

Syntax

IsoDistance(Number|String startX, Number|String startY, Number|String cost, 
            Map<String, String> options, Map<String, String> propagationFactorOptions)

IsoDistance(Number|String startX, Number|String startY, Array<Number|String> costs, 
            Map<String, String> options, Map<String, String> propagationFactorOptions)

Parameters

Options

The options and propagationFactorOptions keys cannot be derived from a column in the table that the UDF is executed on. The keys of the options and propagationFactorOptions maps must also be of type String or convertible to String, and the values should be convertible to a type appropriate for the key’s value (typically this means that all values must be of type String). Keys and values of any type can be enclosed in either double or single quotes; a number or Boolean value will be processed correctly with or without quotes. For information on options that affect the calculation of the route, see Engine Options.

Propagation Factor Override Road Type Options

This option lets you adjust the distance traveled when going off-network.

Return Values

This function returns struct values described in the table below. In the case where a single cost is input, a single struct is returned. In the case where an array of multiple cost values are input, then an array of structs are returned.

Examples

SELECT ToWKT(IsoDistance(ST_Point(-77.088217, 38.937072), 1, map('pb.routing.distanceUnit', 'km')).geometry);

SELECT ToWKT(IsoDistance(Geocode('485A Watervliet Shaker Rd, Latham, NY 12110','usa').geometry, 500).geometry);

Sometimes calculating a route takes longer than expected and times out. You can adjust this using the engine options:

SELECT ToWKT(IsoDistance(x, y, cost, map(pb.routing.engine.timeout, 300)).geometry) FROM <table_name>;

The previous example had the time-out specified as an number. It can also be specified as a string:

SELECT ToWKT(IsoDistance(x, y, cost, map(pb.routing.engine.timeout, '300')).geometry) FROM <table_name>; 

Hive requires that all values in a MAP must be of the same type:

SELECT ToWKT(IsoDistance(x, y, cost, map(pb.routing.engine.timeout, '300', 'pb.routing.allowFallback', 'false')).geometry) FROM <table_name>;

Example showing multiple costs specified in an array for an input point. Hive requires that all values in an array must be of the same type:

SELECT costs[costidx] cost, ToWKT(iso.geometry) wkt, iso.error 
FROM points
LATERAL VIEW explode(array(array(5,10,20))) c as costs
LATERAL VIEW OUTER posexplode(IsoDistance(points.longitude,points.latitude,costs)) isoresult as costidx, iso;

Example showing propagationFactorOptions set:

SELECT ToWKT(IsoDistance(ST_Point(-77.088217, 38.937072), 3, null, map('footpath', '0.45')).geometry);

Example with both options and propagationFactorOptions set:

SELECT ToWKT(IsoDistance(ST_Point(-77.088217, 38.937072), 3, map('pb.routing.timeUnit', 'minute'), map('footpath', '0.45')).geometry);