Geoshape 필드 타입

Geoshape 필드 타입

geo_shape 필드 타입은 폴리곤이나 지리적 점들의 모임 같은 지리적 모양을 담는 데 사용해요. 지도 위 영역이나 도형을 표현할 때 써요.

출처: 문서

본문

예시

geoshape 필드 타입으로 매핑을 만들어 볼게요.

PUT testindex
{
  "mappings": {
    "properties": {
      "location": {
        "type": "geo_shape"
      }
    }
  }
}

형식 (Formats)

geoshape는 다음과 같은 형식으로 색인할 수 있어요.

• GeoJSON
• Well-Known Text (WKT)

GeoJSON과 WKT 모두에서 좌표 배열 안의 좌표는 경도, 위도 순서로 지정해야 해요. 이 형식에서는 경도가 먼저 온다는 점을 기억하세요.

Geoshape 타입

가능한 geoshape 타입과 GeoJSON·WKT 타입과의 관계는 다음 표와 같아요.

OpenSearch 타입	GeoJSON 타입	WKT 타입	설명
point	Point	POINT	위도와 경도로 지정된 지리적 점이에요. OpenSearch는 WGS84 좌표계(일명 EPSG:4326)를 사용해요.
linestring	LineString	LINESTRING	두 개 이상의 점으로 지정된 선이에요. 직선이거나 연결된 선분들의 경로일 수 있어요.
polygon	Polygon	POLYGON	좌표 형태의 정점 목록으로 지정된 폴리곤이에요. 폴리곤은 닫혀 있어야 하며, 마지막 점이 첫 점과 같아야 해요. 따라서 n각형을 만들려면 n+1개의 정점이 필요해요. 최소 정점 수는 4개이며, 이 경우 삼각형이 만들어져요.
multipoint	MultiPoint	MULTIPOINT	서로 연결되지 않은 개별 관련 점들의 배열이에요.
multilinestring	MultiLineString	MULTILINESTRING	linestring들의 배열이에요.
multipolygon	MultiPolygon	MULTIPOLYGON	폴리곤들의 배열이에요.
geometrycollection	GeometryCollection	GEOMETRYCOLLECTION	서로 다른 타입일 수 있는 geoshape들의 모음이에요.
envelope	N/A	BBOX	왼쪽 위와 오른쪽 아래 정점으로 지정된 경계 사각형이에요.

Point

point는 위도와 경도로 지정된 단일 좌표쌍이에요.

GeoJSON 형식으로 point를 색인해 볼게요.

PUT testindex/_doc/1
{
  "location" : {
    "type" : "point",
    "coordinates" : [74.0060, 40.7128]
  }
}

WKT 형식으로 point를 색인해 볼게요.

PUT testindex/_doc/1
{
  "location" : "POINT (74.0060 40.7128)"
}

Linestring

linestring은 두 개 이상의 점으로 지정된 선이에요. 점들이 일직선상에 있으면 linestring은 직선이고, 그렇지 않으면 선분들로 이루어진 경로를 나타내요.

GeoJSON 형식으로 linestring을 색인해 볼게요.

PUT testindex/_doc/2
{
  "location" : {
    "type" : "linestring",
    "coordinates" : [[74.0060, 40.7128], [71.0589, 42.3601]]
  }
}

WKT 형식으로 linestring을 색인해 볼게요.

PUT testindex/_doc/2
{
  "location" : "LINESTRING (74.0060 40.7128, 71.0589 42.3601)"
}

Polygon

polygon은 좌표 형태의 정점 목록으로 지정돼요. 폴리곤은 닫혀 있어야 하며, 마지막 점이 첫 점과 같아야 해요. 다음 예시에서는 네 개의 점으로 삼각형을 만들어요.

GeoJSON은 폴리곤의 정점을 시계 반대 방향으로 나열하도록 요구해요. WKT는 정점에 특정 순서를 강제하지 않아요.

GeoJSON 형식으로 polygon(삼각형)을 색인해 볼게요.

PUT testindex/_doc/3
{
  "location" : {
    "type" : "polygon",
    "coordinates" : [
      [
        [74.0060, 40.7128], 
        [73.7562, 42.6526], 
        [71.0589, 42.3601], 
        [74.0060, 40.7128]
      ]
    ]
  }
}

WKT 형식으로 polygon(삼각형)을 색인해 볼게요.

PUT testindex/_doc/3
{
  "location" : "POLYGON ((74.0060 40.7128, 71.0589 42.3601, 73.7562 42.6526, 74.0060 40.7128))"
}

폴리곤은 내부에 구멍(hole)이 있을 수 있어요. 이 경우 coordinates 필드는 여러 배열을 포함하게 돼요. 첫 번째 배열은 바깥쪽 폴리곤을 나타내고, 이후 각 배열은 구멍을 나타내요. 구멍은 폴리곤으로 표현되며 좌표 배열로 지정돼요.

GeoJSON은 폴리곤의 정점을 시계 반대 방향으로, 구멍의 정점을 시계 방향으로 나열하도록 요구해요. WKT는 정점에 특정 순서를 강제하지 않아요.

GeoJSON 형식으로 삼각형 구멍이 있는 polygon(삼각형)을 색인해 볼게요.

PUT testindex/_doc/4
{
  "location" : {
    "type" : "polygon",
    "coordinates" : [
      [
        [74.0060, 40.7128], 
        [73.7562, 42.6526], 
        [71.0589, 42.3601], 
        [74.0060, 40.7128]
      ],
      [
        [72.6734,41.7658], 
        [73.0515, 41.5582], 
        [72.6506, 41.5623],
        [72.6734, 41.7658]
      ]
    ]
  }
}

WKT 형식으로 삼각형 구멍이 있는 polygon(삼각형)을 색인해 볼게요.

PUT testindex/_doc/4
{
  "location" : "POLYGON ((74.0060 40.7128, 71.0589 42.3601, 73.7562 42.6526, 74.0060 40.7128), (72.6734 41.7658, 72.6506 41.5623, 73.0515 41.5582, 72.6734 41.7658))"
}

OpenSearch에서 폴리곤은 시계 방향이나 시계 반대 방향 중 어떤 순서로든 정점을 나열해 지정할 수 있어요. 이것은 날짜 변경선을 가로지르지 않는(180°보다 좁은) 폴리곤에서 잘 작동해요. 하지만 날짜 변경선을 가로지르는(180°보다 넓은) 폴리곤은 WKT가 정점에 특정 순서를 강제하지 않기 때문에 모호할 수 있어요. 따라서 날짜 변경선을 가로지르는 폴리곤은 반드시 정점을 시계 반대 방향 순서로 지정해야 해요.

매핑 시점에 정점 순회 순서를 지정하는 orientation 파라미터를 정의할 수 있어요.

PUT testindex
{
  "mappings": {
    "properties": {
      "location": {
        "type": "geo_shape",
        "orientation" : "left"
      }
    }
  }
}

이후 색인되는 문서는 orientation 설정을 재정의할 수 있어요.

PUT testindex/_doc/3
{
  "location" : {
    "type" : "polygon",
    "orientation" : "cw",
    "coordinates" : [
      [[74.0060, 40.7128], 
      [71.0589, 42.3601], 
      [73.7562, 42.6526], 
      [74.0060, 40.7128]]
    ]
  }
}

Multipoint

multipoint는 서로 연결되지 않은 개별 관련 점들의 배열이에요.

GeoJSON 형식으로 multipoint를 색인해 볼게요.

PUT testindex/_doc/6
{
  "location" : {
    "type" : "multipoint",
    "coordinates" : [
      [74.0060, 40.7128], 
      [71.0589, 42.3601]
    ]
  }
}

WKT 형식으로 multipoint를 색인해 볼게요.

PUT testindex/_doc/6
{
  "location" : "MULTIPOINT (74.0060 40.7128, 71.0589 42.3601)"
}

Multilinestring

multilinestring은 linestring들의 배열이에요.

GeoJSON 형식으로 multilinestring을 색인해 볼게요.

PUT testindex/_doc/2
{
  "location" : {
    "type" : "multilinestring",
    "coordinates" : [
      [[74.0060, 40.7128], [71.0589, 42.3601]],
      [[73.7562, 42.6526], [72.6734, 41.7658]]
      ]
  }
}

WKT 형식으로 multilinestring을 색인해 볼게요.

PUT testindex/_doc/2
{
  "location" : "MULTILINESTRING ((74.0060 40.7128, 71.0589 42.3601), (73.7562 42.6526, 72.6734 41.7658))"
}

Multipolygon

multipolygon은 폴리곤들의 배열이에요. 이 예시에서 첫 번째 폴리곤은 구멍을 포함하고, 두 번째는 포함하지 않아요.

GeoJSON 형식으로 multipolygon을 색인해 볼게요.

PUT testindex/_doc/4
{
  "location" : {
    "type" : "multipolygon",
    "coordinates" : [
    [
      [
        [74.0060, 40.7128], 
        [73.7562, 42.6526], 
        [71.0589, 42.3601], 
        [74.0060, 40.7128]
      ],
      [
        [73.0515, 41.5582], 
        [72.6506, 41.5623], 
        [72.6734, 41.7658], 
        [73.0515, 41.5582]
      ]
    ],
    [
      [
        [73.9146, 40.8252], 
        [73.8871, 41.0389], 
        [73.6853, 40.9747], 
        [73.9146, 40.8252]
      ]
    ]
  ]
  }
}

WKT 형식으로 multipolygon을 색인해 볼게요.

PUT testindex/_doc/4
{
  "location" : "MULTIPOLYGON (((74.0060 40.7128, 71.0589 42.3601, 73.7562 42.6526, 74.0060 40.7128), (72.6734 41.7658, 72.6506 41.5623, 73.0515 41.5582, 72.6734 41.7658)), ((73.9146 40.8252, 73.6853 40.9747, 73.8871 41.0389, 73.9146 40.8252)))"
}

Geometry collection

geometry collection은 서로 다른 타입일 수 있는 geoshape들의 모음이에요.

GeoJSON 형식으로 geometry collection을 색인해 볼게요.

PUT testindex/_doc/7
{
  "location" : {
    "type": "geometrycollection",
    "geometries": [
      {
        "type": "point",
        "coordinates": [74.0060, 40.7128]
      },
      {
        "type": "linestring",
        "coordinates": [[73.7562, 42.6526], [72.6734, 41.7658]]
      }
    ]
  }
}

WKT 형식으로 geometry collection을 색인해 볼게요.

PUT testindex/_doc/7
{
  "location" : "GEOMETRYCOLLECTION (POINT (74.0060 40.7128), LINESTRING(73.7562 42.6526, 72.6734 41.7658))"
}

Envelope

envelope은 왼쪽 위와 오른쪽 아래 정점으로 지정된 경계 사각형이에요. GeoJSON 형식은 [[minLon, maxLat], [maxLon, minLat]]이에요.

GeoJSON 형식으로 envelope을 색인해 볼게요.

PUT testindex/_doc/2
{
  "location" : {
    "type" : "envelope",
    "coordinates" : [[71.0589, 42.3601], [74.0060, 40.7128]]
  }
}

WKT 형식에서는 BBOX (minLon, maxLon, maxLat, minLat)을 사용해요.

WKT BBOX 형식으로 envelope을 색인해 볼게요.

PUT testindex/_doc/8
{
  "location" : "BBOX (71.0589, 74.0060, 42.3601, 40.7128)"
}

파라미터 (Parameters)

geoshape 필드 타입이 받는 파라미터는 다음 표와 같아요. 모든 파라미터는 선택 사항이에요.

파라미터	설명
coerce	닫히지 않은 선형 링(unclosed linear ring)을 자동으로 닫을지 여부를 지정하는 불리언 값이에요. 기본값은 false예요.
ignore_malformed	잘못된 형식의 GeoJSON 또는 WKT geoshape를 무시하고 예외를 던지지 않도록 지정하는 불리언 값이에요. 기본값은 false(geoshape가 잘못된 형식일 때 예외 발생)예요.
ignore_z_value	좌표가 3개인 점에만 해당해요. ignore_z_value가 true면 세 번째 좌표는 색인되지 않지만 _source 필드에는 계속 저장돼요. false면 예외가 발생해요. 기본값은 true예요.
orientation	geoshape의 좌표 목록에서 정점 순회 순서를 지정해요. orientation은 다음 값을 받아요. 1. RIGHT: 시계 반대 방향. 다음 문자열 중 하나(대소문자 무관)로 RIGHT 방향을 지정해요: right, counterclockwise, ccw. 2. LEFT: 시계 방향. 다음 문자열 중 하나(대소문자 무관)로 LEFT 방향을 지정해요: left, clockwise, cw. 이 값은 개별 문서로 재정의할 수 있어요. 기본값은 RIGHT예요.

더 알아보기 (Learn more)

• OpenSearch 공식 문서