STS_GetLocNearest function

The STS_GetLocNearest function returns the nearest object to the specified point at the specified time.

Syntax

STS_GetLocNearest(    
                    subtrack_name   VARCHAR(128),
                    begin_time      DATETIME YEAR TO FRACTION(5),
                    end_time        DATETIME YEAR TO FRACTION(5),
                    geometry        ST_Geometry)
returns ROW

STS_GetLocNearest(    
                    subtrack_name   VARCHAR(128),
                    begin_time      DATETIME YEAR TO FRACTION(5),
                    end_time        DATETIME YEAR TO FRACTION(5),
                    geometry        ST_Geometry,
                    max_distance    FLOAT)
returns ROW

STS_GetLocNearest(    
                    subtrack_name   VARCHAR(128),
                    begin_time      DATETIME YEAR TO FRACTION(5),
                    end_time        DATETIME YEAR TO FRACTION(5),
                    geometry        ST_Geometry,
                    max_distance    FLOAT,
                    uom             VARCHAR(128))
returns ROW

STS_GetLocNearest(    
                    subtrack_name      VARCHAR(128),
                    begin_time         DATETIME YEAR TO FRACTION(5),
                    end_time           DATETIME YEAR TO FRACTION(5),
                    geometry           ST_Geometry,
                    max_distance       FLOAT,
                    uom                VARCHAR(128),
                    max_nearest_count  INTEGER)
returns ROW

subtrack_name: The name of the subtrack table.
begin_time: The start of the time range. Can be NULL to indicate the first element in the time series.
end_time: The end of the time range. Can be NULL to indicate the last element in the time series.
geometry: The region of interest. Can be an ST_Point, ST_MultiPoint, ST_LineString, ST_MultiLineString, ST_Polygon, or ST_MultiPolygon. Must use the SRID 4326.
max_distance (Optional): The distance from the geometry that defines the border of the region of interest. The unit of measure is specified by the uom parameter.
uom (Optional): The unit of measure for the radius parameter. If unitOfMeasure is not specified, then it is meter for a geographic coordinate systems, and, it is the linear unit of measure for projected coordinate systems. If the projected coordinate system does not have a linear unit of measure specified, it is meter. Must be the name of a linear unit of measure from the unit_name column of the st_units_of_measure table.
max_nearest_count (Optional): The maximum number of return values.; If you omit this parameter, the maximum number of return values is set by the value of the maxNearestCount field in the default parameters document. If the default parameters document does not exist, the number of results is not limited.

Usage

Run the STS_GetLocNearest function to find the set of objects, in order of distance from the geometry, at a specific time.

The following illustration shows three trajectories near the point (-78.752717 43.922478), with the trajectory of object m2 being the closest a 9:00, followed by the trajectories of m3 and m2.

Figure 1. Trajectories near a point at a specific time

Three trajectories are near the point 4326 POINT(-78.752717 43.922478).

Returns

The set of primary key values = The objects nearest the region, in order of distance from the region.

NULL = Nothing found.

Example: Return primary keys

The following statement returns which vehicle was closest to the specified region between the times of 2014-06-10 16:30:00 and 2014-06-10 17:00:00:

SELECT * FROM TABLE(STS_GetLocNearest('t_vehicle_subtrack', 
         '2014-06-10 16:30:00', '2014-06-10 17:00:00',
         ST_Buffer('4326 POINT(-78.752717 43.922478)'::ST_Point, 
                   1.00, 'kilometer'))::row(modid varchar(60))) 
         AS t(mid);

mid  ROW('1001')

1 row(s) retrieved.

Vehicle 1001 was the closest vehicle.