Skip to content

Commit d2e6f89

Browse files
charlotte-hoblikszabosteve
charlotte-hoblik
and
szabosteve
committed
[DOCS]: Add Vector tile search API examples (#129520)
* Add vector tile examples * Add new page to TOC * Add internal translation example * Update docs/reference/elasticsearch/rest-apis/vector-tile-search.md Co-authored-by: István Zoltán Szabó <[email protected]> * Update docs/reference/elasticsearch/rest-apis/vector-tile-search.md Co-authored-by: István Zoltán Szabó <[email protected]> --------- Co-authored-by: István Zoltán Szabó <[email protected]>
1 parent f4d593a commit d2e6f89

File tree

2 files changed

+324
-0
lines changed

2 files changed

+324
-0
lines changed

‎docs/reference/elasticsearch/rest-apis/vector-tile-search.md‎

Lines changed: 323 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,323 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/reference/8.18/search-vector-tile-api.html#search-vector-tile-api-api-example
4+
applies_to:
5+
stack: all
6+
navigation_title: Vector tile search API
7+
---
8+
9+
# Vector tile search API examples
10+
11+
This page shows how to create an index with geospatial data and retrieve vector tile results using the [vector tile search API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search-mvt-1).
12+
13+
14+
You can learn how to:
15+
- [Create an index with geospatial fields](#create-an-index-with-geospatial-fields)
16+
- [Query geospatial data using a vector tile](#query-a-vector-tile-for-geospatial-data)
17+
- [Understand the structure of the API response](#example-response)
18+
- [Understand how the request is internally translated](#how-elasticsearch-translates-the-request-internally)
19+
20+
## Create an index with geospatial fields
21+
22+
The following requests create the `museum` index and add several geospatial
23+
`location` values.
24+
25+
```console
26+
PUT museums
27+
{
28+
"mappings": {
29+
"properties": {
30+
"location": {
31+
"type": "geo_point"
32+
},
33+
"name": {
34+
"type": "keyword"
35+
},
36+
"price": {
37+
"type": "long"
38+
},
39+
"included": {
40+
"type": "boolean"
41+
}
42+
}
43+
}
44+
}
45+
46+
POST museums/_bulk?refresh
47+
{ "index": { "_id": "1" } }
48+
{ "location": "POINT (4.912350 52.374081)", "name": "NEMO Science Museum", "price": 1750, "included": true }
49+
{ "index": { "_id": "2" } }
50+
{ "location": "POINT (4.901618 52.369219)", "name": "Museum Het Rembrandthuis", "price": 1500, "included": false }
51+
{ "index": { "_id": "3" } }
52+
{ "location": "POINT (4.914722 52.371667)", "name": "Nederlands Scheepvaartmuseum", "price":1650, "included": true }
53+
{ "index": { "_id": "4" } }
54+
{ "location": "POINT (4.914722 52.371667)", "name": "Amsterdam Centre for Architecture", "price":0, "included": true }
55+
```
56+
57+
## Query a vector tile for geospatial data
58+
59+
The following request searches the index for `location` values that intersect
60+
the `13/4207/2692` vector tile.
61+
62+
```console
63+
GET museums/_mvt/location/13/4207/2692
64+
{
65+
"grid_agg": "geotile",
66+
"grid_precision": 2,
67+
"fields": [
68+
"name",
69+
"price"
70+
],
71+
"query": {
72+
"term": {
73+
"included": true
74+
}
75+
},
76+
"aggs": {
77+
"min_price": {
78+
"min": {
79+
"field": "price"
80+
}
81+
},
82+
"max_price": {
83+
"max": {
84+
"field": "price"
85+
}
86+
},
87+
"avg_price": {
88+
"avg": {
89+
"field": "price"
90+
}
91+
}
92+
}
93+
}
94+
```
95+
% TEST[continued]
96+
97+
## Example response
98+
99+
The API returns results as a binary vector tile. When decoded into JSON, the
100+
tile contains the following data:
101+
102+
```js
103+
{
104+
"hits": {
105+
"extent": 4096,
106+
"version": 2,
107+
"features": [
108+
{
109+
"geometry": {
110+
"type": "Point",
111+
"coordinates": [
112+
3208,
113+
3864
114+
]
115+
},
116+
"properties": {
117+
"_id": "1",
118+
"_index": "museums",
119+
"name": "NEMO Science Museum",
120+
"price": 1750
121+
},
122+
"type": 1
123+
},
124+
{
125+
"geometry": {
126+
"type": "Point",
127+
"coordinates": [
128+
3429,
129+
3496
130+
]
131+
},
132+
"properties": {
133+
"_id": "3",
134+
"_index": "museums",
135+
"name": "Nederlands Scheepvaartmuseum",
136+
"price": 1650
137+
},
138+
"type": 1
139+
},
140+
{
141+
"geometry": {
142+
"type": "Point",
143+
"coordinates": [
144+
3429,
145+
3496
146+
]
147+
},
148+
"properties": {
149+
"_id": "4",
150+
"_index": "museums",
151+
"name": "Amsterdam Centre for Architecture",
152+
"price": 0
153+
},
154+
"type": 1
155+
}
156+
]
157+
},
158+
"aggs": {
159+
"extent": 4096,
160+
"version": 2,
161+
"features": [
162+
{
163+
"geometry": {
164+
"type": "Polygon",
165+
"coordinates": [
166+
[
167+
[
168+
3072,
169+
3072
170+
],
171+
[
172+
4096,
173+
3072
174+
],
175+
[
176+
4096,
177+
4096
178+
],
179+
[
180+
3072,
181+
4096
182+
],
183+
[
184+
3072,
185+
3072
186+
]
187+
]
188+
]
189+
},
190+
"properties": {
191+
"_count": 3,
192+
"max_price.value": 1750.0,
193+
"min_price.value": 0.0,
194+
"avg_price.value": 1133.3333333333333
195+
},
196+
"type": 3
197+
}
198+
]
199+
},
200+
"meta": {
201+
"extent": 4096,
202+
"version": 2,
203+
"features": [
204+
{
205+
"geometry": {
206+
"type": "Polygon",
207+
"coordinates": [
208+
[
209+
[
210+
0,
211+
0
212+
],
213+
[
214+
4096,
215+
0
216+
],
217+
[
218+
4096,
219+
4096
220+
],
221+
[
222+
0,
223+
4096
224+
],
225+
[
226+
0,
227+
0
228+
]
229+
]
230+
]
231+
},
232+
"properties": {
233+
"_shards.failed": 0,
234+
"_shards.skipped": 0,
235+
"_shards.successful": 1,
236+
"_shards.total": 1,
237+
"aggregations._count.avg": 3.0,
238+
"aggregations._count.count": 1,
239+
"aggregations._count.max": 3.0,
240+
"aggregations._count.min": 3.0,
241+
"aggregations._count.sum": 3.0,
242+
"aggregations.avg_price.avg": 1133.3333333333333,
243+
"aggregations.avg_price.count": 1,
244+
"aggregations.avg_price.max": 1133.3333333333333,
245+
"aggregations.avg_price.min": 1133.3333333333333,
246+
"aggregations.avg_price.sum": 1133.3333333333333,
247+
"aggregations.max_price.avg": 1750.0,
248+
"aggregations.max_price.count": 1,
249+
"aggregations.max_price.max": 1750.0,
250+
"aggregations.max_price.min": 1750.0,
251+
"aggregations.max_price.sum": 1750.0,
252+
"aggregations.min_price.avg": 0.0,
253+
"aggregations.min_price.count": 1,
254+
"aggregations.min_price.max": 0.0,
255+
"aggregations.min_price.min": 0.0,
256+
"aggregations.min_price.sum": 0.0,
257+
"hits.max_score": 0.0,
258+
"hits.total.relation": "eq",
259+
"hits.total.value": 3,
260+
"timed_out": false,
261+
"took": 2
262+
},
263+
"type": 3
264+
}
265+
]
266+
}
267+
}
268+
```
269+
% NOTCONSOLE
270+
271+
## How Elasticsearch translates the request internally
272+
273+
{{es}} may translate a vector tile search API request with a
274+
`grid_agg` argument of `geotile` and an `exact_bounds` argument of `true`
275+
into the following search:
276+
277+
```console
278+
GET my-index/_search
279+
{
280+
"size": 10000,
281+
"query": {
282+
"geo_bounding_box": {
283+
"my-geo-field": {
284+
"top_left": {
285+
"lat": -40.979898069620134,
286+
"lon": -45
287+
},
288+
"bottom_right": {
289+
"lat": -66.51326044311186,
290+
"lon": 0
291+
}
292+
}
293+
}
294+
},
295+
"aggregations": {
296+
"grid": {
297+
"geotile_grid": {
298+
"field": "my-geo-field",
299+
"precision": 11,
300+
"size": 65536,
301+
"bounds": {
302+
"top_left": {
303+
"lat": -40.979898069620134,
304+
"lon": -45
305+
},
306+
"bottom_right": {
307+
"lat": -66.51326044311186,
308+
"lon": 0
309+
}
310+
}
311+
}
312+
},
313+
"bounds": {
314+
"geo_bounds": {
315+
"field": "my-geo-field",
316+
"wrap_longitude": false
317+
}
318+
}
319+
}
320+
}
321+
```
322+
% TEST[continued]
323+

‎docs/reference/elasticsearch/toc.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,7 @@ toc:
105105
- file: rest-apis/shard-request-cache.md
106106
- file: rest-apis/term-vectors-examples.md
107107
- file: rest-apis/update-cc-api-key-examples.md
108+
- file: rest-apis/vector-tile-search.md
108109
- file: mapping-reference/index.md
109110
children:
110111
- file: mapping-reference/document-metadata-fields.md

0 commit comments

Comments
 (0)