处理地理坐标的函数 - ClickHouse Documentation

greatCircleDistance

使用大圆距离公式计算地球表面上两点之间的距离。

greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

输入参数

lon1Deg — 第一个点的经度 (以度为单位) 。范围：[-180°, 180°]。
lat1Deg — 第一个点的纬度 (以度为单位) 。范围：[-90°, 90°]。
lon2Deg — 第二个点的经度 (以度为单位) 。范围：[-180°, 180°]。
lat2Deg — 第二个点的纬度 (以度为单位) 。范围：[-90°, 90°]。

正值表示北纬和东经，负值表示南纬和西经。 返回值 地球表面两点之间的距离，单位为米。当输入参数值超出范围时，会抛出异常。示例

SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673) AS greatCircleDistance

┌─greatCircleDistance─┐
│            14128352 │
└─────────────────────┘

geoDistance

与 greatCircleDistance 类似，但它计算的是 WGS-84 椭球体上的距离，而不是球面上的距离。这种方法对地球大地水准面的近似更精确。其性能与 greatCircleDistance 相同 (没有性能损失) 。建议使用 geoDistance 来计算地球表面的距离。技术说明：对于彼此足够接近的点，我们使用平面近似来计算距离，并采用坐标中点处切平面上的度量。

geoDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

输入参数

lon1Deg — 第一个点的经度 (单位：度) 。范围：[-180°, 180°]。
lat1Deg — 第一个点的纬度 (单位：度) 。范围：[-90°, 90°]。
lon2Deg — 第二个点的经度 (单位：度) 。范围：[-180°, 180°]。
lat2Deg — 第二个点的纬度 (单位：度) 。范围：[-90°, 90°]。

正值表示北纬和东经，负值表示南纬和西经。 返回值 地球表面两点之间的距离，单位为米。当输入参数的值超出上述范围时，会引发异常。示例

SELECT geoDistance(38.8976, -77.0366, 39.9496, -75.1503) AS geoDistance

┌─geoDistance─┐
│   212458.73 │
└─────────────┘

greatCircleAngle

使用大圆距离公式计算地球表面两点之间的中心角。

greatCircleAngle(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

输入参数

lon1Deg — 第一个点的经度，单位为度。
lat1Deg — 第一个点的纬度，单位为度。
lon2Deg — 第二个点的经度，单位为度。
lat2Deg — 第二个点的纬度，单位为度。

返回值 两点之间的中心角，单位为度。示例

SELECT greatCircleAngle(0, 0, 45, 0) AS arc

┌─arc─┐
│  45 │
└─────┘

geoToUTM

将 WGS84 地理坐标 (longitude, latitude) 转换为 Universal Transverse Mercator (UTM) 坐标。 UTM 是一组由 60 个横轴墨卡托投影构成的坐标系统，每个投影覆盖一个宽 6° 的经度带，用于将地理坐标映射到以米为单位的平面网格。除非显式指定 zone，否则会根据经度自动选择分区，并应用针对挪威和斯瓦尔巴的标准例外规则。UTM 仅定义于纬度范围 [-80°, 84°]；极地区域使用单独的 UPS 系统。

geoToUTM(longitude, latitude[, zone])

参数

longitude — 以度为单位的经度。范围：[-180°, 180°]。Float32/Float64。
latitude — 以度为单位的纬度。范围：[-80°, 84°]。Float32/Float64。
zone — 可选。将投影强制指定到此 UTM 分区，而不是自动选择。范围：[1, 60]。(U)Int*。

返回值 一个命名元组 (easting, northing, zone, band)：easting 和 northing 以米为单位 (Float64) ，UTM zone 编号 (UInt8) ，以及 MGRS 纬度 band 字母 (FixedString(1)) 。band 为 'N' 或其后字母时，表示北半球。当纬度超出 [-80°, 84°] 或经度超出 [-180°, 180°] 时，会抛出异常。示例

SELECT geoToUTM(2.294497, 48.858222) AS utm; -- Eiffel Tower

(448251.5978370684,5411935.125629659,31,'U')

UTMToGeo

将 UTM 坐标还原为 WGS84 地理坐标 (longitude, latitude)。这是 geoToUTM 的逆运算。

UTMToGeo(easting, northing, zone, is_north)

参数

easting — 以米为单位的东向坐标 (包含 500000 m 的假东向偏移) 。(U)Int*/Float*。
northing — 以米为单位的北向坐标 (包含南半球 10000000 m 的假北向偏移) 。(U)Int*/Float*。
zone — UTM 分区编号。范围：[1, 60]。(U)Int*。
is_north — 半球：1 表示北半球，0 表示南半球。(U)Int*。

返回值 以度为单位的命名元组 (longitude, latitude)。Tuple(Float64, Float64)。示例

SELECT UTMToGeo(448251.6, 5411935.13, 31, 1) AS coord;

(2.2944970289079203,48.85822204127082)

geoToMGRS

将 WGS84 地理坐标 (longitude, latitude) 编码为 Military Grid Reference System (MGRS) 字符串。该字符串的格式为 <zone><band><100km square><easting><northing>，例如 31UDQ4825111935。precision 参数控制 easting 和 northing 各自使用的位数：5 (默认) 表示 1 m，4 表示 10 m，3 表示 100 m，2 表示 1 km，1 表示 10 km，0 则仅表示 100 km 网格方块。MGRS 仅对纬度范围在 [-80°, 84°] 内的坐标有定义。

geoToMGRS(longitude, latitude[, precision])

参数

longitude — 以度为单位的经度。范围：[-180°, 180°]。Float32/Float64。
latitude — 以度为单位的纬度。范围：[-80°, 84°]。Float32/Float64。
precision — 可选。东向坐标和北向坐标各自保留的位数。默认值：5。范围：[0, 5]。(U)Int*。

返回值 MGRS 坐标字符串。String。示例

SELECT geoToMGRS(2.294497, 48.858222) AS mgrs, geoToMGRS(2.294497, 48.858222, 3) AS mgrs_100m;

┌─mgrs────────────┬─mgrs_100m───┐
│ 31UDQ4825111935 │ 31UDQ482119 │
└─────────────────┴─────────────┘

MGRSToGeo

将 MGRS 字符串解码为 WGS84 地理坐标 (longitude, latitude)。这是 geoToMGRS 的逆运算。返回的 Point 是所指网格方格的中心点，因此结果的精度与字符串中编码的精度一致。输入中的空白字符会被忽略，字母不区分大小写。

MGRSToGeo(mgrs)

参数

mgrs — 要解码的 MGRS 参考字符串。String/FixedString。

返回值 以度为单位的命名元组 (longitude, latitude)。Tuple(Float64, Float64)。示例

SELECT MGRSToGeo('31UDQ4825111935') AS coord;

(2.294495618908297,48.85822536113692)

pointInEllipses

判断该点是否位于至少一个椭圆内。坐标采用笛卡尔坐标系中的几何坐标。

pointInEllipses(x, y, x₀, y₀, a₀, b₀,...,xₙ, yₙ, aₙ, bₙ)

输入参数

x, y — 平面上一点的坐标。
xᵢ, yᵢ — 第 i 个椭圆中心的坐标。
aᵢ, bᵢ — 第 i 个椭圆的轴长，以 x、y 坐标单位表示。

输入参数的总数必须为 2+4⋅n，其中 n 是椭圆的数量。 返回值 如果该点位于至少一个椭圆内，则返回 1；否则返回 0。示例

SELECT pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)

┌─pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)─┐
│                                               1 │
└─────────────────────────────────────────────────┘

pointInPolygon

检查该点是否位于平面上的多边形内。

pointInPolygon((x, y), [(a, b), (c, d) ...], ...)

输入值

(x, y) — 平面上某一点的坐标。数据类型 — Tuple — 由两个数字组成的元组，或 Point。
[(a, b), (c, d) ...] — 多边形顶点。数据类型 — Array 或 Ring。每个顶点用一对坐标 (a, b) 表示。顶点应按顺时针或逆时针顺序指定。顶点最少为 3 个。
该函数支持带孔的多边形 (镂空区域) 。数据类型 — Polygon。可以将整个 Polygon 作为第二个参数传入，也可以先传入外环，再将每个孔分别作为额外参数传入。
该函数也支持 MultiPolygon。数据类型 — MultiPolygon。可以将整个 MultiPolygon 作为第二个参数传入，也可以将其中的每个组成多边形分别作为独立参数传入。
多边形参数也可以是包含多边形形态值 (Ring、Polygon 或 MultiPolygon) 的 Geometry 列。

这些多边形形态类型 (Ring、Polygon、MultiPolygon 和 Geometry) 既可以作为常量传入，也可以作为普通 (非常量) 表列传入。当多边形通过多个独立参数提供时 (先传外环再传孔，或传入一个 MultiPolygon 中的多个多边形) ，所有这些参数都必须是常量。 返回值 如果点位于多边形内部，则返回 1；否则返回 0。如果点位于多边形边界上，函数可能返回 0 或 1。示例

SELECT pointInPolygon((3., 3.), [(6, 0), (8, 4), (5, 8), (0, 2)]) AS res

┌─res─┐
│   1 │
└─────┘

多边形也可以使用具名几何数据类型来指定，包括作为表列：

CREATE TABLE poly (id UInt32, shape Polygon) ENGINE = Memory;
INSERT INTO poly VALUES (1, [[(0, 0), (10, 0), (10, 10), (0, 10)], [(4, 4), (6, 4), (6, 6), (4, 6)]]);
SELECT id, pointInPolygon((2., 2.), shape) AS res FROM poly;

┌─id─┬─res─┐
│  1 │   1 │
└────┴─────┘

注意 • 你可以设置 validate_polygons = 0 以跳过几何校验。 • pointInPolygon 假定每个多边形都是合法的。如果输入存在自相交、环顺序错误或边重叠，结果就会变得不可靠——尤其是对于恰好位于边上、顶点上，或位于自相交区域内且“内部”与“外部”的概念未定义的点。 • 当多边形参数是常量，且点是用已建立索引的键列表示时 (例如，在 x, y 是 PRIMARY KEY 的一部分或被 minmax 索引覆盖的表上使用 pointInPolygon((x, y), constant_polygon)) ，ClickHouse 可以同时使用主键和 minmax 数据跳过索引来跳过无关粒度。

​greatCircleDistance

​geoDistance

​greatCircleAngle

​geoToUTM

​UTMToGeo

​geoToMGRS

​MGRSToGeo

​pointInEllipses

​pointInPolygon

greatCircleDistance

geoDistance

greatCircleAngle

geoToUTM

UTMToGeo

geoToMGRS

MGRSToGeo

pointInEllipses

pointInPolygon