Geo-bounding box 쿼리

Geo-bounding box 쿼리

geopoint 필드를 포함한 문서를 검색하려면 geo-bounding box 쿼리를 사용해요. geo-bounding box 쿼리는 쿼리에 지정된 경계 사각형 안에 geopoint가 있는 문서를 반환합니다. 여러 geopoint를 가진 문서는 그 중 하나 이상이 경계 사각형 안에 있으면 쿼리와 일치해요.

출처: 문서

본문

geopoint 필드를 포함한 문서를 검색하려면 geo-bounding box 쿼리를 사용하세요. geo-bounding box 쿼리는 쿼리에 지정된 경계 사각형 안에 geopoint가 있는 문서를 반환해요. 여러 geopoint를 가진 문서는 경계 사각형 안에 geopoint가 하나 이상 있으면 쿼리와 일치해요.

예시 (Example)

geo-bounding box 쿼리를 사용해 geopoint를 포함한 문서를 검색할 수 있어요.

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

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

세 개의 geopoint를 위도와 경도를 가진 객체로 인덱싱하세요.

PUT testindex1/_doc/1
{
  "point": { 
    "lat": 74.00,
    "lon": 40.71
  }
}

PUT testindex1/_doc/2
{
  "point": { 
    "lat": 72.64,
    "lon": 22.62
  } 
}

PUT testindex1/_doc/3
{
  "point": { 
    "lat": 75.00,
    "lon": 28.00
  }
}

모든 문서를 검색하고 그 점들이 쿼리에 정의된 사각형 안에 있는 문서를 필터링하세요.

GET testindex1/_search
{
  "query": {
    "bool": {
      "must": {
        "match_all": {}
      },
      "filter": {
        "geo_bounding_box": {
          "point": {
            "top_left": {
              "lat": 75,
              "lon": 28
            },
            "bottom_right": {
              "lat": 73,
              "lon": 41
            }
          }
        }
      }
    }
  }
}

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

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

앞의 응답은 geopoint의 제한된 정밀도 때문에 "lat": 75.00, "lon": 28.00의 geopoint를 가진 문서를 포함하지 않아요.

정밀도 (Precision)

Geopoint 좌표는 인덱스 시점에 항상 내림(round down)돼요. 쿼리 시점에는 경계 사각형의 상한 경계가 내림되고 하한 경계는 올림(round up)돼요. 따라서 경계 사각형의 아래쪽과 왼쪽 가장자리에 있는 geopoint를 가진 문서는 반올림 오류 때문에 결과에 포함되지 않을 수 있어요. 반면 경계 사각형의 위쪽과 오른쪽 가장자리에 있는 geopoint는 경계 밖에 있음에도 결과에 포함될 수 있어요. 반올림 오류는 위도의 경우 4.20 × 10⁻⁸도 미만, 경도의 경우 8.39 × 10⁻⁸도 미만(약 1cm)이에요.

경계 사각형 지정하기 (Specifying the bounding box)

꼭짓점 좌표, geohash 또는 WKT(Well-Known Text) 문자열을 제공해 경계 사각형을 지정할 수 있어요.

꼭짓점 좌표로 경계 사각형 지정하기

다음 꼭짓점 좌표 조합 중 하나를 제공하세요.

• top_left와 bottom_right
• top_right와 bottom_left
• top, left, bottom, right

좌표 값은 geopoint 필드 타입이 수용하는 어떤 형식으로든 지정하세요.

다음 예시는 top, left, bottom, right 좌표를 사용해 경계 사각형을 지정하는 방법을 보여줘요.

GET testindex1/_search
{
  "query": {
    "bool": {
      "must": {
        "match_all": {}
      },
      "filter": {
        "geo_bounding_box": {
          "point": {
            "top": 75,
            "left": 28,
            "bottom": 73,
            "right": 41            
          }
        }
      }
    }
  }
}

geohash로 경계 사각형 지정하기

geohash를 사용해 경계 사각형을 지정하면 geohash는 사각형으로 취급돼요. 경계 사각형의 왼쪽 위 꼭짓점은 top_left geohash의 왼쪽 위 꼭짓점에 대응하고, 경계 사각형의 오른쪽 아래 꼭짓점은 bottom_right geohash의 오른쪽 아래 꼭짓점에 대응해요.

다음 예시는 앞의 예시들과 같은 경계 사각형을 지정하기 위해 geohash를 사용하는 방법을 보여줘요.

GET testindex1/_search
{
  "query": {
    "bool": {
      "must": {
        "match_all": {}
      },
      "filter": {
        "geo_bounding_box": {
          "point": {
            "top_left": "ut7ftjkfxm34",
            "bottom_right": "uuvpkcprc4rc"
          }
        }
      }
    }
  }
}

geohash의 전체 영역을 덮는 경계 사각형을 지정하려면 그 geohash를 경계 사각형의 top_left와 bottom_right 파라미터 양쪽으로 제공하세요.

GET testindex1/_search
{
  "query": {
    "bool": {
      "must": {
        "match_all": {}
      },
      "filter": {
        "geo_bounding_box": {
          "point": {
            "top_left": "ut",
            "bottom_right": "ut"
          }
        }
      }
    }
  }
}

WKT로 경계 사각형 지정하기

WKT 형식으로 경계 사각형을 정의하려면 BBOX (minLon, maxLon, maxLat, minLat) 형태의 경계 사각형과 함께 wkt 파라미터를 제공하세요. BBOX는 geo-bounding box 쿼리가 수용하는 유일한 WKT 지오메트리예요.

다음 예시는 WKT를 사용해 앞의 예시들과 같은 경계 사각형을 지정하는 방법을 보여줘요.

GET testindex1/_search
{
  "query": {
    "bool": {
      "must": {
        "match_all": {}
      },
      "filter": {
        "geo_bounding_box": {
          "point": {
            "wkt": "BBOX (28, 41, 75, 73)"
          }
        }
      }
    }
  }
}

파라미터 (Parameters)

Geo-bounding box 쿼리는 다음 파라미터를 받아들여요.

더 알아보기 (Learn more)

• OpenSearch 공식 문서