지리 좌표를 다루는 함수 - 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은 각각 경도 6° 너비의 구역을 포괄하는 60개의 횡축 메르카토르 투영으로 이루어진 체계로, 지리 좌표를 미터 단위의 평면 격자에 매핑합니다. 명시적으로 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*.

반환 값 named tuple (easting, northing, zone, band)입니다. easting 및 northing은 미터 단위(Float64)이고, zone은 UTM 구역 번호(UInt8)이며, band는 MGRS 위도 밴드 문자(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 지리 좌표 (경도, 위도)로 변환합니다. geoToUTM의 역변환입니다.

UTMToGeo(easting, northing, zone, is_north)

인수

easting — 미터 단위의 동향 좌표입니다(500000 m false easting 포함). (U)Int*/Float*.
northing — 미터 단위의 북향 좌표입니다(남반구에서는 10000000 m false northing 포함). (U)Int*/Float*.
zone — UTM 구역 번호입니다. 범위: [1, 60]. (U)Int*.
is_north — 반구를 나타냅니다. 북반구는 1, 남반구는 0입니다. (U)Int*.

반환 값 도 단위의 named tuple (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 — 선택 사항입니다. easting과 northing 각각의 자릿수입니다. 기본값: 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) named tuple을 반환합니다. 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을 두 번째 인수로 전달하거나, 각 구성 다각형을 각각의 인수로 나열할 수 있습니다.
다각형 인수는 다각형 형태의 값(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을 설정하면 geometry 유효성 검사를 건너뛸 수 있습니다. • pointInPolygon은 모든 다각형이 올바른 형식이라고 가정합니다. 입력이 자기 교차하거나, Ring의 순서가 잘못되었거나, edge가 겹치면 결과를 신뢰할 수 없게 됩니다. 특히 edge나 vertex 위에 정확히 놓인 점이나, “inside”와 “outside”의 개념이 정의되지 않는 자기 교차 내부의 점에서는 더욱 그렇습니다. • 다각형 인수가 상수이고 점이 인덱스가 적용된 키 컬럼으로 표현되는 경우(예: x, y가 PRIMARY KEY의 일부이거나 minmax 인덱스로 처리되는 테이블에서 pointInPolygon((x, y), constant_polygon)를 사용하는 경우), ClickHouse는 프라이머리 키(primary key)와 minmax 데이터 스키핑 인덱스를 모두 사용해 관련 없는 그래뉼을 걸러낼 수 있습니다.

​greatCircleDistance

​geoDistance

​greatCircleAngle

​geoToUTM

​UTMToGeo

​geoToMGRS

​MGRSToGeo

​pointInEllipses

​pointInPolygon

greatCircleDistance

geoDistance

greatCircleAngle

geoToUTM

UTMToGeo

geoToMGRS

MGRSToGeo

pointInEllipses

pointInPolygon