Geopolygon 쿼리

geo_polygon 쿼리는 지정된 다각형(polygon) 안에 있는 geopoint를 포함한 문서를 반환해요. 여러 geopoint를 포함한 문서는 그 중 하나 이상이 쿼리와 일치하면 쿼리와 일치합니다.

출처: 문서

본문

geo_polygon 쿼리는 지정된 다각형 안에 있는 geopoint를 포함한 문서를 반환해요. 여러 geopoint를 포함한 문서는 그 중 하나 이상이 쿼리와 일치하면 쿼리와 일치해요.

다각형은 좌표 형태의 꼭짓점 목록으로 지정돼요. geoshape 필드에 다각형을 지정하는 것과 달리, 다각형은 닫힐 필요가 없어요(첫 번째 점과 마지막 점을 같게 지정할 필요가 없음). 점들이 시계 방향 또는 반시계 방향 순서를 따를 필요는 없지만, 두 순서 중 하나로 나열하는 것이 좋아요. 이렇게 하면 올바른 다각형이 포착되도록 보장돼요.

검색 대상 문서 필드는 geo_point로 매핑되어야 해요.

예시 (Example)

point 필드를 geo_point로 매핑한 매핑을 생성하세요.

PUT /testindex1
{
  "mappings": {
    "properties": {
      "point": {
        "type": "geo_point"
      }
    }
  }
}

위도와 경도를 지정해 geopoint를 인덱싱하세요.

PUT testindex1/_doc/1
{
  "point": { 
    "lat": 73.71,
    "lon": 41.32
  }
}

point 객체가 지정된 geo_polygon 안에 있는 문서를 검색하세요.

GET /testindex1/_search
{
  "query": {
    "bool": {
      "must": {
        "match_all": {}
      },
      "filter": {
        "geo_polygon": {
          "point": {
            "points": [
              { "lat": 74.5627, "lon": 41.8645 },
              { "lat": 73.7562, "lon": 42.6526 },
              { "lat": 73.3245, "lon": 41.6189 },
              { "lat": 74.0060, "lon": 40.7128 }
           ]
          }
        }
      }
    }
  }
}

앞의 요청에 지정된 다각형은 다음 이미지에 묘사된 사변형이에요. 일치하는 문서는 이 사변형 안에 있어요. 사변형 꼭짓점의 좌표는 (위도, 경도) 형식으로 지정돼요.

응답에는 일치하는 문서가 포함돼요.

{
  "took": 6,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "testindex1",
        "_id": "1",
        "_score": 1,
        "_source": {
          "point": {
            "lat": 73.71,
            "lon": 41.32
          }
        }
      }
    ]
  }
}

앞의 검색 요청에서 다각형 꼭짓점을 시계 방향 순서로 지정했어요.

"geo_polygon": {
    "point": {
    "points": [
        { "lat": 74.5627, "lon": 41.8645 },
        { "lat": 73.7562, "lon": 42.6526 },
        { "lat": 73.3245, "lon": 41.6189 },
        { "lat": 74.0060, "lon": 40.7128 }
    ]
    }
}

또는 꼭짓점을 반시계 방향 순서로 지정할 수 있어요.

"geo_polygon": {
    "point": {
    "points": [
        { "lat": 74.5627, "lon": 41.8645 },
        { "lat": 74.0060, "lon": 40.7128 },
        { "lat": 73.3245, "lon": 41.6189 },
        { "lat": 73.7562, "lon": 42.6526 }
    ]
    }
}

결과 쿼리 응답에는 같은 일치 문서가 포함돼요.

하지만 꼭짓점을 다음 순서로 지정하면:

"geo_polygon": {
    "point": {
    "points": [
        { "lat": 74.5627, "lon": 41.8645 },
        { "lat": 74.0060, "lon": 40.7128 },
        { "lat": 73.7562, "lon": 42.6526 },
        { "lat": 73.3245, "lon": 41.6189 }
    ]
    }
}

응답은 아무 결과도 반환하지 않아요.

파라미터 (Parameters)

geopolygon 쿼리는 다음 파라미터를 받아들여요.

파라미터	데이터 타입	설명
`_name`	String	필터의 이름. 선택 사항.
`validation_method`	String	검증 방법. 유효한 값은 `IGNORE_MALFORMED`(유효하지 않은 좌표의 geopoint를 수용), `COERCE`(좌표를 유효한 값으로 강제 변환 시도), `STRICT`(좌표가 유효하지 않으면 오류 반환). 선택 사항. 기본값은 `STRICT`.
`ignore_unmapped`	Boolean	매핑되지 않은 필드를 무시할지 여부를 지정함. `true`로 설정하면 쿼리는 매핑되지 않은 필드를 포함한 문서를 반환하지 않음. `false`로 설정하면 필드가 매핑되지 않았을 때 예외가 던져짐. 선택 사항. 기본값은 `false`.

허용 형식 (Accepted formats)

문서를 인덱싱하고 문서를 검색할 때 geopoint 필드 타입이 수용하는 어떤 형식으로든 geopoint 좌표를 지정할 수 있어요.

더 알아보기 (Learn more)

OpenSearch 공식 문서