ST_LocatePointAlong takes a linestring column, a query m-value, and an optional offset column, and returns a point column. The input linestring must have m-values. The output represents a point located where the query m-value is equal to the input linestring's m-value.

Locations along line segments are interpolated, so the query m-value does not need to occur at an existing vertex. If multiple locations match, the function returns the first match in input traversal order, including when m-values are non-monotonic. If the first match is a segment with a constant m-value, the function returns the first point of that segment. For a valid, nonempty input linestring with m-values, the function returns an empty point if there are no matches. A positive offset will return a point shifted to the left of the input line, while a negative offset value will return a point shifted to the right of the input line. This function differs from ST_LocateAlong in that it returns a single point instead of an array of geometries.

Here is a table describing the different locate functions and their primary differences.

One query m-valueTwo query m-values (start/end)
Returns geometry columnST_LocatePointAlongST_LocateLineBetween
Returns array columnST_LocateAlongST_LocateBetween
FunctionSyntax
Pythonlocate_point_along(linestring, measure, offset = 0)
SQLST_LocatePointAlong(linestring, measure, offset = 0)
ScalalocatePointAlong(linestring, measure, offset)

For more details, go to the GeoAnalytics Engine API reference for locate_point_along.

Examples

PythonPythonSQLScala
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10

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_point_along", ST.locate_point_along("geometry", 25, 5))

df.select("locate_point_along").show(truncate = False)
Result
Use dark colors for code blocksCopy
1
2
3
4
5
+----------------------+
|locate_point_along    |
+----------------------+
|{"x":30,"y":55,"m":25}|
+----------------------+

Here is a visual representation of the code snippet above.

Version table

ReleaseNotes

2.2.0

Python, SQL, and Scala functions introduced

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.