xy shape 필드 타입

xy shape 필드 타입

xy_shape 필드 타입은 다각형(polygon)이나 xy point의 모음 같은 도형을 담는 필드 타입이에요. Lucene의 XYShape 필드 타입을 기반으로 하며, geoshape 필드 타입과 비슷하지만 카테시안 평면 위의 도형을 나타냅니다.

출처: 문서

본문

2.4 버전에서 도입되었어요.

xy_shape 필드 타입은 다각형이나 xy point의 모음 같은 도형을 담아요. Lucene XYShape 필드 타입을 기반으로 해요. xy shape를 인덱싱하기 위해 OpenSearch는 도형을 삼각형 메시(triangular mesh)로 테셀레이션하고 각 삼각형을 BKD 트리(균형 잡힌 k차원 트리 집합)에 저장해요. 이는 10^-7 십진법 정도의 정밀도를 제공하며, 거의 완벽한 공간 해상도를 나타내요.

xy_shape 필드 타입은 geoshape 필드 타입과 비슷하지만, 지구 고정 지상 기준계를 기반으로 하지 않는 카테시안 평면 위의 도형을 나타낸다는 점이 달라요. xy shape의 좌표는 단정밀도 부동소수점 값이에요. 부동소수점 값의 범위와 정밀도에 대한 정보는 Numeric field types를 참조하세요.

예시 (Example)

xy_shape 필드 타입이 있는 매핑을 생성하세요.

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

형식 (Formats)

xy shape는 다음 형식으로 인덱싱할 수 있어요.

  • GeoJSON
  • WKT(Well-Known Text)

GeoJSON과 WKT 모두에서 좌표는 좌표 배열 안에서 x, y 순서로 지정해야 해요.

xy shape 타입 (xy shape types)

다음 표는 가능한 xy shape 타입과 GeoJSON, WKT 타입과의 관계를 설명해요.

OpenSearch 타입 GeoJSON 타입 WKT 타입 설명
point Point POINT x, y 좌표로 지정된 지리적 점
linestring LineString LINESTRING 두 개 이상의 점으로 지정된 선. 직선이거나 연결된 선분의 경로일 수 있어요.
polygon Polygon POLYGON 좌표 형태의 꼭짓점 목록으로 지정된 다각형. 다각형은 닫혀 있어야 하며, 즉 마지막 점은 첫 번째 점과 같아야 해요. 따라서 n각형을 만들려면 n+1개의 꼭짓점이 필요해요. 최소 꼭짓점 수는 4개이며, 이는 삼각형을 만듭니다.
multipoint MultiPoint MULTIPOINT 서로 연결되지 않은 개별 관련 점들의 배열
multilinestring MultiLineString MULTILINESTRING linestring들의 배열
multipolygon MultiPolygon MULTIPOLYGON 다각형들의 배열
geometrycollection GeometryCollection GEOMETRYCOLLECTION 서로 다른 타입일 수 있는 xy shape들의 모음
envelope 해당 없음 BBOX 왼쪽 위와 오른쪽 아래 꼭짓점으로 지정된 경계 사각형

Point

point는 한 쌍의 좌표로 지정돼요. GeoJSON 형식으로 point를 인덱싱하세요.

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

WKT 형식으로 point를 인덱싱하세요.

PUT testindex/_doc/1
{
  "location" : "POINT (0.5 4.5)"        
}

Linestring

linestring은 두 개 이상의 점으로 지정된 선이에요. 점들이 공선(collinear)이면 linestring은 직선이에요. 그렇지 않으면 linestring은 선분으로 만들어진 경로를 나타내요.

GeoJSON 형식으로 linestring을 인덱싱하세요.

PUT testindex/_doc/2
{
  "location" : {
    "type" : "linestring",
    "coordinates" : [[0.5, 4.5], [-1.5, 2.3]]
  }
}

WKT 형식으로 linestring을 인덱싱하세요.

PUT testindex/_doc/2
{
  "location" : "LINESTRING (0.5 4.5, -1.5 2.3)"
}

Polygon

polygon은 좌표 형태의 꼭짓점 목록으로 지정돼요. polygon은 닫혀 있어야 하며, 즉 마지막 점은 첫 번째 점과 같아야 해요. 다음 예시에서는 네 개의 점을 사용해 삼각형을 만들었어요.

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

GeoJSON 형식으로 polygon(삼각형)을 인덱싱하세요.

PUT testindex/_doc/3
{
  "location" : {
    "type" : "polygon",
    "coordinates" : [
      [[0.5, 4.5], 
      [2.5, 6.0], 
      [1.5, 2.0], 
      [0.5, 4.5]]
    ]
  }
}

WKT 형식으로 polygon(삼각형)을 인덱싱하세요.

PUT testindex/_doc/3
{
  "location" : "POLYGON ((0.5 4.5, 2.5 6.0, 1.5 2.0, 0.5 4.5))"
}

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

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

GeoJSON 형식으로 삼각형 구멍이 있는 polygon(삼각형)을 인덱싱하세요.

PUT testindex/_doc/4
{
  "location" : {
    "type" : "polygon",
    "coordinates" : [
      [[0.5, 4.5], 
      [2.5, 6.0], 
      [1.5, 2.0], 
      [0.5, 4.5]],
      
      [[1.0, 4.5], 
      [1.5, 4.5], 
      [1.5, 4.0], 
      [1.0, 4.5]]
    ]
  }
}

WKT 형식으로 삼각형 구멍이 있는 polygon(삼각형)을 인덱싱하세요.

PUT testindex/_doc/4
{
  "location" : "POLYGON ((0.5 4.5, 2.5 6.0, 1.5 2.0, 0.5 4.5), (1.0 4.5, 1.5 4.5, 1.5 4.0, 1.0 4.5))"
}

기본적으로 polygon의 꼭짓점은 반시계 방향으로 순회돼요. 매핑 시점에 꼭짓점 순회 순서를 지정하는 orientation 파라미터를 정의할 수 있어요.

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

이후 인덱싱되는 문서가 orientation 설정을 덮어쓸 수 있어요.

PUT testindex/_doc/3
{
  "location" : {
    "type" : "polygon",
    "orientation" : "cw",
    "coordinates" : [
      [[0.5, 4.5], 
      [2.5, 6.0], 
      [1.5, 2.0], 
      [0.5, 4.5]]
    ]
  }
}

Multipoint

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

GeoJSON 형식으로 multipoint를 인덱싱하세요.

PUT testindex/_doc/6
{
  "location" : {
    "type" : "multipoint",
    "coordinates" : [
      [0.5, 4.5], 
      [2.5, 6.0]
    ]
  }
}

WKT 형식으로 multipoint를 인덱싱하세요.

PUT testindex/_doc/6
{
  "location" : "MULTIPOINT (0.5 4.5, 2.5 6.0)"
}

Multilinestring

multilinestring은 linestring들의 배열이에요.

GeoJSON 형식으로 multilinestring을 인덱싱하세요.

PUT testindex/_doc/2
{
  "location" : {
    "type" : "multilinestring",
    "coordinates" : [
      [[0.5, 4.5], [2.5, 6.0]],
      [[1.5, 2.0], [3.5, 3.5]]
      ]
  }
}

WKT 형식으로 multilinestring을 인덱싱하세요.

PUT testindex/_doc/2
{
  "location" : "MULTILINESTRING ((0.5 4.5, 2.5 6.0), (1.5 2.0, 3.5 3.5))"
}

Multipolygon

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

GeoJSON 형식으로 multipolygon을 인덱싱하세요.

PUT testindex/_doc/4
{
  "location" : {
    "type" : "multipolygon",
    "coordinates" : [
    [
      [[0.5, 4.5], 
      [2.5, 6.0], 
      [1.5, 2.0], 
      [0.5, 4.5]],
      
      [[1.0, 4.5], 
      [1.5, 4.5], 
      [1.5, 4.0], 
      [1.0, 4.5]]
    ],
    [
      [[2.0, 0.0], 
      [1.0, 2.0], 
      [3.0, 1.0], 
      [2.0, 0.0]]
      ]
    ]
  }
}

WKT 형식으로 multipolygon을 인덱싱하세요.

PUT testindex/_doc/4
{
  "location" : "MULTIPOLYGON (((0.5 4.5, 2.5 6.0, 1.5 2.0, 0.5 4.5), (1.0 4.5, 1.5 4.5, 1.5 4.0, 1.0 4.5)), ((2.0 0.0, 1.0 2.0, 3.0 1.0, 2.0 0.0)))"
}

Geometry collection

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

GeoJSON 형식으로 geometry collection을 인덱싱하세요.

PUT testindex/_doc/7
{
  "location" : {
    "type": "geometrycollection",
    "geometries": [
      {
        "type": "point",
        "coordinates": [0.5, 4.5]
      },
      {
        "type": "linestring",
        "coordinates": [[2.5, 6.0], [1.5, 2.0]]
      }
    ]
  }
}

WKT 형식으로 geometry collection을 인덱싱하세요.

PUT testindex/_doc/7
{
  "location" : "GEOMETRYCOLLECTION (POINT (0.5 4.5), LINESTRING(2.5 6.0, 1.5 2.0))"
}

Envelope

envelope는 왼쪽 위와 오른쪽 아래 꼭짓점으로 지정된 경계 사각형이에요. GeoJSON 형식은 [[minX, maxY], [maxX, minY]]이에요.

GeoJSON 형식으로 envelope를 인덱싱하세요.

PUT testindex/_doc/2
{
  "location" : {
    "type" : "envelope",
    "coordinates" : [[3.0, 2.0], [6.0, 0.0]]
  }
}

WKT 형식에서는 BBOX (minX, maxX, maxY, minY)를 사용하세요. WKT BBOX 형식으로 envelope를 인덱싱하세요.

PUT testindex/_doc/8
{
  "location" : "BBOX (3.0, 6.0, 2.0, 0.0)"
}

파라미터 (Parameters)

다음 표는 xy_shape 필드 타입이 받아들이는 파라미터를 나열해요. 모든 파라미터는 선택 사항이에요.

파라미터 설명
coerce 닫히지 않은 선형 링(linear ring)을 자동으로 닫을지 여부를 지정하는 Boolean 값. 기본값은 false.
ignore_malformed 잘못된 GeoJSON 또는 WKT xy shape를 무시하고 예외를 던지지 않을지 여부를 지정하는 Boolean 값. 기본값은 false(xy shape가 잘못되면 예외를 던짐).
ignore_z_value 좌표가 3개인 점과 관련됨. ignore_z_value가 true이면 세 번째 좌표는 인덱싱되지 않지만 _source 필드에는 여전히 저장돼요. ignore_z_value가 false이면 예외가 던져져요. 기본값은 true.
orientation xy shape의 좌표 목록에서 꼭짓점의 순회 순서를 지정함. orientation은 다음 값을 가져요. 1. RIGHT: 반시계 방향. right, counterclockwise, ccw 중 하나의 문자열(대소문자 무관)로 RIGHT 방향을 지정하세요. 2. LEFT: 시계 방향. left, clockwise, cw 중 하나의 문자열(대소문자 무관)로 LEFT 방향을 지정하세요. 이 값은 개별 문서로 덮어쓸 수 있어요. 기본값은 RIGHT.

더 알아보기 (Learn more)