Geodistance 집계

geo_distance 집계는 문서를 중심점(central point) 주변의 거리 기반 링(ring)으로 그룹화해요. 각 범위가 링을 정의하며, 문서의 geo_point 필드 값이 지정된 origin에서 얼마나 떨어져 있는지에 따라 버킷에 배치돼요. 이는 개념적으로 range 집계와 비슷하지만 숫자 값이 아닌 지리적 좌표에 대해 동작해요.

대상 필드는 geo_point로 매핑되어야 해요. 문서의 geo_point 필드에 여러 값이 포함된 경우 모든 거리가 평가되고 문서는 그에 따라 버킷팅돼요.

출처: 문서

본문

파라미터 (Parameters)

geo_distance 집계는 다음 파라미터를 받아요.

파라미터	필수/선택	데이터 타입	설명
field	필수	String	거리를 계산할 geo_point 필드.
origin	필수	Object, String, 또는 Array	거리를 측정하는 중심점. 객체 형식(`{"lat": 40.71, "lon": -74.00}`), 문자열 형식(`"40.71, -74.00"`), 또는 GeoJSON 배열 형식(`[-74.00, 40.71]`)을 받아요.
ranges	필수	Array	버킷을 정의하는 거리 범위 목록. 각 범위는 from, to, 그리고 선택적으로 key를 포함할 수 있어요.
unit	선택	String	ranges의 거리 값 단위. 기본값은 m(미터)이에요. 유효한 값: m, km, mi, yd, in, cm, mm.
distance_type	선택	String	거리를 계산하는 데 사용하는 알고리즘. 유효한 값은 다음과 같아요:
			- arc: 지구의 완전한 구면 기하를 사용해 거리를 계산. 가장 정확하지만 가장 느려요.
			- plane: 좌표를 평평한 평면에 투영하고 유클리드 거리를 계산. 가장 빠르지만 정확도가 가장 낮아요. 작은 지리적 영역(약 5km 이하)에만 적합해요.
			기본값은 arc예요.
keyed	선택	Boolean	true면 버킷을 배열 대신 범위 이름으로 키가 지정된 객체로 반환해요. 기본값은 false예요.

예제: 기본 거리 링 (Basic distance rings)

다음 예제는 전자상거래 주문을 뉴욕 시 주변의 세 가지 거리 링으로 그룹화하며, 마일 단위로 측정해요:

GET /opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "distance_from_nyc": {
      "geo_distance": {
        "field": "geoip.location",
        "origin": "40.7128, -74.0060",
        "unit": "mi",
        "ranges": [
          { "to": 50 },
          { "from": 50, "to": 500 },
          { "from": 500 }
        ]
      }
    }
  }
}

예제: 커스텀 범위 이름의 키드 응답 (Keyed response with custom range names)

keyed를 true로 설정하면 버킷을 배열 대신 객체로 반환해요. key 속성을 사용해 각 범위에 커스텀 이름을 지정할 수 있어요:

GET /opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "distance_from_nyc": {
      "geo_distance": {
        "field": "geoip.location",
        "origin": "40.7128, -74.0060",
        "unit": "mi",
        "keyed": true,
        "ranges": [
          { "to": 50, "key": "local" },
          { "from": 50, "to": 500, "key": "domestic" },
          { "from": 500, "key": "international" }
        ]
      }
    }
  }
}

예제 응답 (Example response)

다음 응답은 keyed 예제에 해당해요:

{
  "took": 18,
  "timed_out": false,
  "terminated_early": true,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4675,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "distance_from_nyc": {
      "buckets": {
        "local": {
          "from": 0.0,
          "to": 50.0,
          "doc_count": 896
        },
        "domestic": {
          "from": 50.0,
          "to": 500.0,
          "doc_count": 0
        },
        "international": {
          "from": 500.0,
          "doc_count": 3779
        }
      }
    }
  }
}

응답 본문 필드 (Response body fields)

필드	데이터 타입	설명
buckets	Array 또는 Object	거리 버킷. 기본적으로 배열로, keyed가 true면 객체로 반환돼요.
buckets.key	String	자동 생성된 범위 레이블(예: `*-500.0` 또는 `500.0-3000.0`), 또는 지정된 커스텀 키.
buckets.from	Double	지정된 단위의 거리 범위 하한.
buckets.to	Double	지정된 단위의 거리 범위 상한.
buckets.doc_count	Integer	이 거리 범위 안에 속하는 문서 수.

더 알아보기 (Learn more)

OpenSearch 공식 문서