Geotile grid 집계

geotile grid 집계는 지리적 분석을 위해 문서를 그리드 셀로 그룹화해요. 각 그리드 셀은 지도 타일에 해당하며 {zoom}/{x}/{y} 형식으로 식별돼요. geotile grid 집계를 사용해 geopoint 또는 geoshape 필드에 대해 문서를 집계할 수 있어요. 주목할 만한 차이점 중 하나는 geopoint는 하나의 버킷에만 존재하는 반면, geoshape는 교차하는 모든 geotile 그리드 셀에 집계된다는 점이에요.

출처: 문서

본문

정밀도 (Precision)

precision 파라미터는 그리드 셀 크기를 결정하는 세분성 수준을 제어해요. precision이 낮을수록 그리드 셀이 커져요.

다음 예제는 저정밀도와 고정밀도 집계 요청을 보여줘요.

먼저 인덱스를 만들고 location 필드를 geo_point로 매핑해요:

PUT national_parks
{
  "mappings": {
    "properties": {
      "location": {
        "type": "geo_point"
      }
    }
  }
}

샘플 인덱스에 다음 문서들을 색인해요:

PUT national_parks/_doc/1
{
  "name": "Yellowstone National Park",
  "location": "44.42, -110.59" 
}

PUT national_parks/_doc/2
{
  "name": "Yosemite National Park",
  "location": "37.87, -119.53" 
}

PUT national_parks/_doc/3
{
  "name": "Death Valley National Park",
  "location": "36.53, -116.93" 
}

geopoint를 여러 형식으로 색인할 수 있어요. 지원되는 모든 형식 목록은 geopoint 문서를 참고하세요.

저정밀도 요청 (Low-precision requests)

세 문서를 모두 함께 버킷팅하는 저정밀도 요청을 실행해요:

GET national_parks/_search
{
  "aggregations": {
    "grouped": {
      "geotile_grid": {
        "field": "location",
        "precision": 1
      }
    }
  }
}

geotile grid 집계 쿼리에는 GET 또는 POST HTTP 메서드를 사용할 수 있어요.

응답은 모든 문서가 하나의 그리드 셀에 버킷팅될 만큼 가깝기 때문에 함께 그룹화해요:

{
  "took": 51,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 3,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "national_parks",
        "_id": "1",
        "_score": 1,
        "_source": {
          "name": "Yellowstone National Park",
          "location": "44.42, -110.59"
        }
      },
      {
        "_index": "national_parks",
        "_id": "2",
        "_score": 1,
        "_source": {
          "name": "Yosemite National Park",
          "location": "37.87, -119.53"
        }
      },
      {
        "_index": "national_parks",
        "_id": "3",
        "_score": 1,
        "_source": {
          "name": "Death Valley National Park",
          "location": "36.53, -116.93"
        }
      }
    ]
  },
  "aggregations": {
    "grouped": {
      "buckets": [
        {
          "key": "1/0/0",
          "doc_count": 3
        }
      ]
    }
  }
}

고정밀도 요청 (High-precision requests)

이제 고정밀도 요청을 실행해요:

GET national_parks/_search
{
  "aggregations": {
    "grouped": {
      "geotile_grid": {
        "field": "location",
        "precision": 6
      }
    }
  }
}

세분성이 더 높기 때문에 세 문서 모두 별도로 버킷팅돼요:

{
  "took": 15,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 3,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "national_parks",
        "_id": "1",
        "_score": 1,
        "_source": {
          "name": "Yellowstone National Park",
          "location": "44.42, -110.59"
        }
      },
      {
        "_index": "national_parks",
        "_id": "2",
        "_score": 1,
        "_source": {
          "name": "Yosemite National Park",
          "location": "37.87, -119.53"
        }
      },
      {
        "_index": "national_parks",
        "_id": "3",
        "_score": 1,
        "_source": {
          "name": "Death Valley National Park",
          "location": "36.53, -116.93"
        }
      }
    ]
  },
  "aggregations": {
    "grouped": {
      "buckets": [
        {
          "key": "6/12/23",
          "doc_count": 1
        },
        {
          "key": "6/11/25",
          "doc_count": 1
        },
        {
          "key": "6/10/24",
          "doc_count": 1
        }
      ]
    }
  }
}

또한 bounds 파라미터에 경계 상자의 좌표를 제공해 지리적 영역을 제한할 수도 있어요. bounds와 geo_bounding_box 좌표 모두 geopoint 형식 중 하나로 지정할 수 있어요. 다음 쿼리는 bounds 파라미터에 WKT(well-known text) "POINT(longitude latitude)" 형식을 사용해요:

GET national_parks/_search
{
  "size": 0,
  "aggregations": {
    "grouped": {
      "geotile_grid": {
        "field": "location",
        "precision": 6,
        "bounds": {
            "top_left": "POINT (-120 38)",
            "bottom_right": "POINT (-116 36)"
        }
      }
    }
  }
}

응답은 지정된 bounds 안에 있는 두 결과만 포함해요:

{
  "took": 48,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 3,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "national_parks",
        "_id": "1",
        "_score": 1,
        "_source": {
          "name": "Yellowstone National Park",
          "location": "44.42, -110.59"
        }
      },
      {
        "_index": "national_parks",
        "_id": "2",
        "_score": 1,
        "_source": {
          "name": "Yosemite National Park",
          "location": "37.87, -119.53"
        }
      },
      {
        "_index": "national_parks",
        "_id": "3",
        "_score": 1,
        "_source": {
          "name": "Death Valley National Park",
          "location": "36.53, -116.93"
        }
      }
    ]
  },
  "aggregations": {
    "grouped": {
      "buckets": [
        {
          "key": "6/11/25",
          "doc_count": 1
        },
        {
          "key": "6/10/24",
          "doc_count": 1
        }
      ]
    }
  }
}

bounds 파라미터는 geo_bounding_box 필터와 함께 또는 없이 사용할 수 있어요. 이 두 파라미터는 독립적이며 서로 어떤 공간적 관계를 가질 수 있어요.

Geoshape 집계 (Aggregating geoshapes)

geoshape 필드에 대해 집계를 실행하려면 먼저 인덱스를 만들고 location 필드를 geo_shape로 매핑해요:

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

다음으로, national_parks 인덱스에 몇몇 문서를 색인해요:

PUT national_parks/_doc/1
{
  "name": "Yellowstone National Park",
  "location":
  {"type": "envelope","coordinates": [ [-111.15, 45.12], [-109.83, 44.12] ]}
}

PUT national_parks/_doc/2
{
  "name": "Yosemite National Park",
  "location": 
  {"type": "envelope","coordinates": [ [-120.23, 38.16], [-119.05, 37.45] ]}
}

PUT national_parks/_doc/3
{
  "name": "Death Valley National Park",
  "location": 
  {"type": "envelope","coordinates": [ [-117.34, 37.01], [-116.38, 36.25] ]}
}

location 필드에 대해 다음과 같이 집계를 실행할 수 있어요:

GET national_parks/_search
{
  "aggregations": {
    "grouped": {
      "geotile_grid": {
        "field": "location",
        "precision": 6
      }
    }
  }
}

geoshape을 집계할 때 하나의 geoshape은 여러 그리드 셀과 겹치므로 여러 버킷에 집계될 수 있어요:

{
  "took" : 3,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 3,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "national_parks",
        "_id" : "1",
        "_score" : 1.0,
        "_source" : {
          "name" : "Yellowstone National Park",
          "location" : {
            "type" : "envelope",
            "coordinates" : [
              [
                -111.15,
                45.12
              ],
              [
                -109.83,
                44.12
              ]
            ]
          }
        }
      },
      {
        "_index" : "national_parks",
        "_id" : "2",
        "_score" : 1.0,
        "_source" : {
          "name" : "Yosemite National Park",
          "location" : {
            "type" : "envelope",
            "coordinates" : [
              [
                -120.23,
                38.16
              ],
              [
                -119.05,
                37.45
              ]
            ]
          }
        }
      },
      {
        "_index" : "national_parks",
        "_id" : "3",
        "_score" : 1.0,
        "_source" : {
          "name" : "Death Valley National Park",
          "location" : {
            "type" : "envelope",
            "coordinates" : [
              [
                -117.34,
                37.01
              ],
              [
                -116.38,
                36.25
              ]
            ]
          }
        }
      }
    ]
  },
  "aggregations" : {
    "grouped" : {
      "buckets" : [
        {
          "key" : "6/12/23",
          "doc_count" : 1
        },
        {
          "key" : "6/12/22",
          "doc_count" : 1
        },
        {
          "key" : "6/11/25",
          "doc_count" : 1
        },
        {
          "key" : "6/11/24",
          "doc_count" : 1
        },
        {
          "key" : "6/10/24",
          "doc_count" : 1
        }
      ]
    }
  }
}

현재 OpenSearch는 API를 통한 geoshape 집계는 지원하지만 OpenSearch Dashboards 시각화에서는 지원하지 않아요. 시각화를 위한 geoshape 집계 구현을 보고 싶다면 관련 GitHub 이슈에 upvote하세요.

지원되는 파라미터 (Supported parameters)

Geotile grid 집계 요청은 다음 파라미터를 지원해요.

파라미터	데이터 타입	설명
field	String	geopoint를 포함하는 필드. 이 필드는 geo_point 필드로 매핑되어야 해요. 필드가 배열을 포함하면 모든 배열 값이 집계돼요. 필수.
precision	Integer	결과 버킷팅을 위한 그리드 셀을 결정하는 데 사용되는 세분성 수준. 셀은 요청된 precision의 지정된 크기(대각선)를 초과할 수 없어요. 유효한 값은 [0, 29] 범위예요. 선택. 기본값은 7이에요.
bounds	Object	geopoint 필터링을 위한 경계 상자. 경계 상자는 왼쪽 위와 오른쪽 아래 꼭짓점으로 정의돼요. 꼭짓점은 다음 형식 중 하나로 geopoint로 지정돼요:
		- 위도와 경도가 있는 객체
		- [longitude, latitude] 형식의 배열
		- "latitude,longitude" 형식의 문자열
		- geohash
		- WKT
		형식 예제는 geopoint 형식을 참고하세요. 선택.
size	Integer	반환할 버킷의 최대 수. 버킷이 size보다 많으면 OpenSearch는 문서가 더 많은 버킷을 반환해요. 선택. 기본값은 10,000이에요.
shard_size	Integer	각 샤드에서 반환할 버킷의 최대 수. 선택. 기본값은 max(10, size · number of shards)로, 더 높은 우선순위 버킷의 더 정확한 개수를 제공해요.

더 알아보기 (Learn more)

OpenSearch 공식 문서