Geo Functions Overview

MatrixOne provides a comprehensive set of ST_ spatial functions for creating, inspecting, measuring, and transforming GEOMETRY values. Functions are grouped by category below. Relationship predicates operate in the Cartesian plane (SRID 0); geodetic (SRID 4326) predicates are planned for a future release.

Syntax

All ST_ spatial functions use the form ST_<FunctionName>(<arguments>). Function names are case-insensitive. See each category below for the full signature of each function.

Arguments

Arguments vary by function category. Common argument types include GEOMETRY values, WKT strings, WKB binary, numeric constants, and SRID identifiers. Refer to each function’s signature in the tables below.

Examples

Each function category below includes runnable examples demonstrating typical usage. All examples in this page share a common database geo_func_demo and can be concatenated into a single pasteable script.

Constructors

Functions that create geometry values from text (WKT) or binary (WKB) input.

Function	Description
ST_GeomFromText(wkt [, srid])	Create geometry from WKT; optional SRID.
ST_GeometryFromText(wkt [, srid])	Synonym for ST_GeomFromText.
ST_PointFromText(wkt)	Create POINT from WKT. Rejects non-POINT WKT.
ST_LineFromText(wkt)	Create LINESTRING from WKT.
ST_LinestringFromText(wkt)	Synonym for ST_LineFromText.
ST_PolyFromText(wkt)	Create POLYGON from WKT.
ST_PolygonFromText(wkt)	Synonym for ST_PolyFromText.
ST_MPointFromText(wkt)	Create MULTIPOINT from WKT.
ST_MLineFromText(wkt)	Create MULTILINESTRING from WKT.
ST_MPolyFromText(wkt)	Create MULTIPOLYGON from WKT.
ST_GeomCollFromText(wkt)	Create GEOMETRYCOLLECTION from WKT.
ST_GeomFromWKB(wkb)	Create geometry from WKB binary.
ST_GeomFromBinary(wkb)	Synonym for ST_GeomFromWKB.
ST_PointFromWKB(wkb)	Create POINT from WKB binary.
ST_PolyFromWKB(wkb)	Create POLYGON from WKB binary.

Example:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

SELECT ST_AsText(ST_GeomFromText('POINT(1 2)')) AS point;
SELECT ST_AsText(ST_PointFromText('POINT(5 6)')) AS typed_point;
SELECT ST_AsText(ST_PolyFromText('POLYGON((0 0, 1 0, 1 1, 0 0))')) AS triangle;
SELECT ST_AsText(ST_GeomFromText('POINT(-1.5 2.25)')) AS decimals;

DROP DATABASE geo_func_demo;

I/O Functions

Functions that convert geometry values to and from text or binary representations.

Function	Description
ST_AsText(geom)	Return canonical WKT string.
ST_AsWKT(geom)	Synonym for ST_AsText.
ST_AsWKB(geom)	Return WKB binary.
ST_AsBinary(geom)	Synonym for ST_AsWKB.

Example:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

SELECT ST_AsText(ST_GeomFromText('POINT(1 2)')) AS wkt_output;
SELECT ST_AsText(ST_GeomFromWKB(ST_AsWKB(ST_GeomFromText('LINESTRING(0 0, 1 1, 2 3)')))) AS wkb_roundtrip;
SELECT ST_AsText(CAST('POINT(7 8)' AS GEOMETRY)) AS cast_point;

DROP DATABASE geo_func_demo;

Accessor Functions

Functions that inspect geometry structure, type, and coordinates.

Function	Description
ST_GeometryType(geom)	Return the geometry type name (e.g., ST_Point).
ST_X(point)	Return the X coordinate of a POINT.
ST_Y(point)	Return the Y coordinate of a POINT.
ST_Dimension(geom)	Return the inherent dimension (0=Point, 1=Line, 2=Polygon).
ST_NumPoints(ls)	Return the number of points in a LINESTRING.
ST_NumGeometries(gc)	Return the number of elements in a collection.
ST_NumInteriorRings(poly)	Return the number of interior rings in a POLYGON.
ST_NumInteriorRing(poly)	Singular synonym for ST_NumInteriorRings.
ST_IsEmpty(geom)	Return 1 if the geometry is empty, 0 otherwise.
ST_IsClosed(ls)	Return 1 if the LINESTRING is closed, 0 otherwise.
ST_IsCollection(geom)	Return 1 if the geometry is a collection type.
ST_SRID(geom)	Return the SRID of the geometry.

Measure Functions

Functions that compute scalar measures of a geometry.

Function	Description
ST_Area(poly)	Return the area of a POLYGON or MULTIPOLYGON. For SRID 4326, returns square meters.
ST_Length(ls)	Return the length of a LINESTRING or MULTILINESTRING. For SRID 4326, returns meters.
ST_Distance(g1, g2)	Return the minimum Euclidean distance between two geometries. For SRID 4326, returns meters.

Derived Geometry Functions

Functions that produce a new geometry from an input geometry.

Function	Description
ST_Centroid(geom)	Return the centroid point. Supports POINT, LINESTRING, POLYGON.
ST_Boundary(geom)	Return the boundary (LINESTRING for POLYGON, endpoints for LINESTRING).
ST_Envelope(geom)	Return the bounding rectangle as a POLYGON.
ST_StartPoint(ls)	Return the first point of a LINESTRING.
ST_EndPoint(ls)	Return the last point of a LINESTRING.
ST_PointN(ls, n)	Return the n-th point of a LINESTRING (1-indexed).
ST_ExteriorRing(poly)	Return the exterior ring of a POLYGON as a LINESTRING.
ST_InteriorRingN(poly, n)	Return the n-th interior ring of a POLYGON (1-indexed).
ST_GeometryN(gc, n)	Return the n-th element of a collection (1-indexed).
ST_PointOnSurface(poly)	Return a point guaranteed to lie on the surface of a POLYGON.

Example:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

SELECT ST_AsText(ST_Centroid(ST_GeomFromText('POLYGON((0 0, 2 0, 2 2, 0 2, 0 0))'))) AS centroid;
SELECT ST_AsText(ST_StartPoint(ST_GeomFromText('LINESTRING(7 8, 9 10, 11 12)'))) AS start_pt;
SELECT ST_AsText(ST_EndPoint(ST_GeomFromText('LINESTRING(7 8, 9 10, 11 12)'))) AS end_pt;
SELECT ST_AsText(ST_Envelope(ST_GeomFromText('LINESTRING(1 2, 3 4, 0 5)'))) AS envelope;
SELECT ST_AsText(ST_PointOnSurface(ST_GeomFromText('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))'))) AS point_on_surface;

DROP DATABASE geo_func_demo;

Spatial Relationship Predicates

Functions that test the spatial relationship between two geometries. These operate in the Cartesian plane (SRID 0). Both input geometries must have the same SRID.

Function	Description
ST_Contains(g1, g2)	Return 1 if g1 completely contains g2.
ST_Within(g1, g2)	Return 1 if g1 is completely within g2.
ST_Intersects(g1, g2)	Return 1 if the geometries intersect.
ST_Disjoint(g1, g2)	Return 1 if the geometries do not intersect.
ST_Touches(g1, g2)	Return 1 if the geometries touch at boundaries only.
ST_Crosses(g1, g2)	Return 1 if the geometries cross.
ST_Overlaps(g1, g2)	Return 1 if the geometries overlap (same dimension).
ST_Equals(g1, g2)	Return 1 if the geometries are spatially equal (order-independent).
ST_Covers(g1, g2)	Return 1 if g1 covers g2 (no point of g2 is outside g1).
ST_CoveredBy(g1, g2)	Return 1 if g1 is covered by g2.

Example:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

SELECT ST_Contains(
    ST_GeomFromText('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))'),
    ST_GeomFromText('POINT(2 2)')
) AS contains_yes;
SELECT ST_Within(
    ST_GeomFromText('POINT(2 2)'),
    ST_GeomFromText('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))')
) AS within_yes;
SELECT ST_Intersects(
    ST_GeomFromText('LINESTRING(0 0, 2 2)'),
    ST_GeomFromText('LINESTRING(0 2, 2 0)')
) AS intersects_yes;
SELECT ST_Disjoint(
    ST_GeomFromText('POINT(0 0)'),
    ST_GeomFromText('POINT(5 5)')
) AS disjoint_yes;
SELECT ST_Equals(
    ST_GeomFromText('POINT(1 1)'),
    ST_GeomFromText('POINT(1 1)')
) AS equals_yes;

DROP DATABASE geo_func_demo;

Validity Functions

Functions that test geometric validity and simplicity.

Function	Description
ST_IsSimple(geom)	Return 1 if the geometry has no anomalous self-intersection.
ST_IsRing(ls)	Return 1 if the LINESTRING is both closed and simple. Requires LINESTRING.
ST_IsValid(geom)	Return 1 if the geometry is structurally valid.

Example:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

SELECT ST_IsSimple(ST_GeomFromText('LINESTRING(0 0, 1 0, 2 0)')) AS simple_yes;
SELECT ST_IsSimple(ST_GeomFromText('LINESTRING(0 0, 2 2, 0 2, 2 0)')) AS simple_no;
SELECT ST_IsRing(ST_GeomFromText('LINESTRING(0 0, 2 0, 1 1, 0 0)')) AS ring_yes;
SELECT ST_IsValid(ST_GeomFromText('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))')) AS valid_yes;
SELECT ST_IsValid(ST_GeomFromText('POLYGON((0 0, 4 4, 4 0, 0 4, 0 0))')) AS valid_no;

DROP DATABASE geo_func_demo;

Constructive Geometry Functions

Functions that create new geometries through geometric operations.

Function	Description
ST_ConvexHull(geom)	Return the convex hull of the geometry.
ST_Simplify(geom, tolerance)	Return a simplified geometry using the Douglas-Peucker algorithm.
ST_Collect(g1, g2)	Return a MULTI geometry or GEOMETRYCOLLECTION from two geometries.
ST_Buffer(geom, distance [, segs_per_quarter])	Return a buffer polygon around the geometry. Planar Minkowski-sum buffer.

Example:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

SELECT ST_AsText(ST_ConvexHull(ST_GeomFromText('MULTIPOINT(0 0, 4 0, 4 4, 0 4, 2 2)'))) AS hull;
SELECT ST_AsText(ST_Simplify(ST_GeomFromText('LINESTRING(0 0, 5 0.0001, 10 0)'), 0.001)) AS simplified;
SELECT ST_AsText(ST_Collect(
    ST_GeomFromText('POINT(0 0)'),
    ST_GeomFromText('POINT(1 1)')
)) AS collected;
SELECT ST_Area(ST_Buffer(ST_GeomFromText('POINT(0 0)'), 2)) AS buffer_area;

DROP DATABASE geo_func_demo;

GeoHash Functions

Functions that encode and decode GeoHash strings.

Function	Description
ST_GeoHash(geom, max_length)	Return the GeoHash string for a POINT geometry.
ST_GeoHash(lon, lat, max_length)	Return the GeoHash string from longitude and latitude.
ST_LatFromGeoHash(gh)	Return the latitude from a GeoHash string.
ST_LongFromGeoHash(gh)	Return the longitude from a GeoHash string.
ST_PointFromGeoHash(gh, srid)	Return a POINT from a GeoHash string with the given SRID.

Example:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

SELECT ST_GeoHash(ST_GeomFromText('POINT(-5.603 42.605)'), 5) AS geohash;
SELECT ST_LatFromGeoHash('ezs42') AS latitude;
SELECT ST_LongFromGeoHash('ezs42') AS longitude;
SELECT ST_AsText(ST_PointFromGeoHash('ezs42', 4326)) AS point_from_gh;

DROP DATABASE geo_func_demo;

GeoJSON Functions

Functions that convert between geometry and GeoJSON format.

Function	Description
ST_AsGeoJSON(geom [, maxdecimaldigits])	Return the geometry as a GeoJSON string.
ST_GeomFromGeoJSON(json [, srid])	Create a geometry from a GeoJSON string. Default SRID is 4326.

Example:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

SELECT ST_AsGeoJSON(ST_GeomFromText('POINT(1 2)')) AS geojson;
SELECT ST_AsText(ST_GeomFromGeoJSON('{"type":"Point","coordinates":[3,4]}')) AS point;
SELECT ST_AsGeoJSON(ST_GeomFromText('POINT(1.23456 2.34567)'), 2) AS rounded;
SELECT ST_AsText(ST_GeomFromGeoJSON(ST_AsGeoJSON(
    ST_GeomFromText('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))')
))) AS roundtrip;

DROP DATABASE geo_func_demo;

MBR Predicates

Minimum Bounding Rectangle predicates that operate on the bounding boxes of geometries.

Function	Description
MBRContains(g1, g2)	Return 1 if the MBR of g1 contains the MBR of g2.
MBRWithin(g1, g2)	Return 1 if the MBR of g1 is within the MBR of g2.
MBRCovers(g1, g2)	Return 1 if the MBR of g1 covers the MBR of g2.
MBRCoveredBy(g1, g2)	Return 1 if the MBR of g1 is covered by the MBR of g2.
MBRDisjoint(g1, g2)	Return 1 if the MBRs are disjoint.
MBREquals(g1, g2)	Return 1 if the MBRs are equal.
MBRIntersects(g1, g2)	Return 1 if the MBRs intersect.
MBROverlaps(g1, g2)	Return 1 if the MBRs overlap (same dimension).
MBRTouches(g1, g2)	Return 1 if the MBRs touch at boundaries.

Example:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

SELECT MBRContains(
    ST_GeomFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))'),
    ST_GeomFromText('POLYGON((2 2, 4 2, 4 4, 2 4, 2 2))')
) AS mbr_contains;
SELECT MBRIntersects(
    ST_GeomFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))'),
    ST_GeomFromText('POLYGON((5 5, 15 5, 15 15, 5 15, 5 5))')
) AS mbr_intersects;

DROP DATABASE geo_func_demo;

Linear Referencing Functions

Functions that compute points along a LINESTRING by fraction or distance.

Function	Description
ST_LineInterpolatePoint(ls, fraction)	Return a point at the given fraction (0 to 1) along the LINESTRING.
ST_LineInterpolatePoints(ls, fraction)	Return a MULTIPOINT with points at regular intervals specified by the fraction.
ST_PointAtDistance(ls, distance)	Return a point at the given absolute distance along the LINESTRING.

Example:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

SELECT ST_AsText(ST_LineInterpolatePoint(
    ST_GeomFromText('LINESTRING(0 0, 10 0)'), 0.5
)) AS midpoint;
SELECT ST_AsText(ST_LineInterpolatePoints(
    ST_GeomFromText('LINESTRING(0 0, 10 0)'), 0.25
)) AS quarters;
SELECT ST_AsText(ST_PointAtDistance(
    ST_GeomFromText('LINESTRING(0 0, 10 0)'), 3
)) AS at_dist_3;

DROP DATABASE geo_func_demo;

Discrete Curve Distance Functions

Functions that compute distances between two geometries based on their vertex sets.

Function	Description
ST_FrechetDistance(g1, g2)	Return the Frechet distance (dog-leash distance).
ST_HausdorffDistance(g1, g2)	Return the Hausdorff distance (maximum of the minimum distances).

Example:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

SELECT ST_HausdorffDistance(
    ST_GeomFromText('LINESTRING(0 0, 10 0)'),
    ST_GeomFromText('LINESTRING(0 1, 10 1)')
) AS hausdorff;
SELECT ST_FrechetDistance(
    ST_GeomFromText('LINESTRING(0 0, 10 0)'),
    ST_GeomFromText('LINESTRING(0 0, 10 5)')
) AS frechet;

DROP DATABASE geo_func_demo;

Overlay Functions

Polygon Boolean overlay operations (Martinez-Rueda algorithm). Input geometries must be POLYGON or MULTIPOLYGON.

Function	Description
ST_Union(g1, g2)	Return the union of two polygons.
ST_Intersection(g1, g2)	Return the intersection of two polygons.
ST_Difference(g1, g2)	Return the difference (g1 minus g2) of two polygons.
ST_SymDifference(g1, g2)	Return the symmetric difference (XOR) of two polygons.

Example:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

SELECT ST_Area(ST_Intersection(
    ST_GeomFromText('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))'),
    ST_GeomFromText('POLYGON((2 2, 6 2, 6 6, 2 6, 2 2))')
)) AS intersection_area;
SELECT ST_Area(ST_Union(
    ST_GeomFromText('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))'),
    ST_GeomFromText('POLYGON((2 2, 6 2, 6 6, 2 6, 2 2))')
)) AS union_area;
SELECT ST_Area(ST_Difference(
    ST_GeomFromText('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))'),
    ST_GeomFromText('POLYGON((2 2, 6 2, 6 6, 2 6, 2 2))')
)) AS diff_area;

DROP DATABASE geo_func_demo;

Geodetic Measures

For SRID 4326, ST_Length, ST_Distance, and ST_Area compute geodetic values on the WGS 84 ellipsoid and return meters or square meters. For SRID 0, the same functions compute Cartesian values (unitless).

The +SRID overload syntax allows forcing a specific SRID computation regardless of the geometry’s type SRID:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

-- Geodetic distance: ~111 km per degree of longitude at the equator.
SELECT ST_Distance(
    ST_GeomFromText('POINT(0 0)', 4326),
    ST_GeomFromText('POINT(1 0)', 4326)
) AS geodesic_meters;
-- Cartesian distance: unitless.
SELECT ST_Distance(
    ST_GeomFromText('POINT(0 0)'),
    ST_GeomFromText('POINT(3 4)')
) AS cartesian_units;
-- Force geodetic computation via +SRID overload.
SELECT ST_Area(
    ST_GeomFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'), 4326
) AS forced_geodetic_m2;

DROP DATABASE geo_func_demo;

SRID Propagation

SRID is carried by the expression type and propagates through derived geometry computations. When columns are declared with an SRID, all constructors and computed geometries respect that SRID:

DROP DATABASE IF EXISTS geo_func_demo;
CREATE DATABASE geo_func_demo;
USE geo_func_demo;

SELECT ST_SRID(ST_Centroid(
    ST_GeomFromText('POLYGON((0 0, 2 0, 2 2, 0 2, 0 0))', 4326)
)) AS propagated_srid;
SELECT ST_SRID(ST_Boundary(
    ST_GeomFromText('POLYGON((0 0, 2 0, 2 2, 0 2, 0 0))', 4326)
)) AS boundary_srid;
SELECT ST_SRID(ST_StartPoint(
    ST_GeomFromText('LINESTRING(7 8, 9 10)', 4326)
)) AS startpoint_srid;

DROP DATABASE geo_func_demo;

See Also

• GEOMETRY Data Type