空间函数 – DuckDB - DuckDB 数据库

搜索快捷键 cmd + k | ctrl + k

文档 / 核心扩展 / 空间

空间函数

函数索引

函数	总结
`DuckDB_PROJ_Compiled_Version`	返回当前 DuckDB 实例编译所基于的 PROJ 库版本的文本描述。
`DuckDB_Proj_Version`	返回当前 DuckDB 实例正在使用的 PROJ 库版本的文本描述。
`ST_Affine`	对几何图形应用仿射变换。
`ST_Area`	计算几何图形的面积。
`ST_Area_Spheroid`	使用地球椭球模型，以米为单位返回几何图形的面积。
`ST_AsGeoJSON`	将几何图形作为 GeoJSON 片段返回。
`ST_AsHEXWKB`	将几何图形作为 HEXWKB 字符串返回。
`ST_AsSVG`	将几何图形转换为 SVG 片段或路径。
`ST_AsText`	将几何图形作为 WKT 字符串返回。
`ST_AsWKB`	将几何图形作为 WKB (Well-Known-Binary) 二进制大对象 (blob) 返回。
`ST_Azimuth`	以弧度返回两点之间的方位角（从北开始顺时针测量的角度）。
`ST_Boundary`	返回几何图形的“边界”。
`ST_Buffer`	返回输入几何图形在目标距离处的缓冲区。
`ST_BuildArea`	通过尝试“填充”输入几何图形来创建多边形几何图形。
`ST_Centroid`	返回几何图形的质心。
`ST_Collect`	将几何图形列表收集为集合几何图形。
`ST_CollectionExtract`	将 GeometryCollection 中的几何图形提取为类型化的多重几何图形。
`ST_ConcaveHull`	返回输入几何图形的“凹包”，包含源输入的所有点，可用于从点创建多边形。ratio 参数决定凹陷程度；1.0 返回凸包；0 表示返回尽可能最凹的包。将 allowHoles 设置为非零值以允许输出包含孔洞。
`ST_Contains`	如果第一个几何图形包含第二个几何图形，则返回 true。
`ST_ContainsProperly`	如果第一个几何图形“正确”包含第二个几何图形，则返回 true。
`ST_ConvexHull`	返回包围几何图形的凸包。
`ST_CoverageInvalidEdges`	返回多边形覆盖中无效的边，即未被两个多边形共享的边。
`ST_CoverageSimplify`	简化多边形覆盖中的边，确保简化后的多边形之间没有缝隙，从而保持覆盖完整性。
`ST_CoverageUnion`	将多边形覆盖中的所有几何图形合并为单个几何图形。
`ST_CoveredBy`	如果 geom1 被 geom2 “覆盖”，则返回 true。
`ST_Covers`	如果 geom1 “覆盖” geom2，则返回 true。
`ST_Crosses`	如果 geom1 “穿过” geom2，则返回 true。
`ST_DWithin`	如果两个几何图形在目标距离内，则返回 true。
`ST_DWithin_GEOS`	如果两个几何图形在目标距离内，则返回 true。
`ST_DWithin_Spheroid`	使用地球椭球模型，如果两个 POINT_2D 在目标距离（米）内，则返回 true。
`ST_Difference`	返回两个几何图形之间的“差集”。
`ST_Dimension`	返回几何图形的“拓扑维数”。
`ST_Disjoint`	如果几何图形是不相交的，则返回 true。
`ST_Distance`	返回两个几何图形之间的平面距离。
`ST_Distance_GEOS`	返回两个几何图形之间的平面距离。
`ST_Distance_Sphere`	返回两个几何图形之间的半正矢（大圆）距离。
`ST_Distance_Spheroid`	使用地球椭球模型，以米为单位返回两个几何图形之间的距离。
`ST_Dump`	将几何图形转储为子几何图形列表及其在原始几何图形中的“路径”。
`ST_EndPoint`	返回 LINESTRING 的终点。
`ST_Envelope`	将几何图形的最小外接矩形作为多边形几何图形返回。
`ST_Equals`	如果几何图形“相等”，则返回 true。
`ST_Extent`	返回包围输入几何图形的最小外接矩形。
`ST_Extent_Approx`	如果可用，返回几何图形的近似外接矩形。
`ST_ExteriorRing`	返回多边形几何图形的外环（壳）。
`ST_FlipCoordinates`	返回一个新几何图形，其坐标“翻转”，即 x = y 且 y = x。
`ST_Force2D`	强制几何图形的顶点具有 X 和 Y 分量。
`ST_Force3DM`	强制几何图形的顶点具有 X、Y 和 M 分量。
`ST_Force3DZ`	强制几何图形的顶点具有 X、Y 和 Z 分量。
`ST_Force4D`	强制几何图形的顶点具有 X、Y、Z 和 M 分量。
`ST_GeomFromGeoJSON`	从 GeoJSON 片段反序列化一个 GEOMETRY。
`ST_GeomFromHEXEWKB`	从 HEX(E)WKB 编码字符串反序列化一个 GEOMETRY。
`ST_GeomFromHEXWKB`	从 HEX(E)WKB 编码字符串反序列化一个 GEOMETRY。
`ST_GeomFromText`	从 WKT 编码字符串反序列化一个 GEOMETRY。
`ST_GeomFromWKB`	从 WKB 编码的 blob 反序列化一个 GEOMETRY。
`ST_GeometryType`	返回识别输入几何类型的 'GEOMETRY_TYPE' 枚举。可能的枚举返回类型为：`POINT`、`LINESTRING`、`POLYGON`、`MULTIPOINT`、`MULTILINESTRING`、`MULTIPOLYGON` 和 `GEOMETRYCOLLECTION`。
`ST_HasM`	检查输入几何图形是否具有 M 值。
`ST_HasZ`	检查输入几何图形是否具有 Z 值。
`ST_Hilbert`	将 X 和 Y 值编码为覆盖给定外接矩形的希尔伯特曲线索引。
`ST_Intersection`	返回两个几何图形的交集。
`ST_Intersects`	如果几何图形相交，则返回 true。
`ST_Intersects_Extent`	如果两个几何图形的外接矩形相交，则返回 true。
`ST_IsClosed`	检查几何图形是否“闭合”。
`ST_IsEmpty`	如果几何图形是“空”的，则返回 true。
`ST_IsRing`	如果几何图形是环（同时满足 ST_IsClosed 和 ST_IsSimple），则返回 true。
`ST_IsSimple`	如果几何图形是简单图形，则返回 true。
`ST_IsValid`	如果几何图形有效，则返回 true。
`ST_Length`	返回输入线几何图形的长度。
`ST_Length_Spheroid`	使用地球椭球模型，以米为单位返回输入几何图形的长度。
`ST_LineInterpolatePoint`	返回沿线按总 2D 长度的分数插值的点。
`ST_LineInterpolatePoints`	返回沿线按总 2D 长度的分数插值的多点。
`ST_LineMerge`	“合并”输入线几何图形，可选择考虑方向。
`ST_LineString2DFromWKB`	从 WKB 编码的 blob 反序列化一个 LINESTRING_2D。
`ST_LineSubstring`	返回线在总 2D 长度的两个分数之间的子字符串。
`ST_M`	返回点几何图形的 M 坐标。
`ST_MMax`	返回几何图形的最大 M 坐标。
`ST_MMin`	返回几何图形的最小 M 坐标。
`ST_MakeEnvelope`	根据最小/最大坐标创建矩形多边形。
`ST_MakeLine`	从 POINT 几何图形列表创建 LINESTRING。
`ST_MakePolygon`	从 LINESTRING 壳创建 POLYGON。
`ST_MakeValid`	返回几何图形的有效表示。
`ST_MaximumInscribedCircle`	返回输入几何图形的最大内切圆，可选精度容差。
`ST_MinimumRotatedRectangle`	返回包围输入几何图形的最小旋转矩形，通过使用旋转矩形寻找面积最小的外接框，而不是像 ST_Envelope() 那样仅取最高和最低坐标值。
`ST_Multi`	将单个几何图形转变为多重几何图形。
`ST_NGeometries`	返回集合几何图形中的组件几何图形数量。
`ST_NInteriorRings`	返回多边形的内环数量。
`ST_NPoints`	返回几何图形内的顶点数量。
`ST_Node`	返回一个“节点化”的 MultiLinestring，由组合一组输入 linestring 并在此相交处添加额外顶点产生。
`ST_Normalize`	返回几何图形的“归一化”表示。
`ST_NumGeometries`	返回集合几何图形中的组件几何图形数量。
`ST_NumInteriorRings`	返回多边形的内环数量。
`ST_NumPoints`	返回几何图形内的顶点数量。
`ST_Overlaps`	如果几何图形重叠，则返回 true。
`ST_Perimeter`	返回几何图形周长的长度。
`ST_Perimeter_Spheroid`	使用地球椭球模型，以米为单位返回周长的长度。
`ST_Point`	创建一个 GEOMETRY 点。
`ST_Point2D`	创建一个 POINT_2D。
`ST_Point2DFromWKB`	从 WKB 编码的 blob 反序列化一个 POINT_2D。
`ST_Point3D`	创建一个 POINT_3D。
`ST_Point4D`	创建一个 POINT_4D。
`ST_PointN`	将输入几何图形的第 n 个顶点作为点几何图形返回。
`ST_PointOnSurface`	返回一个保证位于几何图形表面上的点。
`ST_Points`	将几何图形中的所有顶点收集为 MULTIPOINT。
`ST_Polygon2DFromWKB`	从 WKB 编码的 blob 反序列化一个 POLYGON_2D。
`ST_Polygonize`	返回输入几何图形的多边形化表示。
`ST_QuadKey`	计算给定经纬度点在给定层级的 quadkey。
`ST_ReducePrecision`	返回将所有顶点减少到给定精度的几何图形。
`ST_RemoveRepeatedPoints`	从 LINESTRING 中移除重复点。
`ST_Reverse`	返回其顶点顺序被反转的几何图形。
`ST_ShortestLine`	返回两个几何图形之间的最短线。
`ST_Simplify`	返回几何图形的简化版本。
`ST_SimplifyPreserveTopology`	返回保留拓扑的几何图形简化版本。
`ST_StartPoint`	返回 LINESTRING 的起点。
`ST_TileEnvelope`	`ST_TileEnvelope` 标量函数根据指定的缩放级别和瓦片索引生成瓦片外接矩形多边形。
`ST_Touches`	如果几何图形接触，则返回 true。
`ST_Transform`	在两个坐标系之间转换几何图形。
`ST_Union`	返回两个几何图形的并集。
`ST_VoronoiDiagram`	返回提供的 MultiPoint 几何图形的泰森多边形（Voronoi）图。
`ST_Within`	如果第一个几何图形在第二个几何图形内，则返回 true。
`ST_WithinProperly`	如果第一个几何图形“正确”包含在第二个几何图形中，则返回 true。
`ST_X`	返回点几何图形的 X 坐标。
`ST_XMax`	返回几何图形的最大 X 坐标。
`ST_XMin`	返回几何图形的最小 X 坐标。
`ST_Y`	返回点几何图形的 Y 坐标。
`ST_YMax`	返回几何图形的最大 Y 坐标。
`ST_YMin`	返回几何图形的最小 Y 坐标。
`ST_Z`	返回点几何图形的 Z 坐标。
`ST_ZMFlag`	返回指示输入几何图形中 Z 和 M 值存在情况的标志。
`ST_ZMax`	返回几何图形的最大 Z 坐标。
`ST_ZMin`	返回几何图形的最小 Z 坐标。

聚合函数

函数	总结
`ST_CoverageInvalidEdges_Agg`	返回覆盖几何图形的无效边。
`ST_CoverageSimplify_Agg`	在保持覆盖完整性的同时简化一组几何图形。
`ST_CoverageUnion_Agg`	在保持覆盖完整性的同时合并一组几何图形。
`ST_Envelope_Agg`	ST_Extent_Agg 的别名。
`ST_Extent_Agg`	计算包含一组输入几何图形的最小外接矩形多边形。
`ST_Intersection_Agg`	计算一组几何图形的交集。
`ST_MemUnion_Agg`	计算一组输入几何图形的并集。
`ST_Union_Agg`	计算一组输入几何图形的并集。

宏函数

函数	总结
`ST_Rotate`	ST_RotateZ 的别名。
`ST_RotateX`	围绕 X 轴旋转几何图形。这是调用 ST_Affine 的简写宏。
`ST_RotateY`	围绕 Y 轴旋转几何图形。这是调用 ST_Affine 的简写宏。
`ST_RotateZ`	围绕 Z 轴旋转几何图形。这是调用 ST_Affine 的简写宏。
`ST_Scale`
`ST_TransScale`	在 X 和 Y 方向平移然后缩放几何图形。这是调用 ST_Affine 的简写宏。
`ST_Translate`

表函数

函数	总结
`ST_Drivers`	返回支持的 GDAL 驱动程序和文件格式列表。
`ST_GeneratePoints`	在指定的外接矩形内生成一组随机点。
`ST_Read`	使用 GDAL 库读取并导入各种地理空间文件格式。
`ST_ReadOSM`	`ST_ReadOsm()` 表函数支持直接从 `.osm.pbf` 文件读取压缩的 OpenStreetMap 数据。
`ST_ReadSHP`	在不依赖 GDAL 库的情况下读取 Shapefile。
`ST_Read_Meta`	使用 GDAL 库读取各种地理空间文件格式的元数据。

标量函数

DuckDB_PROJ_Compiled_Version

签名

VARCHAR DuckDB_PROJ_Compiled_Version ()

示例

SELECT duckdb_proj_compiled_version();
┌────────────────────────────────┐
│ duckdb_proj_compiled_version() │
│            varchar             │
├────────────────────────────────┤
│ Rel. 9.1.1, December 1st, 2022 │
└────────────────────────────────┘

DuckDB_Proj_Version

签名

VARCHAR DuckDB_Proj_Version ()

示例

SELECT duckdb_proj_version();
┌───────────────────────┐
│ duckdb_proj_version() │
│        varchar        │
├───────────────────────┤
│ 9.1.1                 │
└───────────────────────┘

ST_Affine

签名

GEOMETRY ST_Affine (geom GEOMETRY, a DOUBLE, b DOUBLE, c DOUBLE, d DOUBLE, e DOUBLE, f DOUBLE, g DOUBLE, h DOUBLE, i DOUBLE, xoff DOUBLE, yoff DOUBLE, zoff DOUBLE)
GEOMETRY ST_Affine (geom GEOMETRY, a DOUBLE, b DOUBLE, d DOUBLE, e DOUBLE, xoff DOUBLE, yoff DOUBLE)

示例

-- Translate a point by (2, 3)
SELECT ST_Affine(ST_Point(1, 1),
                 1, 0,   -- a, b
                 0, 1,   -- d, e
                 2, 3);  -- xoff, yoff
----
POINT (3 4)

-- Scale a geometry by factor 2 in X and Y
SELECT ST_Affine(ST_Point(1, 1),
                 2, 0, 0,   -- a, b, c
                 0, 2, 0,   -- d, e, f
                 0, 0, 1,   -- g, h, i
                 0, 0, 0);  -- xoff, yoff, zoff
----
POINT (2 2)

ST_Area

签名

DOUBLE ST_Area (geom GEOMETRY)
DOUBLE ST_Area (polygon POLYGON_2D)
DOUBLE ST_Area (linestring LINESTRING_2D)
DOUBLE ST_Area (point POINT_2D)
DOUBLE ST_Area (box BOX_2D)

描述

计算几何图形的面积。

对于任何不是 POLYGON、MULTIPOLYGON 或包含多边形几何图形的 GEOMETRYCOLLECTION 的几何图形，返回 0.0。

面积单位与几何图形的空间参考系统一致。

此函数的 POINT_2D 和 LINESTRING_2D 重载始终返回 0.0，但为了完整性包含在内。

示例

select ST_Area('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry);
-- 1.0

ST_Area_Spheroid

签名

DOUBLE ST_Area_Spheroid (geom GEOMETRY)
DOUBLE ST_Area_Spheroid (poly POLYGON_2D)

描述

使用地球椭球模型，以米为单位返回几何图形的面积。

假定输入几何图形处于 EPSG:4326 坐标系 (WGS84) 中，轴顺序为 [纬度, 经度]，面积以平方米为单位返回。此函数使用 GeographicLib 库，通过地球椭球模型计算面积。这是一种考虑了地球曲率的计算多边形面积的高精度方法，但也是最慢的。

对于任何不是 POLYGON、MULTIPOLYGON 或包含多边形几何图形的 GEOMETRYCOLLECTION 的几何图形，返回 0.0。

ST_AsGeoJSON

签名

JSON ST_AsGeoJSON (geom GEOMETRY)

描述

将几何图形作为 GeoJSON 片段返回。

这不会返回完整的 GeoJSON 文档，仅返回几何片段。要构建完整的 GeoJSON 文档或要素，请结合此函数使用 DuckDB JSON 扩展。此函数支持带有 Z 值的几何图形，但不支持 M 值。M 值会被忽略。

示例

select ST_AsGeoJSON('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry);
----
{"type":"Polygon","coordinates":[[[0.0,0.0],[0.0,1.0],[1.0,1.0],[1.0,0.0],[0.0,0.0]]]}

-- Convert a geometry into a full GeoJSON feature (requires the JSON extension to be loaded)
SELECT CAST({
    type: 'Feature',
    geometry: ST_AsGeoJSON(ST_Point(1,2)),
    properties: {
        name: 'my_point'
    }
} AS JSON);
----
{"type":"Feature","geometry":{"type":"Point","coordinates":[1.0,2.0]},"properties":{"name":"my_point"}}

ST_AsHEXWKB

签名

VARCHAR ST_AsHEXWKB (geom GEOMETRY)

示例

SELECT ST_AsHexWKB('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry);
----
01030000000100000005000000000000000000000000000...

ST_AsSVG

签名

VARCHAR ST_AsSVG (geom GEOMETRY, relative BOOLEAN, precision INTEGER)

描述

将几何图形转换为 SVG 片段或路径。

SVG 片段以字符串形式返回。该片段是一个可以在 SVG 文档中使用的路径元素。第三个布尔参数指定路径应该是相对坐标还是绝对坐标。第三个参数指定坐标所使用的最大位数。

点使用绝对坐标格式化为 cx/cy，或使用相对坐标格式化为 x/y。

示例

SELECT ST_AsSVG('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::GEOMETRY, false, 15);
----
M 0 0 L 0 -1 1 -1 1 0 Z

ST_AsText

签名

VARCHAR ST_AsText (geom GEOMETRY)
VARCHAR ST_AsText (point POINT_2D)
VARCHAR ST_AsText (linestring LINESTRING_2D)
VARCHAR ST_AsText (polygon POLYGON_2D)
VARCHAR ST_AsText (box BOX_2D)

示例

SELECT ST_MakeEnvelope(0,0,1,1);
----
POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))

ST_AsWKB

签名

WKB_BLOB ST_AsWKB (geom GEOMETRY)

描述

将几何图形作为 WKB (Well-Known-Binary) 二进制大对象 (blob) 返回。

示例

SELECT ST_AsWKB('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::GEOMETRY)::BLOB;
----
\x01\x03\x00\x00\x00\x01\x00\x00\x00\x05...

ST_Azimuth

签名

DOUBLE ST_Azimuth (origin GEOMETRY, target GEOMETRY)
DOUBLE ST_Azimuth (origin POINT_2D, target POINT_2D)

示例

SELECT degrees(ST_Azimuth(ST_Point(0, 0), ST_Point(0, 1)));
----
90.0

ST_Buffer

签名

GEOMETRY ST_Buffer (geom GEOMETRY, distance DOUBLE)
GEOMETRY ST_Buffer (geom GEOMETRY, distance DOUBLE, num_triangles INTEGER)
GEOMETRY ST_Buffer (geom GEOMETRY, distance DOUBLE, num_triangles INTEGER, cap_style VARCHAR, join_style VARCHAR, mitre_limit DOUBLE)

描述

返回输入几何图形在目标距离处的缓冲区。

geom 是输入几何图形。

distance 是缓冲区的目标距离，单位与输入几何图形相同。

num_triangles 表示将生成多少个三角形来近似四分之一圆。数值越大，生成的几何图形越平滑。默认值为 8。

cap_style 必须是 "CAP_ROUND"、"CAP_FLAT"、"CAP_SQUARE" 之一。此参数不区分大小写。

join_style 必须是 "JOIN_ROUND"、"JOIN_MITRE"、"JOIN_BEVEL" 之一。此参数不区分大小写。

mitre_limit 仅在 join_style 为 "JOIN_MITRE" 时适用。它是从角点到斜接点的距离与角半径的比率。默认值为 1.0。

这是一个平面操作，不会考虑地球的曲率。

ST_BuildArea

签名

GEOMETRY ST_BuildArea (geom GEOMETRY)

描述

通过尝试“填充”输入几何图形来创建多边形几何图形。

与 ST_Polygonize 不同，此函数不会填充孔洞。

ST_Collect

签名

GEOMETRY ST_Collect (geoms GEOMETRY[])

描述

将几何图形列表收集为集合几何图形。

如果所有几何图形都是 POINT，则返回一个 MULTIPOINT。
如果所有几何图形都是 LINESTRING，则返回一个 MULTILINESTRING。
如果所有几何图形都是 POLYGON，则返回一个 MULTIPOLYGON。
否则，如果输入集合包含不同类型的几何图形，则返回一个 GEOMETRYCOLLECTION。

空几何图形和 NULL 几何图形会被忽略。如果所有几何图形均为空或为 NULL，则返回 GEOMETRYCOLLECTION EMPTY。

示例

-- With all POINT's, a MULTIPOINT is returned
SELECT ST_Collect([ST_Point(1, 2), ST_Point(3, 4)]);
----
MULTIPOINT (1 2, 3 4)

-- With mixed geometry types, a GEOMETRYCOLLECTION is returned
SELECT ST_Collect([ST_Point(1, 2), ST_GeomFromText('LINESTRING(3 4, 5 6)')]);
----
GEOMETRYCOLLECTION (POINT (1 2), LINESTRING (3 4, 5 6))

-- Note that the empty geometry is ignored, so the result is a MULTIPOINT
SELECT ST_Collect([ST_Point(1, 2), NULL, ST_GeomFromText('GEOMETRYCOLLECTION EMPTY')]);
----
MULTIPOINT (1 2)

-- If all geometries are empty or NULL, a GEOMETRYCOLLECTION EMPTY is returned
SELECT ST_Collect([NULL, ST_GeomFromText('GEOMETRYCOLLECTION EMPTY')]);
----
GEOMETRYCOLLECTION EMPTY

-- Tip: You can use the `ST_Collect` function together with the `list()` aggregate function to collect multiple rows of geometries into a single geometry collection:

CREATE TABLE points (geom GEOMETRY);

INSERT INTO points VALUES (ST_Point(1, 2)), (ST_Point(3, 4));

SELECT ST_Collect(list(geom)) FROM points;
----
MULTIPOINT (1 2, 3 4)

ST_CollectionExtract

签名

GEOMETRY ST_CollectionExtract (geom GEOMETRY, type INTEGER)
GEOMETRY ST_CollectionExtract (geom GEOMETRY)

描述

将 GeometryCollection 中的几何图形提取为类型化的多重几何图形。

如果输入几何图形是 GeometryCollection，函数将根据 type 参数返回多重几何图形。

如果 type = 1，返回包含集合中所有点的 MultiPoint。
如果 type = 2，返回包含集合中所有 LineString 的 MultiLineString。
如果 type = 3，返回包含集合中所有 Polygon 的 MultiPolygon。

如果未提供 type 参数，函数将返回与所包含几何图形的最高“表面维度”匹配的多重几何图形。例如，如果集合仅包含点，则返回 MultiPoint；如果包含点和线，则返回 MultiLineString；同样，如果包含多边形，则返回 MultiPolygon。较低表面维度的包含几何图形将被忽略。

如果输入几何图形包含嵌套的 GeometryCollection，它们的几何图形也将被递归提取并包含在最终的多重几何图形中。

如果输入几何图形不是 GeometryCollection，函数将按原样返回输入几何图形。

示例

select st_collectionextract('MULTIPOINT(1 2,3 4)'::geometry, 1);
-- MULTIPOINT (1 2, 3 4)

ST_ConcaveHull

签名

GEOMETRY ST_ConcaveHull (geom GEOMETRY, ratio DOUBLE, allowHoles BOOLEAN)

描述

返回输入几何图形的“凹包”，包含源输入的所有点，可用于从点创建多边形。ratio 参数决定凹陷程度；1.0 返回凸包；0 表示返回尽可能最凹的包。将 allowHoles 设置为非零值以允许输出包含孔洞。

ST_Contains

签名

BOOLEAN ST_Contains (geom1 POLYGON_2D, geom2 POINT_2D)
BOOLEAN ST_Contains (geom1 GEOMETRY, geom2 GEOMETRY)

描述

如果第一个几何图形包含第二个几何图形，则返回 true。

与 ST_ContainsProperly 不同，如果 geom2 严格包含在 geom1 的边界上，此函数也将返回 true。几何图形总是 ST_Contains 其自身，但不 ST_ContainsProperly 其自身。

ST_ContainsProperly

签名

BOOLEAN ST_ContainsProperly (geom1 GEOMETRY, geom2 GEOMETRY)

描述

如果第一个几何图形“正确”包含第二个几何图形，则返回 true。

与 ST_Contains 不同，如果 geom2 严格包含在 geom1 的边界上，此函数不返回 true。几何图形总是 ST_Contains 其自身，但不 ST_ContainsProperly 其自身。

ST_CoverageInvalidEdges

签名

GEOMETRY ST_CoverageInvalidEdges (geoms GEOMETRY[], tolerance DOUBLE)
GEOMETRY ST_CoverageInvalidEdges (geoms GEOMETRY[])

描述

返回多边形覆盖中无效的边，即未被两个多边形共享的边。如果输入不是多边形覆盖，或者输入有效，则返回 NULL。容差默认为 0。

ST_CoverageSimplify

签名

GEOMETRY ST_CoverageSimplify (geoms GEOMETRY[], tolerance DOUBLE, simplify_boundary BOOLEAN)
GEOMETRY ST_CoverageSimplify (geoms GEOMETRY[], tolerance DOUBLE)

描述

简化多边形覆盖中的边，确保简化后的多边形之间没有缝隙，从而保持覆盖完整性。

默认情况下，覆盖的边界也会被简化，但这可以通过可选的第三个 'simplify_boundary' 参数进行控制。

ST_CoverageUnion

签名

GEOMETRY ST_CoverageUnion (geoms GEOMETRY[])

描述

将多边形覆盖中的所有几何图形合并为单个几何图形。这可能比使用 ST_Union 更快，但可能使用更多内存。

ST_DWithin_Spheroid

签名

BOOLEAN ST_DWithin_Spheroid (p1 POINT_2D, p2 POINT_2D, distance DOUBLE)

描述

使用地球椭球模型，如果两个 POINT_2D 在目标距离（米）内，则返回 true。

假定输入几何图形处于 EPSG:4326 坐标系 (WGS84) 中，轴顺序为 [纬度, 经度]，距离以米为单位返回。此函数使用 GeographicLib 库来解决反向测地线问题，使用地球椭球模型计算两点之间的距离。这是一种考虑了地球表面曲率的计算任意两点间距离的高精度方法，但也是最慢的。

ST_Dimension

签名

INTEGER ST_Dimension (geom GEOMETRY)

描述

返回几何图形的“拓扑维数”。

对于 POINT 和 MULTIPOINT 几何图形，返回 0。
对于 LINESTRING 和 MULTILINESTRING，返回 1。
对于 POLYGON 和 MULTIPOLYGON，返回 2。
对于 GEOMETRYCOLLECTION，返回所含几何图形的最大维度，如果集合为空，则返回 0。

示例

select st_dimension('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry);
----
2

ST_Distance

签名

DOUBLE ST_Distance (point1 POINT_2D, point2 POINT_2D)
DOUBLE ST_Distance (point POINT_2D, linestring LINESTRING_2D)
DOUBLE ST_Distance (linestring LINESTRING_2D, point POINT_2D)
DOUBLE ST_Distance (geom1 GEOMETRY, geom2 GEOMETRY)

示例

SELECT ST_Distance('POINT (0 0)'::GEOMETRY, 'POINT (3 4)'::GEOMETRY);
----
5.0

-- Z coordinates are ignored
SELECT ST_Distance('POINT Z (0 0 0)'::GEOMETRY, 'POINT Z (3 4 5)'::GEOMETRY);
----
5.0

ST_Distance_Sphere

签名

DOUBLE ST_Distance_Sphere (geom1 GEOMETRY, geom2 GEOMETRY)
DOUBLE ST_Distance_Sphere (point1 POINT_2D, point2 POINT_2D)

描述

返回两个几何图形之间的半正矢（大圆）距离。

仅支持 POINT 几何图形。
返回以米为单位的距离。
输入预计使用 WGS84 (EPSG:4326) 坐标，轴顺序为 [纬度, 经度]。

ST_Distance_Spheroid

签名

DOUBLE ST_Distance_Spheroid (p1 POINT_2D, p2 POINT_2D)

描述

使用地球椭球模型，以米为单位返回两个几何图形之间的距离。

假定输入几何图形处于 EPSG:4326 坐标系 (WGS84) 中，轴顺序为 [纬度, 经度]，距离限制预计以米为单位。此函数使用 GeographicLib 库来解决反向测地线问题，使用地球椭球模型计算两点之间的距离。这是一种考虑了地球表面曲率的计算任意两点间距离的高精度方法，但也是最慢的。

示例

-- Note: the coordinates are in WGS84 and [latitude, longitude] axis order
-- Whats the distance between New York and Amsterdam (JFK and AMS airport)?
SELECT st_distance_spheroid(
st_point(40.6446, -73.7797),
st_point(52.3130, 4.7725)
);
----
5863418.7459356235
-- Roughly 5863km!

ST_Dump

签名

STRUCT(geom GEOMETRY, path INTEGER[])[] ST_Dump (geom GEOMETRY)

描述

将几何图形转储为子几何图形列表及其在原始几何图形中的“路径”。

您可以使用 UNNEST(res, recursive := true) 函数将结果结构体列表展开为多行。

示例

select st_dump('MULTIPOINT(1 2,3 4)'::geometry);
----
[{'geom': 'POINT(1 2)', 'path': [0]}, {'geom': 'POINT(3 4)', 'path': [1]}]

select unnest(st_dump('MULTIPOINT(1 2,3 4)'::geometry), recursive := true);
-- ┌─────────────┬─────────┐
-- │    geom     │  path   │
-- │  geometry   │ int32[] │
-- ├─────────────┼─────────┤
-- │ POINT (1 2) │ [1]     │
-- │ POINT (3 4) │ [2]     │
-- └─────────────┴─────────┘

ST_Extent_Approx

签名

BOX_2DF ST_Extent_Approx (geom GEOMETRY)

描述

如果可用，返回几何图形的近似外接矩形。

此函数仅在内部使用，并返回几何图形的缓存外接矩形（如果存在）。此函数将来可能会被删除或重命名。

ST_Force2D

签名

GEOMETRY ST_Force2D (geom GEOMETRY)

描述

强制几何图形的顶点具有 X 和 Y 分量。

此函数将删除输入几何图形中存在的任何 Z 和 M 值（如果存在）。如果输入几何图形已经是 2D，则按原样返回。

ST_Force3DM

签名

GEOMETRY ST_Force3DM (geom GEOMETRY, m DOUBLE)

描述

强制几何图形的顶点具有 X、Y 和 M 分量。

适用以下情况：

如果输入几何图形具有 Z 分量但没有 M 分量，Z 分量将被新 M 值替换。
如果输入几何图形具有 M 分量但没有 Z 分量，则按原样返回。
如果输入几何图形既有 Z 分量又有 M 分量，Z 分量将被删除。
否则，如果输入几何图形既没有 Z 也没有 M 分量，新 M 值将被添加到输入几何图形的顶点中。

ST_Force3DZ

签名

GEOMETRY ST_Force3DZ (geom GEOMETRY, z DOUBLE)

描述

强制几何图形的顶点具有 X、Y 和 Z 分量。

适用以下情况：

如果输入几何图形具有 M 分量但没有 Z 分量，M 分量将被新 Z 值替换。
如果输入几何图形具有 Z 分量但没有 M 分量，则按原样返回。
如果输入几何图形既有 Z 分量又有 M 分量，M 分量将被删除。
否则，如果输入几何图形既没有 Z 也没有 M 分量，新 Z 值将被添加到输入几何图形的顶点中。

ST_Force4D

签名

GEOMETRY ST_Force4D (geom GEOMETRY, z DOUBLE, m DOUBLE)

描述

强制几何图形的顶点具有 X、Y、Z 和 M 分量。

适用以下情况：

如果输入几何图形具有 Z 分量但没有 M 分量，新 M 值将被添加到输入几何图形的顶点中。
如果输入几何图形具有 M 分量但没有 Z 分量，新 Z 值将被添加到输入几何图形的顶点中。
如果输入几何图形既有 Z 分量又有 M 分量，几何图形将按原样返回。
否则，如果输入几何图形既没有 Z 也没有 M 分量，新 Z 和 M 值将被添加到输入几何图形的顶点中。

ST_GeomFromGeoJSON

签名

GEOMETRY ST_GeomFromGeoJSON (geojson JSON)
GEOMETRY ST_GeomFromGeoJSON (geojson VARCHAR)

示例

SELECT ST_GeomFromGeoJSON('{"type":"Point","coordinates":[1.0,2.0]}');
----
POINT (1 2)

ST_GeomFromHEXEWKB

签名

GEOMETRY ST_GeomFromHEXEWKB (hexwkb VARCHAR)

描述

从 HEX(E)WKB 编码字符串反序列化一个 GEOMETRY。

DuckDB 空间当前不区分 WKB 和 EWKB，因此 ST_GeomFromHEXWKB 和 ST_GeomFromHEXEWKB 互为别名。

ST_GeomFromHEXWKB

签名

GEOMETRY ST_GeomFromHEXWKB (hexwkb VARCHAR)

描述

从 HEX(E)WKB 编码字符串反序列化一个 GEOMETRY。

DuckDB 空间当前不区分 WKB 和 EWKB，因此 ST_GeomFromHEXWKB 和 ST_GeomFromHEXEWKB 互为别名。

ST_GeometryType

签名

ANY ST_GeometryType (geom GEOMETRY)
ANY ST_GeometryType (point POINT_2D)
ANY ST_GeometryType (linestring LINESTRING_2D)
ANY ST_GeometryType (polygon POLYGON_2D)
ANY ST_GeometryType (wkb WKB_BLOB)

描述

返回识别输入几何类型的 'GEOMETRY_TYPE' 枚举。可能的枚举返回类型为：POINT、LINESTRING、POLYGON、MULTIPOINT、MULTILINESTRING、MULTIPOLYGON 和 GEOMETRYCOLLECTION。

示例

SELECT DISTINCT ST_GeometryType(ST_GeomFromText('POINT(1 1)'));
----
POINT

ST_HasM

签名

BOOLEAN ST_HasM (geom GEOMETRY)
BOOLEAN ST_HasM (wkb WKB_BLOB)

示例

-- HasM for a 2D geometry
SELECT ST_HasM(ST_GeomFromText('POINT(1 1)'));
----
false

-- HasM for a 3DZ geometry
SELECT ST_HasM(ST_GeomFromText('POINT Z(1 1 1)'));
----
false

-- HasM for a 3DM geometry
SELECT ST_HasM(ST_GeomFromText('POINT M(1 1 1)'));
----
true

-- HasM for a 4D geometry
SELECT ST_HasM(ST_GeomFromText('POINT ZM(1 1 1 1)'));
----
true

ST_HasZ

签名

BOOLEAN ST_HasZ (geom GEOMETRY)
BOOLEAN ST_HasZ (wkb WKB_BLOB)

示例

-- HasZ for a 2D geometry
SELECT ST_HasZ(ST_GeomFromText('POINT(1 1)'));
----
false

-- HasZ for a 3DZ geometry
SELECT ST_HasZ(ST_GeomFromText('POINT Z(1 1 1)'));
----
true

-- HasZ for a 3DM geometry
SELECT ST_HasZ(ST_GeomFromText('POINT M(1 1 1)'));
----
false

-- HasZ for a 4D geometry
SELECT ST_HasZ(ST_GeomFromText('POINT ZM(1 1 1 1)'));
----
true

ST_Hilbert

签名

UINTEGER ST_Hilbert (x DOUBLE, y DOUBLE, bounds BOX_2D)
UINTEGER ST_Hilbert (geom GEOMETRY, bounds BOX_2D)
UINTEGER ST_Hilbert (geom GEOMETRY)
UINTEGER ST_Hilbert (box BOX_2D, bounds BOX_2D)
UINTEGER ST_Hilbert (box BOX_2DF, bounds BOX_2DF)

描述

将 X 和 Y 值编码为覆盖给定外接矩形的希尔伯特曲线索引。如果提供了几何图形，则使用近似外接矩形的中心点作为要编码的点。如果未提供外接矩形，希尔伯特曲线索引将映射到单精度浮点的完整范围。对于 BOX_2D 和 BOX_2DF 变体，使用框的中心作为要编码的点。

ST_IsRing

签名

BOOLEAN ST_IsRing (geom GEOMETRY)

描述

如果几何图形是环（同时满足 ST_IsClosed 和 ST_IsSimple），则返回 true。

ST_Length_Spheroid

签名

DOUBLE ST_Length_Spheroid (geom GEOMETRY)
DOUBLE ST_Length_Spheroid (line LINESTRING_2D)

描述

使用地球椭球模型，以米为单位返回输入几何图形的长度。

假定输入几何图形处于 EPSG:4326 坐标系 (WGS84) 中，轴顺序为 [纬度, 经度]，长度以米为单位返回。此函数使用 GeographicLib 库，通过地球椭球模型计算长度。这是一种考虑了地球曲率的计算线几何图形长度的高精度方法，但也是最慢的。

对于任何不是 LINESTRING、MULTILINESTRING 或包含线几何图形的 GEOMETRYCOLLECTION 的几何图形，返回 0.0。

ST_LineInterpolatePoints

签名

GEOMETRY ST_LineInterpolatePoints (line GEOMETRY, fraction DOUBLE, repeat BOOLEAN)

描述

返回沿线按总 2D 长度的分数插值的多点。

如果 repeat 为 false，结果是单个点（等同于 ST_LineInterpolatePoint），否则结果是多点，并在分数间隔处重复点。

ST_M

签名

DOUBLE ST_M (geom GEOMETRY)

示例

SELECT ST_M(ST_Point(1, 2, 3, 4))

ST_MMax

签名

DOUBLE ST_MMax (geom GEOMETRY)

示例

SELECT ST_MMax(ST_Point(1, 2, 3, 4))

ST_MMin

签名

DOUBLE ST_MMin (geom GEOMETRY)

示例

SELECT ST_MMin(ST_Point(1, 2, 3, 4))

ST_MakeLine

签名

GEOMETRY ST_MakeLine (geoms GEOMETRY[])
GEOMETRY ST_MakeLine (start GEOMETRY, end GEOMETRY)

示例

SELECT ST_MakeLine([ST_Point(0, 0), ST_Point(1, 1)]);
----
LINESTRING(0 0, 1 1)

ST_MakePolygon

签名

GEOMETRY ST_MakePolygon (shell GEOMETRY)
GEOMETRY ST_MakePolygon (shell GEOMETRY, holes GEOMETRY[])

示例

SELECT ST_MakePolygon(ST_LineString([ST_Point(0, 0), ST_Point(1, 0), ST_Point(1, 1), ST_Point(0, 0)]));

ST_MaximumInscribedCircle

签名

STRUCT(center GEOMETRY, nearest GEOMETRY, radius DOUBLE) ST_MaximumInscribedCircle (geom GEOMETRY)
STRUCT(center GEOMETRY, nearest GEOMETRY, radius DOUBLE) ST_MaximumInscribedCircle (geom GEOMETRY, tolerance DOUBLE)

描述

返回输入几何图形的最大内切圆，可选精度容差。

默认情况下，容差计算为 max(width, height) / 1000。返回值是一个结构体，包含圆心、几何图形边界上距离圆心最近的点以及圆的半径。

示例

-- Find the maximum inscribed circle of a square
SELECT ST_MaximumInscribedCircle(
    ST_GeomFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))')
);
----
{'center': POINT (5 5), 'nearest': POINT (5 0), 'radius': 5.0}

ST_MinimumRotatedRectangle

签名

GEOMETRY ST_MinimumRotatedRectangle (geom GEOMETRY)

描述

返回包围输入几何图形的最小旋转矩形，通过使用旋转矩形寻找面积最小的外接框，而不是像 ST_Envelope() 那样仅取最高和最低坐标值。

ST_Multi

签名

GEOMETRY ST_Multi (geom GEOMETRY)

描述

将单个几何图形转变为多重几何图形。

如果几何图形已经是多重几何图形，则按原样返回。

示例

SELECT ST_Multi(ST_GeomFromText('POINT(1 2)'));
----
MULTIPOINT (1 2)

SELECT ST_Multi(ST_GeomFromText('LINESTRING(1 1, 2 2)'));
----
MULTILINESTRING ((1 1, 2 2))

SELECT ST_Multi(ST_GeomFromText('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'));
----
MULTIPOLYGON (((0 0, 0 1, 1 1, 1 0, 0 0)))

ST_NGeometries

签名

INTEGER ST_NGeometries (geom GEOMETRY)

描述

返回集合几何图形中的组件几何图形数量。如果输入几何图形不是集合，此函数根据几何图形是否为空返回 0 或 1。

ST_Node

签名

GEOMETRY ST_Node (geom GEOMETRY)

描述

返回一个“节点化”的 MultiLinestring，由组合一组输入 linestring 并在此相交处添加额外顶点产生。

示例

-- Create a noded multilinestring from two intersecting lines
SELECT ST_Node(
    ST_GeomFromText('MULTILINESTRING((0 0, 2 2), (0 2, 2 0))')
);
----
MULTILINESTRING ((0 0, 1 1), (1 1, 2 2), (0 2, 1 1), (1 1, 2 0))

ST_NumGeometries

签名

INTEGER ST_NumGeometries (geom GEOMETRY)

描述

返回集合几何图形中的组件几何图形数量。如果输入几何图形不是集合，此函数根据几何图形是否为空返回 0 或 1。

ST_Perimeter_Spheroid

签名

DOUBLE ST_Perimeter_Spheroid (geom GEOMETRY)
DOUBLE ST_Perimeter_Spheroid (poly POLYGON_2D)

描述

使用地球椭球模型，以米为单位返回周长的长度。

假定输入几何图形处于 EPSG:4326 坐标系 (WGS84) 中，轴顺序为 [纬度, 经度]，长度以米为单位返回。此函数使用 GeographicLib 库，通过地球椭球模型计算周长。这是一种考虑了地球曲率的计算多边形周长的高精度方法，但也是最慢的。

对于任何不是 POLYGON、MULTIPOLYGON 或包含多边形几何图形的 GEOMETRYCOLLECTION 的几何图形，返回 0.0。

ST_Points

签名

GEOMETRY ST_Points (geom GEOMETRY)

示例

select st_points('LINESTRING(1 1, 2 2)'::geometry);
----
MULTIPOINT (1 1, 2 2)

select st_points('MULTIPOLYGON Z EMPTY'::geometry);
----
MULTIPOINT Z EMPTY

ST_Polygonize

签名

GEOMETRY ST_Polygonize (geometries GEOMETRY[])

示例

-- Create a polygon from a closed linestring ring
SELECT ST_Polygonize([
    ST_GeomFromText('LINESTRING(0 0, 0 10, 10 10, 10 0, 0 0)')
]);
---
GEOMETRYCOLLECTION (POLYGON ((0 0, 0 10, 10 10, 10 0, 0 0)))

ST_QuadKey

签名

VARCHAR ST_QuadKey (longitude DOUBLE, latitude DOUBLE, level INTEGER)
VARCHAR ST_QuadKey (point GEOMETRY, level INTEGER)

描述

计算给定层级上给定经纬度点的 quadkey。请注意，参数顺序为经度, 纬度。

level 必须在 1 到 23 之间（含边界）。

输入的坐标将被限制在地球的经纬度范围内（经度在 -180 到 180 之间，纬度在 -85.05112878 到 85.05112878 之间）。

如果输入几何图形不是 POINT，几何图形重载会报错。

示例

SELECT ST_QuadKey(st_point(11.08, 49.45), 10);
----
1333203202

ST_TileEnvelope

签名

GEOMETRY ST_TileEnvelope (tile_zoom INTEGER, tile_x INTEGER, tile_y INTEGER)

描述

ST_TileEnvelope 标量函数根据指定的缩放级别和瓦片索引生成瓦片外接矩形多边形。

这在 MVT 生成中用于选择与瓦片范围对应的要素。外接矩形位于 Web 墨卡托坐标参考系统 (EPSG:3857) 中。瓦片金字塔从缩放级别 0 开始，对应于全球的一个单一瓦片。每个缩放级别使每个方向的瓦片数量加倍，即缩放级别 1 是 2x2 瓦片，缩放级别 2 是 4x4 瓦片，依此类推。瓦片索引从左上角的 [x=0, y=0] 开始，并向下和向右增加。例如，在缩放级别 2，右上角的瓦片是 [x=3, y=0]，左下角的瓦片是 [x=0, y=3]，右下角是 [x=3, y=3]。

SELECT ST_TileEnvelope(2, 3, 1);

示例

SELECT ST_TileEnvelope(2, 3, 1);
┌───────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                         st_tileenvelope(2, 3, 1)                                          │
│                                                 geometry                                                  │
├───────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ POLYGON ((1.00188E+07 0, 1.00188E+07 1.00188E+07, 2.00375E+07 1.00188E+07, 2.00375E+07 0, 1.00188E+07 0)) │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────┘

ST_Touches

签名

BOOLEAN ST_Touches (geom1 GEOMETRY, geom2 GEOMETRY)

描述

如果几何图形接触，则返回 true。

ST_Transform

签名

BOX_2D ST_Transform (box BOX_2D, source_crs VARCHAR, target_crs VARCHAR)
BOX_2D ST_Transform (box BOX_2D, source_crs VARCHAR, target_crs VARCHAR, always_xy BOOLEAN)
POINT_2D ST_Transform (point POINT_2D, source_crs VARCHAR, target_crs VARCHAR)
POINT_2D ST_Transform (point POINT_2D, source_crs VARCHAR, target_crs VARCHAR, always_xy BOOLEAN)
GEOMETRY ST_Transform (geom GEOMETRY, source_crs VARCHAR, target_crs VARCHAR)
GEOMETRY ST_Transform (geom GEOMETRY, source_crs VARCHAR, target_crs VARCHAR, always_xy BOOLEAN)

描述

在两个坐标系之间转换几何图形。

可以使用 PROJ 库支持的任何格式指定源坐标系和目标坐标系。

第三个可选参数 always_xy 可用于强制将输入和输出几何图形解释为具有 [东向, 北向] 坐标轴顺序，而不管源和目标坐标系定义如何。这在转换到/从 WGS84/EPSG:4326 坐标系（大多数人听到“经度”/“纬度”或“GPS 坐标”时所想的）时特别有用，该系统定义为具有 [纬度, 经度] 轴顺序，尽管在实践中通常使用 [经度, 纬度]（例如在 GeoJSON 中）。更多详细信息可在 PROJ 文档中找到。

DuckDB 空间扩展自带了一份静态的 PROJ 坐标系数据库，因此如果您在系统上安装了 PROJ，可用的坐标系可能与 GIS 软件中可用的坐标系有所不同。

示例

-- Transform a geometry from EPSG:4326 to EPSG:3857 (WGS84 to WebMercator)
-- Note that since WGS84 is defined as having a [latitude, longitude] axis order
-- we follow the standard and provide the input geometry using that axis order,
-- but the output will be [easting, northing] because that is what's defined by
-- WebMercator.

SELECT
    ST_Transform(
        st_point(52.373123, 4.892360),
        'EPSG:4326',
        'EPSG:3857'
    );
----
POINT (544615.0239773799 6867874.103539125)

-- Alternatively, let's say we got our input point from e.g. a GeoJSON file,
-- which uses WGS84 but with [longitude, latitude] axis order. We can use the
-- `always_xy` parameter to force the input geometry to be interpreted as having
-- a [northing, easting] axis order instead, even though the source coordinate
-- reference system definition (WGS84) says otherwise.

SELECT 
    ST_Transform(
        -- note the axis order is reversed here
        st_point(4.892360, 52.373123),
        'EPSG:4326',
        'EPSG:3857',
        always_xy := true
    );
----
POINT (544615.0239773799 6867874.103539125)

-- Transform a geometry from OSG36 British National Grid EPSG:27700 to EPSG:4326 WGS84
-- Standard transform is often fine for the first few decimal places before being wrong
-- which could result in an error starting at about 10m and possibly much more
SELECT ST_Transform(bng, 'EPSG:27700', 'EPSG:4326', xy := true) AS without_grid_file
FROM (SELECT ST_GeomFromText('POINT( 170370.718 11572.405 )') AS bng);
----
POINT (-5.202992651563592 49.96007490162923)

-- By using an official NTv2 grid file, we can reduce the error down around the 9th decimal place
-- which in theory is below a millimetre, and in practice unlikely that your coordinates are that precise
-- British National Grid "NTv2 format files" download available here:
-- https://www.ordnancesurvey.co.uk/products/os-net/for-developers
SELECT ST_Transform(bng
    , '+proj=tmerc +lat_0=49 +lon_0=-2 +k=0.9996012717 +x_0=400000 +y_0=-100000 +ellps=airy +units=m +no_defs +nadgrids=/full/path/to/OSTN15-NTv2/OSTN15_NTv2_OSGBtoETRS.gsb +type=crs'
    , 'EPSG:4326', xy := true) AS with_grid_file
FROM (SELECT ST_GeomFromText('POINT( 170370.718 11572.405 )') AS bng) t;
----
POINT (-5.203046090608746 49.96006137018598)

ST_Union

签名

GEOMETRY ST_Union (geom1 GEOMETRY, geom2 GEOMETRY)

描述

返回两个几何图形的并集。

ST_VoronoiDiagram

签名

GEOMETRY ST_VoronoiDiagram (geom GEOMETRY)

描述

返回提供的 MultiPoint 几何图形的泰森多边形（Voronoi）图。

ST_Within

签名

BOOLEAN ST_Within (geom1 POINT_2D, geom2 POLYGON_2D)
BOOLEAN ST_Within (geom1 GEOMETRY, geom2 GEOMETRY)

描述

如果第一个几何图形在第二个几何图形内，则返回 true。

ST_WithinProperly

签名

BOOLEAN ST_WithinProperly (geom1 GEOMETRY, geom2 GEOMETRY)

描述

如果第一个几何图形“正确”包含在第二个几何图形中，则返回 true。

此函数的功能与 ST_ContainsProperly 相同，但参数已交换。

ST_X

签名

DOUBLE ST_X (geom GEOMETRY)
DOUBLE ST_X (point POINT_2D)

描述

返回点几何图形的 X 坐标。

示例

SELECT ST_X(ST_Point(1, 2))

ST_XMax

签名

DOUBLE ST_XMax (geom GEOMETRY)
DOUBLE ST_XMax (point POINT_2D)
DOUBLE ST_XMax (line LINESTRING_2D)
DOUBLE ST_XMax (polygon POLYGON_2D)
DOUBLE ST_XMax (box BOX_2D)
FLOAT ST_XMax (box BOX_2DF)

描述

返回几何图形的最大 X 坐标。

示例

SELECT ST_XMax(ST_Point(1, 2))

ST_XMin

签名

DOUBLE ST_XMin (geom GEOMETRY)
DOUBLE ST_XMin (point POINT_2D)
DOUBLE ST_XMin (line LINESTRING_2D)
DOUBLE ST_XMin (polygon POLYGON_2D)
DOUBLE ST_XMin (box BOX_2D)
FLOAT ST_XMin (box BOX_2DF)

描述

返回几何图形的最小 X 坐标。

示例

SELECT ST_XMin(ST_Point(1, 2))

ST_Y

签名

DOUBLE ST_Y (geom GEOMETRY)
DOUBLE ST_Y (point POINT_2D)

描述

返回点几何图形的 Y 坐标。

示例

SELECT ST_Y(ST_Point(1, 2))

ST_YMax

签名

DOUBLE ST_YMax (geom GEOMETRY)
DOUBLE ST_YMax (point POINT_2D)
DOUBLE ST_YMax (line LINESTRING_2D)
DOUBLE ST_YMax (polygon POLYGON_2D)
DOUBLE ST_YMax (box BOX_2D)
FLOAT ST_YMax (box BOX_2DF)

描述

返回几何图形的最大 Y 坐标。

示例

SELECT ST_YMax(ST_Point(1, 2))

ST_YMin

签名

DOUBLE ST_YMin (geom GEOMETRY)
DOUBLE ST_YMin (point POINT_2D)
DOUBLE ST_YMin (line LINESTRING_2D)
DOUBLE ST_YMin (polygon POLYGON_2D)
DOUBLE ST_YMin (box BOX_2D)
FLOAT ST_YMin (box BOX_2DF)

描述

返回几何图形的最小 Y 坐标。

示例

SELECT ST_YMin(ST_Point(1, 2))

ST_Z

签名

DOUBLE ST_Z (geom GEOMETRY)

描述

返回点几何图形的 Z 坐标。

示例

SELECT ST_Z(ST_Point(1, 2, 3))

ST_ZMFlag

签名

UTINYINT ST_ZMFlag (geom GEOMETRY)
UTINYINT ST_ZMFlag (wkb WKB_BLOB)

描述

返回指示输入几何图形中 Z 和 M 值存在情况的标志。0 = 无 Z 或 M 值；1 = 仅 M 值；2 = 仅 Z 值；3 = Z 和 M 值。

示例

-- ZMFlag for a 2D geometry
SELECT ST_ZMFlag(ST_GeomFromText('POINT(1 1)'));
----
0

-- ZMFlag for a 3DZ geometry
SELECT ST_ZMFlag(ST_GeomFromText('POINT Z(1 1 1)'));
----
2

-- ZMFlag for a 3DM geometry
SELECT ST_ZMFlag(ST_GeomFromText('POINT M(1 1 1)'));
----
1

-- ZMFlag for a 4D geometry
SELECT ST_ZMFlag(ST_GeomFromText('POINT ZM(1 1 1 1)'));
----
3

ST_ZMax

签名

DOUBLE ST_ZMax (geom GEOMETRY)

描述

返回几何图形的最大 Z 坐标。

示例

SELECT ST_ZMax(ST_Point(1, 2, 3))

ST_ZMin

签名

DOUBLE ST_ZMin (geom GEOMETRY)

描述

返回几何图形的最小 Z 坐标。

示例

SELECT ST_ZMin(ST_Point(1, 2, 3))

聚合函数

ST_CoverageInvalidEdges_Agg

签名

GEOMETRY ST_CoverageInvalidEdges_Agg (col0 GEOMETRY)
GEOMETRY ST_CoverageInvalidEdges_Agg (col0 GEOMETRY, col1 DOUBLE)

描述

返回覆盖几何图形的无效边。

ST_CoverageSimplify_Agg

签名

GEOMETRY ST_CoverageSimplify_Agg (col0 GEOMETRY, col1 DOUBLE)
GEOMETRY ST_CoverageSimplify_Agg (col0 GEOMETRY, col1 DOUBLE, col2 BOOLEAN)

描述

在保持覆盖完整性的同时简化一组几何图形。

ST_CoverageUnion_Agg

签名

GEOMETRY ST_CoverageUnion_Agg (col0 GEOMETRY)

描述

在保持覆盖完整性的同时合并一组几何图形。

ST_Envelope_Agg

签名

GEOMETRY ST_Envelope_Agg (col0 GEOMETRY)

描述

ST_Extent_Agg 的别名。

计算包含一组输入几何图形的最小外接矩形多边形。

示例

SELECT ST_Extent_Agg(geom) FROM UNNEST([ST_Point(1,1), ST_Point(5,5)]) AS _(geom);
-- POLYGON ((1 1, 1 5, 5 5, 5 1, 1 1))

ST_Extent_Agg

签名

GEOMETRY ST_Extent_Agg (col0 GEOMETRY)

描述

计算包含一组输入几何图形的最小外接矩形多边形。

示例

SELECT ST_Extent_Agg(geom) FROM UNNEST([ST_Point(1,1), ST_Point(5,5)]) AS _(geom);
-- POLYGON ((1 1, 1 5, 5 5, 5 1, 1 1))

ST_Intersection_Agg

签名

GEOMETRY ST_Intersection_Agg (col0 GEOMETRY)

描述

计算一组几何图形的交集。

ST_MemUnion_Agg

签名

GEOMETRY ST_MemUnion_Agg (col0 GEOMETRY)

描述

计算一组输入几何图形的并集。“较慢，但可能比 ST_UnionAgg 更节省内存，因为每个几何图形都是单独合并到并集中，而不是一次性全部合并。

ST_Union_Agg

签名

GEOMETRY ST_Union_Agg (col0 GEOMETRY)

描述

计算一组输入几何图形的并集。

宏函数

ST_Rotate

签名

GEOMETRY ST_Rotate (geom GEOMETRY, radians double)

描述

ST_RotateZ 的别名。

ST_RotateX

签名

GEOMETRY ST_RotateX (geom GEOMETRY, radians double)

描述

围绕 X 轴旋转几何图形。这是调用 ST_Affine 的简写宏。

示例

-- Rotate a 3D point 90 degrees (π/2 radians) around the X-axis
SELECT ST_RotateX(ST_GeomFromText('POINT Z(0 1 0)'), pi()/2);
----
POINT Z (0 0 1)

ST_RotateY

签名

GEOMETRY ST_RotateY (geom GEOMETRY, radians double)

描述

围绕 Y 轴旋转几何图形。这是调用 ST_Affine 的简写宏。

示例

-- Rotate a 3D point 90 degrees (π/2 radians) around the Y-axis
SELECT ST_RotateY(ST_GeomFromText('POINT Z(1 0 0)'), pi()/2);
----
POINT Z (0 0 -1)

ST_RotateZ

签名

GEOMETRY ST_RotateZ (geom GEOMETRY, radians double)

描述

围绕 Z 轴旋转几何图形。这是调用 ST_Affine 的简写宏。

示例

-- Rotate a point 90 degrees (π/2 radians) around the Z-axis
SELECT ST_RotateZ(ST_Point(1, 0), pi()/2);
----
POINT (0 1)

ST_Scale

签名

GEOMETRY ST_Scale (geom GEOMETRY, xs double, ys double, zs double)
GEOMETRY ST_Scale (geom GEOMETRY, xs double, ys double)

ST_TransScale

签名

GEOMETRY ST_TransScale (geom GEOMETRY, dx double, dy double, xs double, ys double)

描述

在 X 和 Y 方向平移然后缩放几何图形。这是调用 ST_Affine 的简写宏。

示例

-- Translate by (1, 2) then scale by (2, 3)
SELECT ST_TransScale(ST_Point(1, 1), 1, 2, 2, 3);
----
POINT (4 9)

ST_Translate

签名

GEOMETRY ST_Translate (geom GEOMETRY, dx double, dy double, dz double)
GEOMETRY ST_Translate (geom GEOMETRY, dx double, dy double)

表函数

ST_Drivers

签名

ST_Drivers ()

描述

返回支持的 GDAL 驱动程序和文件格式列表。

请注意，并非所有这些驱动程序都经过充分测试。有些可能需要传递额外的选项才能正常工作。如果您遇到任何问题，请首先查阅 GDAL 文档。

示例

SELECT * FROM ST_Drivers();

ST_GeneratePoints

签名

ST_GeneratePoints (col0 BOX_2D, col1 BIGINT)
ST_GeneratePoints (col0 BOX_2D, col1 BIGINT, col2 BIGINT)

描述

在指定的外接矩形内生成一组随机点。

接受一个外接矩形 (min_x, min_y, max_x, max_y)、要生成的点的数量以及可选的随机数生成器种子。

示例

SELECT * FROM ST_GeneratePoints({min_x: 0, min_y:0, max_x:10, max_y:10}::BOX_2D, 5, 42);

ST_Read

签名

ST_Read (col0 VARCHAR, keep_wkb BOOLEAN, max_batch_size INTEGER, sequential_layer_scan BOOLEAN, layer VARCHAR, sibling_files VARCHAR[], spatial_filter WKB_BLOB, spatial_filter_box BOX_2D, allowed_drivers VARCHAR[], open_options VARCHAR[])

描述

使用 GDAL 库读取并导入各种地理空间文件格式。

ST_Read 表函数基于 GDAL 转换库，支持将各种地理空间矢量文件格式的读取方式如同 DuckDB 表一样。

有关受支持文件格式和驱动程序的列表，请参见 ST_Drivers。

除 path 参数外，所有参数均为可选。

参数	类型	描述
`path`	VARCHAR	要读取的文件的路径。必填。
`sequential_layer_scan`	BOOLEAN	如果设置为 true，表函数将按顺序扫描所有图层并返回与给定图层名称匹配的第一个图层。某些驱动程序（例如 OSM 驱动程序）需要此项才能正常工作。
`spatial_filter`	WKB_BLOB	如果设置为 WKB blob，表函数将仅返回与给定 WKB 几何图形相交的行。某些驱动程序可能原生支持高效的空间过滤，在这种情况下，过滤操作将被下推。否则，过滤由 GDAL 执行，这可能要慢得多。
`open_options`	VARCHAR[]	传递给 GDAL 驱动程序以控制文件打开方式的键值对列表。例如，GeoJSON 驱动程序支持 FLATTEN_NESTED_ATTRIBUTES=YES 选项来展平嵌套属性。
`layer`	VARCHAR	要从中读取的文件中的图层名称。如果为 NULL，则返回第一个图层。也可以是图层索引（从 0 开始）。
`allowed_drivers`	VARCHAR[]	允许用于打开文件的 GDAL 驱动程序名称列表。如果为空，则允许所有驱动程序。
`sibling_files`	VARCHAR[]	打开文件所需的同级文件列表。例如，ESRI Shapefile 驱动程序要求存在 .shx 文件。尽管大多数时候这些可以自动发现。
`spatial_filter_box`	BOX_2D	如果设置为 BOX_2D，表函数将仅返回与给定外接矩形相交的行。类似于 spatial_filter。
`keep_wkb`	BOOLEAN	如果设置，表函数将返回类型为 WKB_BLOB（可转换为 BLOB）的 wkb_geometry 列中的几何图形，而不是 GEOMETRY。如果您想在 DuckDB 中使用 DuckDB 空间尚不支持在 GEOMETRY 类型中表示的更特殊的几何子类型，这将非常有用。

请注意，GDAL 是单线程的，因此此表函数将无法充分利用并行性。

通过使用 ST_Read，空间扩展还为常见的地理空间文件格式提供了“替代扫描”，允许您直接查询这些格式的文件，就像查询表一样。

SELECT * FROM './path/to/some/shapefile/dataset.shp';

实际上，这只是调用 ST_Read 的语法糖，因此性能没有差异。如果您想传递额外的选项，应该直接使用 ST_Read 表函数。

目前通过文件扩展名识别以下格式：

格式	扩展
ESRI ShapeFile	.shp
GeoPackage	.gpkg
FlatGeoBuf	.fgb

示例

-- Read a Shapefile
SELECT * FROM ST_Read('some/file/path/filename.shp');

-- Read a GeoJSON file
CREATE TABLE my_geojson_table AS SELECT * FROM ST_Read('some/file/path/filename.json');

ST_ReadOSM

签名

ST_ReadOSM (col0 VARCHAR)

描述

ST_ReadOsm() 表函数支持直接从 .osm.pbf 文件读取压缩的 OpenStreetMap 数据。

此函数使用多线程和零拷贝 protobuf 解析，使其比使用 ST_Read() OSM 驱动程序快得多，但它仅输出原始 OSM 数据（节点、路、关系），而不构造任何几何图形。对于简单的节点实体（如 PoI），您可以轻松构造 POINT 几何图形，但也可以通过在 SQL 中手动联接引用和节点来构造 LINESTRING 和 POLYGON 几何图形，尽管可用内存通常是一个限制因素。ST_ReadOSM() 函数还提供了一个“替代扫描”以支持像表一样直接读取文件。不过，这只是调用 ST_ReadOSM() 的语法糖。示例：

SELECT * FROM 'tmp/data/germany.osm.pbf' LIMIT 5;

示例

SELECT *
FROM ST_ReadOSM('tmp/data/germany.osm.pbf')
WHERE tags['highway'] != []
LIMIT 5;
----
┌──────────────────────┬────────┬──────────────────────┬─────────┬────────────────────┬────────────┬───────────┬────────────────────────┐
│         kind         │   id   │         tags         │  refs   │        lat         │    lon     │ ref_roles │       ref_types        │
│ enum('node', 'way'…  │ int64  │ map(varchar, varch…  │ int64[] │       double       │   double   │ varchar[] │ enum('node', 'way', …  │
├──────────────────────┼────────┼──────────────────────┼─────────┼────────────────────┼────────────┼───────────┼────────────────────────┤
│ node                 │ 122351 │ {bicycle=yes, butt…  │         │         53.5492951 │   9.977553 │           │                        │
│ node                 │ 122397 │ {crossing=no, high…  │         │ 53.520990100000006 │ 10.0156924 │           │                        │
│ node                 │ 122493 │ {TMC:cid_58:tabcd_…  │         │ 53.129614600000004 │  8.1970173 │           │                        │
│ node                 │ 123566 │ {highway=traffic_s…  │         │ 54.617268200000005 │  8.9718171 │           │                        │
│ node                 │ 125801 │ {TMC:cid_58:tabcd_…  │         │ 53.070685000000005 │  8.7819939 │           │                        │
└──────────────────────┴────────┴──────────────────────┴─────────┴────────────────────┴────────────┴───────────┴────────────────────────┘

ST_ReadSHP

签名

ST_ReadSHP (col0 VARCHAR, encoding VARCHAR)

描述

在不依赖 GDAL 库的情况下读取 Shapefile。

ST_Read_Meta

签名

ST_Read_Meta (col0 VARCHAR)
ST_Read_Meta (col0 VARCHAR[])

描述

使用 GDAL 库读取各种地理空间文件格式的元数据。

ST_Read_Meta 表函数与 ST_Read 表函数配套使用，但它不是读取文件的内容，而是扫描元数据。由于底层 GDAL 库的数据模型相当灵活，大多数有趣的元数据都在返回的 layers 列中，这是一个由 DuckDB STRUCT 和 LIST 类型组成的略显复杂的嵌套结构。

示例

-- Find the coordinate reference system authority name and code for the first layers first geometry column in the file
SELECT
    layers[1].geometry_fields[1].crs.auth_name as name,
    layers[1].geometry_fields[1].crs.auth_code as code
FROM st_read_meta('../../tmp/data/amsterdam_roads.fgb');

关于此页面

行为准则商标使用指南