Skip to content

Commit efcfaee

Browse files
talevytalevy
committed
add geo_shape documentation for supported aggregations (#58284)
This commit adds documentation for geo_shape fields in aggregations Closes #55495.
1 parent ca1829c commit efcfaee

File tree

5 files changed

+168
-4
lines changed

5 files changed

+168
-4
lines changed

‎docs/reference/aggregations/bucket/geohashgrid-aggregation.asciidoc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -268,6 +268,16 @@ Cell dimensions vary with latitude and so the table is for the worst-case scenar
268268
12:: 3.7cm x 1.9cm
269269

270270

271+
[discrete]
272+
[role="xpack"]
273+
==== Aggregating `geo_shape` fields
274+
275+
Aggregating on <<geo-shape>> fields works just as it does for points, except that a single
276+
shape can be counted for in multiple tiles. A shape will contribute to the count of matching values
277+
if any part of its shape intersects with that tile. Below is an image that demonstrates this
278+
279+
280+
image:images/spatial/geoshape_grid.png[]
271281

272282
==== Options
273283

‎docs/reference/aggregations/bucket/geotilegrid-aggregation.asciidoc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,6 +219,17 @@ POST /museums/_search?size=0
219219
--------------------------------------------------
220220
// TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
221221

222+
[discrete]
223+
[role="xpack"]
224+
==== Aggregating `geo_shape` fields
225+
226+
Aggregating on <<geo-shape>> fields works just as it does for points, except that a single
227+
shape can be counted for in multiple tiles. A shape will contribute to the count of matching values
228+
if any part of its shape intersects with that tile. Below is an image that demonstrates this
229+
230+
231+
image:images/spatial/geoshape_grid.png[]
232+
222233
==== Options
223234

224235
[horizontal]

‎docs/reference/aggregations/metrics/geobounds-aggregation.asciidoc‎

Lines changed: 63 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[[search-aggregations-metrics-geobounds-aggregation]]
22
=== Geo Bounds Aggregation
33

4-
A metric aggregation that computes the bounding box containing all geo_point values for a field.
4+
A metric aggregation that computes the bounding box containing all geo values for a field.
55

66

77
Example:
@@ -77,3 +77,65 @@ The response for the above aggregation:
7777
}
7878
--------------------------------------------------
7979
// TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
80+
81+
[discrete]
82+
[role="xpack"]
83+
==== Geo Bounds Aggregation on `geo_shape` fields
84+
85+
The Geo Bounds Aggregation is also supported on `geo_shape` fields.
86+
87+
Example:
88+
89+
[source,console]
90+
--------------------------------------------------
91+
PUT /places
92+
{
93+
"mappings": {
94+
"properties": {
95+
"geometry": {
96+
"type": "geo_shape"
97+
}
98+
}
99+
}
100+
}
101+
102+
POST /places/_bulk?refresh
103+
{"index":{"_id":1}}
104+
{"name": "NEMO Science Museum", "geometry": "POINT(4.912350 52.374081)" }
105+
{"index":{"_id":2}}
106+
{"name": "Sportpark De Weeren", "geometry": { "type": "Polygon", "coordinates": [ [ [ 4.965305328369141, 52.39347642069457 ], [ 4.966979026794433, 52.391721758934835 ], [ 4.969425201416015, 52.39238958618537 ], [ 4.967944622039794, 52.39420969150824 ], [ 4.965305328369141, 52.39347642069457 ] ] ] } }
107+
108+
POST /places/_search?size=0
109+
{
110+
"aggs" : {
111+
"viewport" : {
112+
"geo_bounds" : {
113+
"field" : "geometry"
114+
}
115+
}
116+
}
117+
}
118+
--------------------------------------------------
119+
// TEST
120+
121+
[source,console-result]
122+
--------------------------------------------------
123+
{
124+
...
125+
"aggregations": {
126+
"viewport": {
127+
"bounds": {
128+
"top_left": {
129+
"lat": 52.39420966710895,
130+
"lon": 4.912349972873926
131+
},
132+
"bottom_right": {
133+
"lat": 52.374080987647176,
134+
"lon": 4.969425117596984
135+
}
136+
}
137+
}
138+
}
139+
}
140+
--------------------------------------------------
141+
// TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]

‎docs/reference/aggregations/metrics/geocentroid-aggregation.asciidoc‎

Lines changed: 84 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[[search-aggregations-metrics-geocentroid-aggregation]]
22
=== Geo Centroid Aggregation
33

4-
A metric aggregation that computes the weighted https://en.wikipedia.org/wiki/Centroid[centroid] from all coordinate values for a <<geo-point>> field.
4+
A metric aggregation that computes the weighted https://en.wikipedia.org/wiki/Centroid[centroid] from all coordinate values for geo fields.
55

66
Example:
77

@@ -144,6 +144,87 @@ The response for the above aggregation:
144144
--------------------------------------------------
145145
// TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
146146

147+
148+
[discrete]
149+
[role="xpack"]
150+
==== Geo Centroid Aggregation on `geo_shape` fields
151+
152+
The centroid metric for geo-shapes is more nuanced than for points. The centroid of a specific aggregation bucket
153+
containing shapes is the centroid of the highest-dimensionality shape type in the bucket. For example, if a bucket contains
154+
shapes comprising of polygons and lines, then the lines do not contribute to the centroid metric. Each type of shape's
155+
centroid is calculated differently. Envelopes and circles ingested via the <<ingest-circle-processor>> are treated
156+
as polygons.
157+
158+
|===
159+
|Geometry Type | Centroid Calculation
160+
161+
|[Multi]Point
162+
|equally weighted average of all the coordinates
163+
164+
|[Multi]LineString
165+
|a weighted average of all the centroids of each segment, where the weight of each segment is its length in degrees
166+
167+
|[Multi]Polygon
168+
|a weighted average of all the centroids of all the triangles of a polygon where the triangles are formed by every two consecutive vertices and the starting-point.
169+
holes have negative weights. weights represent the area of the triangle in deg^2 calculated
170+
171+
|GeometryCollection
172+
|The centroid of all the underlying geometries with the highest dimension. If Polygons and Lines and/or Points, then lines and/or points are ignored.
173+
If Lines and Points, then points are ignored
174+
|===
175+
176+
Example:
177+
178+
[source,console]
179+
--------------------------------------------------
180+
PUT /places
181+
{
182+
"mappings": {
183+
"properties": {
184+
"geometry": {
185+
"type": "geo_shape"
186+
}
187+
}
188+
}
189+
}
190+
191+
POST /places/_bulk?refresh
192+
{"index":{"_id":1}}
193+
{"name": "NEMO Science Museum", "geometry": "POINT(4.912350 52.374081)" }
194+
{"index":{"_id":2}}
195+
{"name": "Sportpark De Weeren", "geometry": { "type": "Polygon", "coordinates": [ [ [ 4.965305328369141, 52.39347642069457 ], [ 4.966979026794433, 52.391721758934835 ], [ 4.969425201416015, 52.39238958618537 ], [ 4.967944622039794, 52.39420969150824 ], [ 4.965305328369141, 52.39347642069457 ] ] ] } }
196+
197+
POST /places/_search?size=0
198+
{
199+
"aggs" : {
200+
"centroid" : {
201+
"geo_centroid" : {
202+
"field" : "geometry"
203+
}
204+
}
205+
}
206+
}
207+
--------------------------------------------------
208+
// TEST
209+
210+
[source,console-result]
211+
--------------------------------------------------
212+
{
213+
...
214+
"aggregations": {
215+
"centroid": {
216+
"location": {
217+
"lat": 52.39296147599816,
218+
"lon": 4.967404240742326
219+
},
220+
"count": 2
221+
}
222+
}
223+
}
224+
--------------------------------------------------
225+
// TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
226+
227+
147228
[WARNING]
148229
.Using `geo_centroid` as a sub-aggregation of `geohash_grid`
149230
====
@@ -152,8 +233,8 @@ aggregation places documents, not individual geo-points, into buckets. If a
152233
document's `geo_point` field contains <<array,multiple values>>, the document
153234
could be assigned to multiple buckets, even if one or more of its geo-points are
154235
outside the bucket boundaries.
155-
236+
156237
If a `geocentroid` sub-aggregation is also used, each centroid is calculated
157238
using all geo-points in a bucket, including those outside the bucket boundaries.
158239
This can result in centroids outside of bucket boundaries.
159-
====
240+
====

‎docs/reference/images/spatial/geoshape_grid.png‎

255 KB
Loading

0 commit comments

Comments
 (0)