mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-28 09:28:55 -04:00
[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ó <istvan.szabo@elastic.co> * Update docs/reference/elasticsearch/rest-apis/vector-tile-search.md Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co> --------- Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co>
This commit is contained in:
Charlotte Hoblik
GitHub
parent
fb30e59a38
commit
1a0ab74323
2 changed files with 324 additions and 0 deletions
323
docs/reference/elasticsearch/rest-apis/vector-tile-search.md
Normal file
323
docs/reference/elasticsearch/rest-apis/vector-tile-search.md
Normal file
|
|
@ -0,0 +1,323 @@
|
||||||
|
---
|
||||||
|
mapped_pages:
|
||||||
|
- https://www.elastic.co/guide/en/elasticsearch/reference/8.18/search-vector-tile-api.html#search-vector-tile-api-api-example
|
||||||
|
applies_to:
|
||||||
|
stack: all
|
||||||
|
navigation_title: Vector tile search API
|
||||||
|
---
|
||||||
|
|
||||||
|
# Vector tile search API examples
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
||||||
|
|
||||||
|
You can learn how to:
|
||||||
|
- [Create an index with geospatial fields](#create-an-index-with-geospatial-fields)
|
||||||
|
- [Query geospatial data using a vector tile](#query-a-vector-tile-for-geospatial-data)
|
||||||
|
- [Understand the structure of the API response](#example-response)
|
||||||
|
- [Understand how the request is internally translated](#how-elasticsearch-translates-the-request-internally)
|
||||||
|
|
||||||
|
## Create an index with geospatial fields
|
||||||
|
|
||||||
|
The following requests create the `museum` index and add several geospatial
|
||||||
|
`location` values.
|
||||||
|
|
||||||
|
```console
|
||||||
|
PUT museums
|
||||||
|
{
|
||||||
|
"mappings": {
|
||||||
|
"properties": {
|
||||||
|
"location": {
|
||||||
|
"type": "geo_point"
|
||||||
|
},
|
||||||
|
"name": {
|
||||||
|
"type": "keyword"
|
||||||
|
},
|
||||||
|
"price": {
|
||||||
|
"type": "long"
|
||||||
|
},
|
||||||
|
"included": {
|
||||||
|
"type": "boolean"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
POST museums/_bulk?refresh
|
||||||
|
{ "index": { "_id": "1" } }
|
||||||
|
{ "location": "POINT (4.912350 52.374081)", "name": "NEMO Science Museum", "price": 1750, "included": true }
|
||||||
|
{ "index": { "_id": "2" } }
|
||||||
|
{ "location": "POINT (4.901618 52.369219)", "name": "Museum Het Rembrandthuis", "price": 1500, "included": false }
|
||||||
|
{ "index": { "_id": "3" } }
|
||||||
|
{ "location": "POINT (4.914722 52.371667)", "name": "Nederlands Scheepvaartmuseum", "price":1650, "included": true }
|
||||||
|
{ "index": { "_id": "4" } }
|
||||||
|
{ "location": "POINT (4.914722 52.371667)", "name": "Amsterdam Centre for Architecture", "price":0, "included": true }
|
||||||
|
```
|
||||||
|
|
||||||
|
## Query a vector tile for geospatial data
|
||||||
|
|
||||||
|
The following request searches the index for `location` values that intersect
|
||||||
|
the `13/4207/2692` vector tile.
|
||||||
|
|
||||||
|
```console
|
||||||
|
GET museums/_mvt/location/13/4207/2692
|
||||||
|
{
|
||||||
|
"grid_agg": "geotile",
|
||||||
|
"grid_precision": 2,
|
||||||
|
"fields": [
|
||||||
|
"name",
|
||||||
|
"price"
|
||||||
|
],
|
||||||
|
"query": {
|
||||||
|
"term": {
|
||||||
|
"included": true
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"aggs": {
|
||||||
|
"min_price": {
|
||||||
|
"min": {
|
||||||
|
"field": "price"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"max_price": {
|
||||||
|
"max": {
|
||||||
|
"field": "price"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"avg_price": {
|
||||||
|
"avg": {
|
||||||
|
"field": "price"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
% TEST[continued]
|
||||||
|
|
||||||
|
## Example response
|
||||||
|
|
||||||
|
The API returns results as a binary vector tile. When decoded into JSON, the
|
||||||
|
tile contains the following data:
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
"hits": {
|
||||||
|
"extent": 4096,
|
||||||
|
"version": 2,
|
||||||
|
"features": [
|
||||||
|
{
|
||||||
|
"geometry": {
|
||||||
|
"type": "Point",
|
||||||
|
"coordinates": [
|
||||||
|
3208,
|
||||||
|
3864
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"properties": {
|
||||||
|
"_id": "1",
|
||||||
|
"_index": "museums",
|
||||||
|
"name": "NEMO Science Museum",
|
||||||
|
"price": 1750
|
||||||
|
},
|
||||||
|
"type": 1
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"geometry": {
|
||||||
|
"type": "Point",
|
||||||
|
"coordinates": [
|
||||||
|
3429,
|
||||||
|
3496
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"properties": {
|
||||||
|
"_id": "3",
|
||||||
|
"_index": "museums",
|
||||||
|
"name": "Nederlands Scheepvaartmuseum",
|
||||||
|
"price": 1650
|
||||||
|
},
|
||||||
|
"type": 1
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"geometry": {
|
||||||
|
"type": "Point",
|
||||||
|
"coordinates": [
|
||||||
|
3429,
|
||||||
|
3496
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"properties": {
|
||||||
|
"_id": "4",
|
||||||
|
"_index": "museums",
|
||||||
|
"name": "Amsterdam Centre for Architecture",
|
||||||
|
"price": 0
|
||||||
|
},
|
||||||
|
"type": 1
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"aggs": {
|
||||||
|
"extent": 4096,
|
||||||
|
"version": 2,
|
||||||
|
"features": [
|
||||||
|
{
|
||||||
|
"geometry": {
|
||||||
|
"type": "Polygon",
|
||||||
|
"coordinates": [
|
||||||
|
[
|
||||||
|
[
|
||||||
|
3072,
|
||||||
|
3072
|
||||||
|
],
|
||||||
|
[
|
||||||
|
4096,
|
||||||
|
3072
|
||||||
|
],
|
||||||
|
[
|
||||||
|
4096,
|
||||||
|
4096
|
||||||
|
],
|
||||||
|
[
|
||||||
|
3072,
|
||||||
|
4096
|
||||||
|
],
|
||||||
|
[
|
||||||
|
3072,
|
||||||
|
3072
|
||||||
|
]
|
||||||
|
]
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"properties": {
|
||||||
|
"_count": 3,
|
||||||
|
"max_price.value": 1750.0,
|
||||||
|
"min_price.value": 0.0,
|
||||||
|
"avg_price.value": 1133.3333333333333
|
||||||
|
},
|
||||||
|
"type": 3
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"meta": {
|
||||||
|
"extent": 4096,
|
||||||
|
"version": 2,
|
||||||
|
"features": [
|
||||||
|
{
|
||||||
|
"geometry": {
|
||||||
|
"type": "Polygon",
|
||||||
|
"coordinates": [
|
||||||
|
[
|
||||||
|
[
|
||||||
|
0,
|
||||||
|
0
|
||||||
|
],
|
||||||
|
[
|
||||||
|
4096,
|
||||||
|
0
|
||||||
|
],
|
||||||
|
[
|
||||||
|
4096,
|
||||||
|
4096
|
||||||
|
],
|
||||||
|
[
|
||||||
|
0,
|
||||||
|
4096
|
||||||
|
],
|
||||||
|
[
|
||||||
|
0,
|
||||||
|
0
|
||||||
|
]
|
||||||
|
]
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"properties": {
|
||||||
|
"_shards.failed": 0,
|
||||||
|
"_shards.skipped": 0,
|
||||||
|
"_shards.successful": 1,
|
||||||
|
"_shards.total": 1,
|
||||||
|
"aggregations._count.avg": 3.0,
|
||||||
|
"aggregations._count.count": 1,
|
||||||
|
"aggregations._count.max": 3.0,
|
||||||
|
"aggregations._count.min": 3.0,
|
||||||
|
"aggregations._count.sum": 3.0,
|
||||||
|
"aggregations.avg_price.avg": 1133.3333333333333,
|
||||||
|
"aggregations.avg_price.count": 1,
|
||||||
|
"aggregations.avg_price.max": 1133.3333333333333,
|
||||||
|
"aggregations.avg_price.min": 1133.3333333333333,
|
||||||
|
"aggregations.avg_price.sum": 1133.3333333333333,
|
||||||
|
"aggregations.max_price.avg": 1750.0,
|
||||||
|
"aggregations.max_price.count": 1,
|
||||||
|
"aggregations.max_price.max": 1750.0,
|
||||||
|
"aggregations.max_price.min": 1750.0,
|
||||||
|
"aggregations.max_price.sum": 1750.0,
|
||||||
|
"aggregations.min_price.avg": 0.0,
|
||||||
|
"aggregations.min_price.count": 1,
|
||||||
|
"aggregations.min_price.max": 0.0,
|
||||||
|
"aggregations.min_price.min": 0.0,
|
||||||
|
"aggregations.min_price.sum": 0.0,
|
||||||
|
"hits.max_score": 0.0,
|
||||||
|
"hits.total.relation": "eq",
|
||||||
|
"hits.total.value": 3,
|
||||||
|
"timed_out": false,
|
||||||
|
"took": 2
|
||||||
|
},
|
||||||
|
"type": 3
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
% NOTCONSOLE
|
||||||
|
|
||||||
|
## How Elasticsearch translates the request internally
|
||||||
|
|
||||||
|
{{es}} may translate a vector tile search API request with a
|
||||||
|
`grid_agg` argument of `geotile` and an `exact_bounds` argument of `true`
|
||||||
|
into the following search:
|
||||||
|
|
||||||
|
```console
|
||||||
|
GET my-index/_search
|
||||||
|
{
|
||||||
|
"size": 10000,
|
||||||
|
"query": {
|
||||||
|
"geo_bounding_box": {
|
||||||
|
"my-geo-field": {
|
||||||
|
"top_left": {
|
||||||
|
"lat": -40.979898069620134,
|
||||||
|
"lon": -45
|
||||||
|
},
|
||||||
|
"bottom_right": {
|
||||||
|
"lat": -66.51326044311186,
|
||||||
|
"lon": 0
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"aggregations": {
|
||||||
|
"grid": {
|
||||||
|
"geotile_grid": {
|
||||||
|
"field": "my-geo-field",
|
||||||
|
"precision": 11,
|
||||||
|
"size": 65536,
|
||||||
|
"bounds": {
|
||||||
|
"top_left": {
|
||||||
|
"lat": -40.979898069620134,
|
||||||
|
"lon": -45
|
||||||
|
},
|
||||||
|
"bottom_right": {
|
||||||
|
"lat": -66.51326044311186,
|
||||||
|
"lon": 0
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"bounds": {
|
||||||
|
"geo_bounds": {
|
||||||
|
"field": "my-geo-field",
|
||||||
|
"wrap_longitude": false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
% TEST[continued]
|
||||||
|
|
||||||
|
|
@ -106,6 +106,7 @@ toc:
|
||||||
- file: rest-apis/shard-request-cache.md
|
- file: rest-apis/shard-request-cache.md
|
||||||
- file: rest-apis/term-vectors-examples.md
|
- file: rest-apis/term-vectors-examples.md
|
||||||
- file: rest-apis/update-cc-api-key-examples.md
|
- file: rest-apis/update-cc-api-key-examples.md
|
||||||
|
- file: rest-apis/vector-tile-search.md
|
||||||
- file: mapping-reference/index.md
|
- file: mapping-reference/index.md
|
||||||
children:
|
children:
|
||||||
- file: mapping-reference/document-metadata-fields.md
|
- file: mapping-reference/document-metadata-fields.md
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue