ST_LocateAlong

ST_LocateAlong takes a geometry and a measure as input parameters and returns a multipoint or multilinestring of that part of the given geometry that has exactly the specified measure of the given geometry that contains the specified measure.

For points and multipoints, all the points with the specified measure are returned. For linestrings, multilinestrings, polygons, and multipolygons, interpolation is performed to compute the result. The computation for polygons and multipolygons is performed on the boundary of the geometry.

For points and multipoints, if the given measure is not found, then an empty geometry is returned. For all other geometries, if the given measure is lower than the lowest measure in the geometry or higher than the highest measure in the geometry, then an empty geometry is returned.

If the given geometry is null, then null is returned.

Syntax

Parameters

geometry: A value of one of the seven distinct spatial data types that represents the geometry.
measure: A value of type DOUBLE that is the measure that the parts of geometry that must be included in the result.

Return type

db2gse.ST_Geometry

Examples

Example 1

The following CREATE TABLE statement creates the SAMPLE_GEOMETRIES table. The SAMPLE_GEOMETRIES table has two columns. The ID column uniquely identifies each row, and the GEOMETRY column ST_Geometry stores sample geometry.

CREATE TABLE sample_geometries(id SMALLINT, geometry ST_GEOMETRY)

The following INSERT statements insert two rows. The first is a linestring, and the second is a multipoint.

INSERT INTO sample_geometries(id, geometry) 
  VALUES (1, ST_Geometry(ST_LineString('linestring m (2 2 3, 3 5 3, 3 3 6, 
         4 4 8)', 1))), 
INSERT INTO sample_geometries(id, geometry) 
  VALUES (2, ST_Geometry(ST_MultiPoint('multipoint m (2 2 3, 3 5 3, 3 3 6, 
         4 4 6, 5 5 6, 6 6 8)', 1)))

Example 2

In the following SELECT statement and the corresponding result set, the ST_LocateAlong function finds points with a measure of 7. The first row returns a point, and the second row returns an empty point. For linear features (a geometry with a dimension that is greater than 0), the ST_LocateAlong function can interpolate the point; however, for multipoints the target measure must match exactly.

SELECT id, cast(ST_AsText(ST_LocateAlong(geometry, 7)) 
AS varchar(45)) AS measure_7 
FROM sample_geometries

Results:

  ID       MEASURE_7
--------- ------------------------------
   1      POINT M ( 3.50000000 3.50000000 7.00000000)
   2      POINT EMPTY

Example 3

In the following SELECT statement and the corresponding result set, the ST_LocateAlong function returns a point and a multipoint. The target measure of 6 matches the measures in both the ST_LocateAlong and the multipoint source data.

SELECT id, cast(ST_AsText(ST_LocateAlong(geometry, 6)) 
AS varchar(120)) AS measure_6 
FROM sample_geometries

Results:

  ID       MEASURE_6
--------- ------------------------------
   1      POINT M ( 3.00000000 3.00000000 6.00000000)
   2      MULTIPOINT M ( 3.00000000 3.00000000 6.00000000,
          4.00000000 4.00000000 6.00000000, 
          5.00000000 5.00000000 6.00000000)