GeoJSON - ClickHouse Documentation

입력	출력	별칭
✔	✔

설명

GeoJSON 데이터는 단일 FeatureCollection 문서로 교환되며, ClickHouse는 이를 id, geometry, properties의 3개 컬럼에 매핑합니다 — 각 Feature마다 한 세트씩입니다. 문서를 읽으면 feature당 1개의 행이 생성되고, 쓰면 행당 1개의 feature가 생성됩니다.

데이터 읽기

FeatureCollection을 읽으면 피처당 1개의 행이 생성되며, 다음과 같은 고정 스키마가 적용됩니다:

컬럼	유형	설명
`id`	`Nullable(String)`	피처의 `id` 멤버(JSON 문자열 또는 숫자)로, 텍스트로 저장됩니다. `id`가 없거나 `null`이면 `NULL`로 저장되며, 명시적인 빈 문자열 id는 `''`로 유지됩니다.
`geometry`	`Geometry`	피처의 geometry로, `Geometry` variant type에 저장됩니다.
`properties`	`Nullable(JSON)`	피처의 `properties` 객체로, 반정형 `JSON` 컬럼에 저장됩니다. 명시적인 `"properties": null`은 `NULL`로 유지됩니다.

각 geometry는 ClickHouse의 Geometry 타입(Variant)에 저장됩니다. 지원되는 GeoJSON geometry 타입은 Point, LineString, MultiLineString, Polygon, MultiPolygon입니다. 나머지 두 GeoJSON geometry 타입인 GeometryCollection과 MultiPoint는 Geometry 타입으로 표현할 수 없으므로, 이를 geometry 컬럼으로 읽으면 기본적으로 예외가 발생합니다. 이 동작은 대신 NULL을 삽입하도록 변경할 수 있습니다. 자세한 내용은 아래의 지원되지 않는 geometry 타입 처리를 참조하십시오. 기본적으로 geometry 컬럼이 NULL이 되는 경우는 피처의 geometry가 명시적인 JSON null일 때뿐입니다. input_format_geojson_unsupported_geometry_handling = 'null'에서는 지원되지 않는 geometry 타입인 경우에도 NULL이 됩니다. 문서 구조는 검증됩니다. 최상위 type은 반드시 FeatureCollection이어야 하며, features의 모든 요소는 type이 Feature여야 합니다. 기본적으로 좌표는 GeoJSON shape 불변 조건을 만족해야 합니다. 즉, LineString(및 각 MultiLineString의 선)은 최소 2개의 Point를 가져야 하고, Polygon ring(및 각 MultiPolygon의 ring)은 닫혀 있어야 하며 최소 4개의 Point를 가져야 합니다(Geometry 검증 참조). 잘못된 형식의 문서는 조용히 적재되지 않고 거부됩니다. 키 순서는 유연합니다. 최상위 type은 features 배열보다 앞이나 뒤에 올 수 있으며, geometry 객체 내부에서도 coordinates는 type보다 앞이나 뒤에 올 수 있습니다. 스키마 추론은 위의 고정 스키마를 반환하므로, 테이블 정의 없이도 DESCRIBE와 SELECT ... FROM format(...)를 사용할 수 있습니다. 다음은 여러 Geometry 타입이 혼합된 GeoJSON 파일 london.geojson입니다:

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "id": "1",
            "geometry": {"type": "Point", "coordinates": [-0.0761, 51.5081]},
            "properties": {"name": "Tower of London", "feature_type": "landmark", "year_built": 1078}
        },
        {
            "type": "Feature",
            "id": "2",
            "geometry": {
                "type": "LineString",
                "coordinates": [[-0.2500, 51.4700], [-0.1800, 51.4900], [-0.1200, 51.5060], [-0.0700, 51.5050], [0.0000, 51.5100]]
            },
            "properties": {"name": "River Thames", "feature_type": "river", "length_km": 346}
        },
        {
            "type": "Feature",
            "id": "3",
            "geometry": {
                "type": "Polygon",
                "coordinates": [[[-0.1880, 51.5074], [-0.1533, 51.5074], [-0.1533, 51.5153], [-0.1880, 51.5153], [-0.1880, 51.5074]]]
            },
            "properties": {"name": "Hyde Park", "feature_type": "park", "area_km2": 1.42}
        }
    ]
}

파일에 쿼리를 실행해 Geometry 타입을 확인할 수 있습니다.

Query

SELECT id, properties.name AS name, variantType(geometry) AS geo_type
FROM file('london.geojson', GeoJSON);

Response

┌─id─┬─name────────────┬─geo_type───┐
│ 1  │ Tower of London │ Point      │
│ 2  │ River Thames    │ LineString │
│ 3  │ Hyde Park       │ Polygon    │
└────┴─────────────────┴────────────┘

파일 확장자 .geojson은 자동으로 감지되므로 포맷 인수는 생략할 수 있습니다:

Query

SELECT id, properties.name AS name, variantType(geometry) AS geo_type
FROM file('london.geojson');

각 Geometry 객체의 실제 타입을 확인하려면 variantType를 사용할 수 있습니다:

Query

SELECT properties.name AS name, geometry, variantType(geometry)
FROM file('london.geojson', GeoJSON);

Response

Row 1:
──────
name:                  Tower of London
geometry:              (-0.0761,51.5081)
variantType(geometry): Point

Row 2:
──────
name:                  River Thames
geometry:              [(-0.25,51.47),(-0.18,51.49),(-0.12,51.506),(-0.07,51.505),(0,51.51)]
variantType(geometry): LineString

Row 3:
──────
name:                  Hyde Park
geometry:              [[(-0.188,51.5074),(-0.1533,51.5074),(-0.1533,51.5153),(-0.188,51.5153),(-0.188,51.5074)]]
variantType(geometry): Polygon

그리고 내부 데이터는 다음과 같이 추출할 수 있습니다:

Query

SELECT properties.name AS name, variantType(geometry), geometry.Point, geometry.LineString, geometry.Polygon
FROM file('london.geojson', GeoJSON);

Response

Row 1:
──────
name:                  Tower of London
variantType(geometry): Point
geometry.Point:        (-0.0761,51.5081)
geometry.LineString:   []
geometry.Polygon:      []

Row 2:
──────
name:                  River Thames
variantType(geometry): LineString
geometry.Point:        (0,0)
geometry.LineString:   [(-0.25,51.47),(-0.18,51.49),(-0.12,51.506),(-0.07,51.505),(0,51.51)]
geometry.Polygon:      []

Row 3:
──────
name:                  Hyde Park
variantType(geometry): Polygon
geometry.Point:        (0,0)
geometry.LineString:   []
geometry.Polygon:      [[(-0.188,51.5074),(-0.1533,51.5074),(-0.1533,51.5153),(-0.188,51.5153),(-0.188,51.5074)]]

Geometry 하위 컬럼에 접근하면 해당 행에 그 타입의 값이 있으면 그 값을 반환하고, 그렇지 않으면 타입의 기본값을 반환합니다. Point는 (0,0)을, 배열 기반 타입은 []를 반환하므로 어떤 타입이 설정되어 있는지 확인하려면 variantType(geometry)를 사용하십시오. GeoJSON 데이터도 테이블에 수집할 수 있습니다:

Query

CREATE TABLE london
(
    id           String,
    geometry     Geometry,
    properties   Nullable(JSON),
    name         String MATERIALIZED properties.name,
    feature_type String MATERIALIZED properties.feature_type
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO london
SELECT id, geometry, properties
FROM file('london.geojson', GeoJSON);

다음으로 피처 유형별로 쿼리합니다:

Query

SELECT name, feature_type, variantType(geometry) AS geo_type
FROM london
ORDER BY id;

Response

┌─name────────────┬─feature_type─┬─geo_type───┐
│ Tower of London │ landmark     │ Point      │
│ River Thames    │ river        │ LineString │
│ Hyde Park       │ park         │ Polygon    │
└─────────────────┴──────────────┴────────────┘

GeoJSON 데이터의 스키마도 테이블 정의 없이 추론할 수 있습니다:

Query

DESCRIBE format(GeoJSON, '{"type":"FeatureCollection","features":[]}');

Response

┌─name───────┬─type─────────────┐
│ id         │ Nullable(String) │
│ geometry   │ Geometry         │
│ properties │ Nullable(JSON)   │
└────────────┴──────────────────┘

지원되지 않는 Geometry 타입 처리

GeometryCollection 및 MultiPoint와 같은 일부 유효한 GeoJSON Geometry 타입은 ClickHouse의 Geometry 타입으로 표현할 수 없습니다. 이러한 geometry를 geometry 컬럼에 저장해야 할 때 어떤 방식으로 처리할지는 input_format_geojson_unsupported_geometry_handling 설정으로 제어할 수 있습니다. 가능한 값은 다음과 같습니다:

'throw' — 예외를 발생시킵니다(기본값)
'null' — geometry 컬럼에 NULL 값을 삽입하고 파싱을 계속합니다

이 처리는 geometry 컬럼을 읽을 때만 적용됩니다. geometry가 요청된 출력 컬럼이 아닌 경우(예: SELECT id FROM ...)에도 지원되지 않는 geometry의 형식 유효성은 검사되지만, 이 처리 방식이 적용되지는 않습니다. 즉, geometry 값이 구체화되지 않으므로 예외가 발생하지도 않고 NULL이 삽입되지도 않습니다.

제한 사항

읽기 시에는 고정된 스키마에 맞는 내용만 반영되므로, 일부 GeoJSON 정보는 보존되지 않습니다:

id, geometry, properties만 생성되며, 그 외의 문서 구조는 컬럼으로 노출되지 않습니다.
위치의 세 번째(고도) 좌표와 그 이후 좌표는 삭제되므로, 위치는 [longitude, latitude]만 남습니다.
bbox와 외부 멤버(예: 최상위 name 또는 crs, 또는 Feature 내부의 추가 멤버)는 무시됩니다.
숫자형 id는 텍스트로 저장되므로 문자열과 숫자의 구분이 사라집니다. id가 없거나 null이면 NULL이 됩니다.
GeometryCollection과 MultiPoint는 표현할 수 없습니다. 지원되지 않는 Geometry 타입 처리를 참조하십시오.

데이터 쓰기

결과 집합을 쓰면 GeoJSON FeatureCollection 하나가 생성되며, 각 행은 Feature 하나로 기록됩니다. 결과의 컬럼은 각 Feature에 다음과 같이 매핑됩니다.

Feature member	Built from	Notes
`type`	—	항상 `"Feature"`입니다.
`geometry`	the single geometry-typed column	geometry 유형의 컬럼이 정확히 1개 있어야 하며, 그렇지 않으면 쿼리가 거부됩니다. `NULL` geometry는 `null`로 기록됩니다.
`id`	a column named `id`	값이 `NULL`이면 생략됩니다. `String` 컬럼은 JSON 문자열로, 숫자 컬럼은 JSON 숫자로 기록됩니다.
`properties`	all remaining columns	`properties`라는 이름의 단일 컬럼이 있고 그 유형이 객체와 유사한 경우(`JSON`, `Map` 또는 이름이 지정된 `Tuple`), `properties` 키 아래에 중첩하지 않고 해당 값을 `properties` 객체로 직접 기록합니다. 그렇지 않으면 나머지 각 컬럼이 자신의 이름을 키로 하는 속성이 됩니다(남은 컬럼이 없으면 빈 객체가 됩니다).

geometry 유형의 컬럼은 Geometry Variant이거나 특정 geo 유형일 수 있으며, 각각은 다음 GeoJSON geometry 유형에 매핑됩니다.

ClickHouse type	GeoJSON `"type"`
`Point`	`Point`
`LineString`	`LineString`
`MultiLineString`	`MultiLineString`
`Polygon`	`Polygon`
`MultiPolygon`	`MultiPolygon`
`Ring`	`Polygon` (a single ring)
`Geometry`	the active variant’s type (or `null`)

Ring은 GeoJSON geometry 유형이 아닙니다. linear ring은 Polygon의 구성 요소이므로 Ring 값은 단일 ring Polygon으로 기록됩니다.

예시

위에서 생성한 london 테이블에서 계속해서, 일반 속성 컬럼을 내보내면 id와 geometry를 제외한 모든 컬럼이 프로퍼티가 됩니다:

Query

SELECT id, geometry, name, feature_type
FROM london
ORDER BY id
FORMAT GeoJSON;

Response

{"type":"FeatureCollection","features":[{"type":"Feature","id":"1","geometry":{"type":"Point","coordinates":[-0.0761,51.5081]},"properties":{"name":"Tower of London","feature_type":"landmark"}},{"type":"Feature","id":"2","geometry":{"type":"LineString","coordinates":[[-0.25,51.47],[-0.18,51.49],[-0.12,51.506],[-0.07,51.505],[0,51.51]]},"properties":{"name":"River Thames","feature_type":"river"}},{"type":"Feature","id":"3","geometry":{"type":"Polygon","coordinates":[[[-0.188,51.5074],[-0.1533,51.5074],[-0.1533,51.5153],[-0.188,51.5153],[-0.188,51.5074]]]},"properties":{"name":"Hyde Park","feature_type":"park"}}]}

properties라는 이름의 객체 유형 컬럼이 하나만 있으면 해당 컬럼이 직접 출력되므로, GeoJSON 파일을 읽은 뒤 그대로 다시 쓰면 문서가 그대로 재현됩니다(이 파일에서 추론되는 컬럼은 id, geometry, properties입니다):

Query

SELECT * FROM file('london.geojson', GeoJSON) FORMAT GeoJSON;

Response

{"type":"FeatureCollection","features":[{"type":"Feature","id":"1","geometry":{"type":"Point","coordinates":[-0.0761,51.5081]},"properties":{"feature_type":"landmark","name":"Tower of London","year_built":1078}},{"type":"Feature","id":"2","geometry":{"type":"LineString","coordinates":[[-0.25,51.47],[-0.18,51.49],[-0.12,51.506],[-0.07,51.505],[0,51.51]]},"properties":{"feature_type":"river","length_km":346,"name":"River Thames"}},{"type":"Feature","id":"3","geometry":{"type":"Polygon","coordinates":[[[-0.188,51.5074],[-0.1533,51.5074],[-0.1533,51.5153],[-0.188,51.5153],[-0.188,51.5074]]]},"properties":{"area_km2":1.42,"feature_type":"park","name":"Hyde Park"}}]}

숫자형 id 컬럼은 JSON 숫자 형식으로 기록되며(NULL인 널 허용 Nullable id는 완전히 생략됩니다):

Query

SELECT 42 AS id, (-0.1276, 51.5072)::Point AS geometry FORMAT GeoJSON;

Response

{"type":"FeatureCollection","features":[{"type":"Feature","id":42,"geometry":{"type":"Point","coordinates":[-0.1276,51.5072]},"properties":{}}]}

Ring은 단일 링 Polygon으로 표기됩니다:

Query

SELECT [(0., 0.), (10., 0.), (10., 10.), (0., 0.)]::Ring AS geometry FORMAT GeoJSON;

Response

{"type":"FeatureCollection","features":[{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[0,0],[10,0],[10,10],[0,0]]]},"properties":{}}]}

파일에 쓰기

클라이언트에서 GeoJSON 파일로 쓰려면 INTO OUTFILE을 사용하십시오:

Query

SELECT id, geometry, properties
FROM london
ORDER BY id
INTO OUTFILE 'london_export.geojson'
FORMAT GeoJSON;

서버는 file 테이블 함수를 사용해 파일에 직접 쓸 수 있습니다(.geojson 확장자가 포맷을 자동으로 선택합니다):

Query

INSERT INTO FUNCTION file('london_export.geojson', GeoJSON)
SELECT id, geometry, properties FROM london;

제한 사항

ClickHouse의 geo 타입에는 좌표 참조 시스템이 없으므로, 출력에서는 좌표가 이미 RFC 7946에서 요구하는 [longitude, latitude] 순서의 WGS84 경도/위도라고 가정합니다. 재투영이나 축 스왑은 수행하지 않으므로, 투영 좌표나 (latitude, longitude)로 저장된 데이터는 구조적으로는 유효하지만 규격을 준수하지 않는 GeoJSON을 생성합니다.

출력에는 ClickHouse에 저장된 내용만 반영됩니다.

읽는 과정에서 손실되는 정보(위치의 고도, bbox, 외부 멤버, id가 문자열인지 숫자인지에 대한 구분)는 복원할 수 없습니다. 자세한 내용은 읽기 제한 사항을 참조하십시오.
좌표는 Float64 값에서 왕복 가능한 가장 짧은 표현으로 기록됩니다.
JSON 컬럼에서 직접 가져온 properties 객체는 JSON 타입의 정규 키 순서로 출력되므로, 입력과 순서가 다를 수 있습니다.

지오메트리는 저장된 그대로 기록되며, 좌표 순서와 감김 방향도 유지됩니다. 기본적으로는 쓰기 시점에 GeoJSON 도형 유효성을 검사합니다(도형 유효성 검사 참조). 따라서 점이 1개뿐인 LineString이나 닫히지 않은 Polygon ring처럼 유효한 GeoJSON 도형이 아닌 지오메트리는, 기록한 문서를 다시 읽을 수 있도록 거부됩니다. 대신 이러한 지오메트리를 있는 그대로 출력하려면 format_geojson_validate_geometry = 0으로 설정하십시오. 그러면 구조적으로는 유효하지만 규격을 준수하지 않는 GeoJSON이 생성됩니다. 오른손 법칙(감김 방향) 불변성은 어느 경우에도 강제되지 않으며, null과 비어 있는 properties 객체의 구분도 유지됩니다.

Geometry 유효성 검사

설정 format_geojson_validate_geometry는 포맷이 RFC 7946의 지오메트리 형태 규칙을 양방향에서 모두 적용할지 제어합니다. 기본적으로 활성화되어 있습니다. 활성화되면 GeoJSON 형태 규칙을 위반하는 지오메트리는 거부됩니다. 예를 들어 점이 2개 미만인 LineString(또는 MultiLineString의 선), 점이 4개 미만이거나 첫 번째 점과 마지막 점이 달라 닫히지 않은 Polygon 또는 MultiPolygon의 ring, 또는 비어 있는 MultiLineString, Polygon, MultiPolygon이 여기에 해당합니다. 동일한 규칙이 이런 문서를 읽을 때와 이런 ClickHouse 값을 쓸 때 모두 적용되므로, 한 번 쓴 문서는 항상 다시 읽을 수 있습니다. 비활성화되면 이러한 형태 규칙은 양방향 모두에서 적용되지 않습니다. 즉, 퇴화된 지오메트리는 있는 그대로 읽고 있는 그대로 기록합니다. 따라서 유효한 GeoJSON 지오메트리가 아닌 ClickHouse 지오메트리 값도 이 포맷을 통해 그대로 왕복할 수 있지만, 그 대가로 유효한 GeoJSON이 아닌 문서가 생성될 수 있습니다. 이 유효성 검사는 구조만 검사합니다. 즉, 점 개수와 ring 폐합 여부만 확인합니다. 도형의 기하학적 정확성은 검사하지 않으므로, 구조적으로는 유효하지만 기하학적으로는 퇴화된 지오메트리도 양방향 모두에서 허용됩니다. 예를 들어 면적이 0인 polygon, 자기 자신과 교차하는 ring, 또는 holes(내부 ring)가 바깥쪽 ring 바깥에 있는 polygon이 여기에 해당합니다. polygon ring의 오른손 법칙(right-hand-rule, winding) 방향도 마찬가지로 적용하지 않습니다. 한 가지 검사는 이 설정과 무관합니다. 유한하지 않은 좌표(NaN, Inf)는 JSON 숫자로 표현할 수 없으므로 항상 거부됩니다.

​설명

​데이터 읽기

​지원되지 않는 Geometry 타입 처리

​제한 사항

​데이터 쓰기

​예시

​파일에 쓰기

​제한 사항

​Geometry 유효성 검사

설명

데이터 읽기

지원되지 않는 Geometry 타입 처리

제한 사항

데이터 쓰기

예시

파일에 쓰기

제한 사항

Geometry 유효성 검사