空间函数 – 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 是否在目标距离（米）内
`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`	返回沿线按总二维长度的某个分数插值的点。
`ST_LineInterpolatePoints`	返回沿线按总二维长度的某个分数插值的多点。
`ST_LineMerge`	“合并”输入线几何体，可选地考虑方向。
`ST_LineString2DFromWKB`	从 WKB 编码的 blob 反序列化 LINESTRING_2D
`ST_LineSubstring`	返回线在总二维长度的两个分数之间的子字符串。
`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，通过组合输入线串集合并在其相交处添加额外顶点生成。
`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)

示例

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 是否在目标距离（米）内

假定输入几何体位于 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 值，此函数将删除它们。如果输入几何体已经是二维的，则按原样返回。

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)

描述

返回沿线按总二维长度的某个分数插值的多点。

如果 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，通过组合输入线串集合并在其相交处添加额外顶点生成。

示例

-- 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 Mercator 坐标参考系统 (EPSG:3857) 中。瓦片金字塔从缩放级别 0 开始，对应于世界的一个瓦片。每个缩放级别都会将每个方向的瓦片数量加倍，例如缩放级别 1 为 2 瓦片宽 2 瓦片高，缩放级别 2 为 4 瓦片宽 4 瓦片高，依此类推。瓦片索引从左上角 [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 practise 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_geometry 列中返回几何体，类型为 WKB_BLOB（可转换为 BLOB），而不是 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');