ST_LocateAlong takes a linestring, point, or multipoint column, an m-value to query, and an optional offset column, and returns an array of geometries. The input geometry must have m-values. The output represents all points or line segments with m-values equal to the query m-value.
Locations along line segments are interpolated,
so the query m-value does not need to occur at an existing vertex. Matching points are grouped into a multipoint,
and matching line portions are grouped into a linestring in the output array. For a valid, nonempty
input geometry with m-values, the function returns an empty array if there are no matches. A positive offset value will return geometries
shifted to the left of the input line, while a negative offset value will return geometries shifted to the right of the
input line. For point input geometries, specifying a non-zero offset value will return null.
Here is a table describing the different locate functions and their primary differences.
| One query m-value | Two query m-values (start/end) | |
|---|---|---|
| Returns geometry column | ST_LocatePointAlong | ST_LocateLineBetween |
| Returns array column | ST_LocateAlong | ST_LocateBetween |
| Function | Syntax |
|---|---|
| Python | locate |
| SQL | ST |
| Scala | locate |
For more details, go to the GeoAnalytics Engine API reference for locate_along.
Examples
from geoanalytics.sql import functions as ST
LINE_M_WKT = [('LINESTRING M (10 10 10, 10 50 20, 50 50 30, 50 10 40)',)]
df = spark.createDataFrame(LINE_M_WKT, ["wkt"]) \
.withColumn("geometry", ST.line_from_text("wkt")) \
.withColumn("locate_along", ST.locate_along("geometry", 25, 5))
df.select("locate_along").show(truncate = False)+-------------------------------------+
|locate_along |
+-------------------------------------+
|[{"hasM":true,"points":[[30,55,25]]}]|
+-------------------------------------+Here is a visual representation of the code snippet above.
Version table
| Release | Notes |
|---|---|
2.2.0 | Python, SQL, and Scala functions introduced |