Geo 函数概览¶

MatrixOne 提供了一套全面的 ST_ 空间函数，用于创建、检查、测量和转换 GEOMETRY 值。以下按类别分组列出。所有空间函数。关系谓词在笛卡尔坐标系（SRID 0）下运算；大地测量（SRID 4326）谓词计划在后续版本中支持。

语法¶

所有 ST_ 空间函数均使用 ST_<函数名>(<参数>) 形式。函数名不区分大小写。各函数的完整签名请参阅下方对应类别。

参数说明¶

各函数类别的参数不同。常见参数类型包括 GEOMETRY 值、WKT 字符串、WKB 二进制、数值常量以及 SRID 标识符。具体参数请参阅下方各函数签名表。

示例¶

下方每个函数类别均包含可执行示例，演示典型用法。本页所有示例共享同一数据库 geo_func_demo，可拼接为单份可直接粘贴的脚本。

构造函数¶

从文本（WKT）或二进制（WKB）输入创建几何值的函数。

函数	描述
`ST_GeomFromText(wkt [, srid])`	从 WKT 创建几何值；可选 SRID。
`ST_GeometryFromText(wkt [, srid])`	`ST_GeomFromText` 的同义词。
`ST_PointFromText(wkt)`	从 WKT 创建 POINT。拒绝非 POINT 的 WKT。
`ST_LineFromText(wkt)`	从 WKT 创建 LINESTRING。
`ST_LinestringFromText(wkt)`	`ST_LineFromText` 的同义词。
`ST_PolyFromText(wkt)`	从 WKT 创建 POLYGON。
`ST_PolygonFromText(wkt)`	`ST_PolyFromText` 的同义词。
`ST_MPointFromText(wkt)`	从 WKT 创建 MULTIPOINT。
`ST_MLineFromText(wkt)`	从 WKT 创建 MULTILINESTRING。
`ST_MPolyFromText(wkt)`	从 WKT 创建 MULTIPOLYGON。
`ST_GeomCollFromText(wkt)`	从 WKT 创建 GEOMETRYCOLLECTION。
`ST_GeomFromWKB(wkb)`	从 WKB 二进制创建几何值。
`ST_GeomFromBinary(wkb)`	`ST_GeomFromWKB` 的同义词。
`ST_PointFromWKB(wkb)`	从 WKB 二进制创建 POINT。
`ST_PolyFromWKB(wkb)`	从 WKB 二进制创建 POLYGON。

示例：

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 函数¶

将几何值转换为文本或二进制表示的函数。

函数	描述
`ST_AsText(geom)`	返回规范 WKT 字符串。
`ST_AsWKT(geom)`	`ST_AsText` 的同义词。
`ST_AsWKB(geom)`	返回 WKB 二进制。
`ST_AsBinary(geom)`	`ST_AsWKB` 的同义词。

示例：

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;

访问器函数¶

检查几何结构、类型和坐标的函数。

函数	描述
`ST_GeometryType(geom)`	返回几何类型名称（如 `ST_Point`）。
`ST_X(point)`	返回 POINT 的 X 坐标。
`ST_Y(point)`	返回 POINT 的 Y 坐标。
`ST_Dimension(geom)`	返回固有维度（0=Point, 1=Line, 2=Polygon）。
`ST_NumPoints(ls)`	返回 LINESTRING 中的点数。
`ST_NumGeometries(gc)`	返回集合中的元素数。
`ST_NumInteriorRings(poly)`	返回 POLYGON 中内环的数量。
`ST_NumInteriorRing(poly)`	`ST_NumInteriorRings` 的单数同义词。
`ST_IsEmpty(geom)`	几何值为空返回 1，否则返回 0。
`ST_IsClosed(ls)`	LINESTRING 闭合返回 1，否则返回 0。
`ST_IsCollection(geom)`	几何值为集合类型返回 1。
`ST_SRID(geom)`	返回几何值的 SRID。

度量函数¶

计算几何度量标量值的函数。

函数	描述
`ST_Area(poly)`	返回 POLYGON 或 MULTIPOLYGON 的面积。SRID 4326 时返回平方米。
`ST_Length(ls)`	返回 LINESTRING 或 MULTILINESTRING 的长度。SRID 4326 时返回米。
`ST_Distance(g1, g2)`	返回两个几何值之间的最小欧几里得距离。SRID 4326 时返回米。

派生几何函数¶

从输入几何值生成新几何值的函数。

函数	描述
`ST_Centroid(geom)`	返回质心点。支持 POINT、LINESTRING、POLYGON。
`ST_Boundary(geom)`	返回边界（POLYGON 为 LINESTRING，LINESTRING 为端点）。
`ST_Envelope(geom)`	返回包围矩形作为 POLYGON。
`ST_StartPoint(ls)`	返回 LINESTRING 的第一个点。
`ST_EndPoint(ls)`	返回 LINESTRING 的最后一个点。
`ST_PointN(ls, n)`	返回 LINESTRING 的第 n 个点（从 1 开始）。
`ST_ExteriorRing(poly)`	返回 POLYGON 的外环作为 LINESTRING。
`ST_InteriorRingN(poly, n)`	返回 POLYGON 的第 n 个内环（从 1 开始）。
`ST_GeometryN(gc, n)`	返回集合的第 n 个元素（从 1 开始）。
`ST_PointOnSurface(poly)`	返回保证位于 POLYGON 表面上的一个点。

示例：

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;

空间关系谓词¶

测试两个几何值之间空间关系的函数。这些函数在笛卡尔坐标系（SRID 0）下运算。两个输入几何值必须具有相同的 SRID。

函数	描述
`ST_Contains(g1, g2)`	g1 完全包含 g2 返回 1。
`ST_Within(g1, g2)`	g1 完全在 g2 内返回 1。
`ST_Intersects(g1, g2)`	几何值相交返回 1。
`ST_Disjoint(g1, g2)`	几何值不相交返回 1。
`ST_Touches(g1, g2)`	几何值仅在边界接触返回 1。
`ST_Crosses(g1, g2)`	几何值交叉返回 1。
`ST_Overlaps(g1, g2)`	几何值重叠（同维度）返回 1。
`ST_Equals(g1, g2)`	几何值空间相等（与顺序无关）返回 1。
`ST_Covers(g1, g2)`	g1 覆盖 g2（g2 的任意点都不在 g1 外）返回 1。
`ST_CoveredBy(g1, g2)`	g1 被 g2 覆盖返回 1。

示例：

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;

有效性函数¶

测试几何有效性和简单性的函数。

函数	描述
`ST_IsSimple(geom)`	几何值无异常自相交返回 1。
`ST_IsRing(ls)`	LINESTRING 既闭合又简单返回 1。需要 LINESTRING 类型。
`ST_IsValid(geom)`	几何值结构有效返回 1。

示例：

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;

构造几何函数¶

通过几何运算创建新几何值的函数。

函数	描述
`ST_ConvexHull(geom)`	返回几何值的凸包。
`ST_Simplify(geom, tolerance)`	使用 Douglas-Peucker 算法返回简化几何值。
`ST_Collect(g1, g2)`	从两个几何值返回 MULTI 几何或 GEOMETRYCOLLECTION。
`ST_Buffer(geom, distance [, segs_per_quarter])`	返回几何值周围的缓冲区多边形。使用平面 Minkowski 和缓冲区算法。

示例：

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 函数¶

编解码 GeoHash 字符串的函数。

函数	描述
`ST_GeoHash(geom, max_length)`	返回 POINT 几何值的 GeoHash 字符串。
`ST_GeoHash(lon, lat, max_length)`	从经度和纬度返回 GeoHash 字符串。
`ST_LatFromGeoHash(gh)`	从 GeoHash 字符串返回纬度。
`ST_LongFromGeoHash(gh)`	从 GeoHash 字符串返回经度。
`ST_PointFromGeoHash(gh, srid)`	从 GeoHash 字符串和给定 SRID 返回 POINT。

示例：

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 函数¶

在几何值和 GeoJSON 格式之间转换的函数。

函数	描述
`ST_AsGeoJSON(geom [, maxdecimaldigits])`	将几何值以 GeoJSON 字符串返回。
`ST_GeomFromGeoJSON(json [, srid])`	从 GeoJSON 字符串创建几何值。默认 SRID 为 4326。

示例：

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 谓词¶

基于几何值包围框（Minimum Bounding Rectangle）运算的谓词函数。

函数	描述
`MBRContains(g1, g2)`	g1 的 MBR 包含 g2 的 MBR 返回 1。
`MBRWithin(g1, g2)`	g1 的 MBR 在 g2 的 MBR 内返回 1。
`MBRCovers(g1, g2)`	g1 的 MBR 覆盖 g2 的 MBR 返回 1。
`MBRCoveredBy(g1, g2)`	g1 的 MBR 被 g2 的 MBR 覆盖返回 1。
`MBRDisjoint(g1, g2)`	MBR 不相交返回 1。
`MBREquals(g1, g2)`	MBR 相等返回 1。
`MBRIntersects(g1, g2)`	MBR 相交返回 1。
`MBROverlaps(g1, g2)`	MBR 重叠（同维度）返回 1。
`MBRTouches(g1, g2)`	MBR 在边界接触返回 1。

示例：

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;

线性参考函数¶

沿 LINESTRING 按比例或距离计算点的函数。

函数	描述
`ST_LineInterpolatePoint(ls, fraction)`	返回 LINESTRING 在给定比例（0 到 1）处的点。
`ST_LineInterpolatePoints(ls, fraction)`	返回以给定比例为间隔的 MULTIPOINT。
`ST_PointAtDistance(ls, distance)`	返回 LINESTRING 在给定绝对距离处的点。

示例：

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;

离散曲线距离函数¶

基于顶点集计算两个几何值之间距离的函数。

函数	描述
`ST_FrechetDistance(g1, g2)`	返回 Frechet 距离（狗绳距离）。
`ST_HausdorffDistance(g1, g2)`	返回 Hausdorff 距离（最小距离中的最大值）。

示例：

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;

叠加函数¶

多边形布尔叠加运算（使用 Martinez-Rueda 算法）。输入几何值必须为 POLYGON 或 MULTIPOLYGON。

函数	描述
`ST_Union(g1, g2)`	返回两个多边形的并集。
`ST_Intersection(g1, g2)`	返回两个多边形的交集。
`ST_Difference(g1, g2)`	返回两个多边形的差集（g1 减去 g2）。
`ST_SymDifference(g1, g2)`	返回两个多边形的对称差集（XOR）。

示例：

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;

大地测量度量¶

对于 SRID 4326，ST_Length、ST_Distance 和 ST_Area 在 WGS 84 椭球体上计算大地测量值，返回米或平方米。对于 SRID 0，同一函数计算笛卡尔值（无单位）。

+SRID 重载语法允许强制使用特定 SRID 计算，无论几何值的类型 SRID 是什么：

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

-- 大地测量距离：赤道附近每经度约 111 公里。
SELECT ST_Distance(
    ST_GeomFromText('POINT(0 0)', 4326),
    ST_GeomFromText('POINT(1 0)', 4326)
) AS geodesic_meters;
-- 笛卡尔距离：无单位。
SELECT ST_Distance(
    ST_GeomFromText('POINT(0 0)'),
    ST_GeomFromText('POINT(3 4)')
) AS cartesian_units;
-- 通过 +SRID 重载强制大地测量计算。
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 传播¶

SRID 由表达式类型携带，并在派生几何计算中传播。当列声明了 SRID 时，所有构造函数和计算几何都遵循该 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;

另请参阅¶

GEOMETRY 数据类型