Filters vertices from a geometry object based on their M coordinate values and returns a new geometry object.
Syntax
geometry ST_FilterByM(geometry geom, double precision min, double precision max = null, boolean returnM = false);Parameters
| Parameter | Description | Default |
|---|---|---|
geom | The input geometry object. | — |
min | The minimum M coordinate value. Vertices with an M value below this threshold are excluded. | — |
max | The maximum M coordinate value. Vertices with an M value above this threshold are excluded. If omitted, only min is applied. | null |
returnM | Whether to include the M coordinate in the returned geometry. | false |
Description
ST_FilterByM returns a geometry object containing only vertices whose M coordinate is greater than or equal to min and less than or equal to max. If max is omitted, only the min threshold applies.
If too few vertices remain after filtering, the function returns an empty geometry object.
For GeometryCollection inputs, objects that do not contain enough points are ignored.
If the input geometry does not contain enough points,
ST_FilterByMreturns an empty geometry object. This differs from ST_SimplifyVW, which returns a geometry with enough points in the same situation.The returned geometry may be invalid.
The returned geometry preserves all dimensions of the input, including Z and M coordinates.
Examples
Filter by M coordinate range
SELECT ST_AsText(ST_FilterByM('LINESTRINGM(0 0 0,1 1 1,2 2 2,3 3 3)'::geometry, 2, 4, true));Result:
st_astext
----------------------------
LINESTRING M (2 2 2,3 3 3)
(1 row)Return an empty geometry when too few vertices remain
When filtering leaves fewer vertices than the geometry type requires, the function returns an empty geometry.
SELECT ST_AsText(ST_FilterByM('LINESTRINGM(0 0 0,1 1 1,2 2 2,3 3 3)'::geometry, 3, 4, true));Result:
st_astext
--------------------
LINESTRING M EMPTY
(1 row)