From ee1c523f778fc5dd8cf3426cfb6b1d11f6a9743d Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Tue, 17 Jun 2025 10:12:19 +0200 Subject: [PATCH 1/5] Add vector tile examples --- .../rest-apis/vector-tile-search.md | 269 ++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 docs/reference/elasticsearch/rest-apis/vector-tile-search.md diff --git a/docs/reference/elasticsearch/rest-apis/vector-tile-search.md b/docs/reference/elasticsearch/rest-apis/vector-tile-search.md new file mode 100644 index 0000000000000..b780534c0dfe6 --- /dev/null +++ b/docs/reference/elasticsearch/rest-apis/vector-tile-search.md @@ -0,0 +1,269 @@ +--- +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 +--- + +# Vector tile search 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) + +## 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 + From 3cc26db8294483e77155128ba29ced8b7d53c59d Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Tue, 17 Jun 2025 10:19:45 +0200 Subject: [PATCH 2/5] Add new page to TOC --- docs/reference/elasticsearch/toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/elasticsearch/toc.yml b/docs/reference/elasticsearch/toc.yml index 6d9cd044103fc..c7306d290cfdb 100644 --- a/docs/reference/elasticsearch/toc.yml +++ b/docs/reference/elasticsearch/toc.yml @@ -101,6 +101,7 @@ toc: - file: rest-apis/searching-with-query-rules.md - file: rest-apis/shard-request-cache.md - file: rest-apis/term-vectors-examples.md + - file: rest-apis/vector-tile-search.md - file: mapping-reference/index.md children: - file: mapping-reference/document-metadata-fields.md From 6224d4776f9ee869e1fc23b3c478ffd9907b7aba Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Wed, 18 Jun 2025 11:02:13 +0200 Subject: [PATCH 3/5] Add internal translation example --- .../rest-apis/vector-tile-search.md | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/docs/reference/elasticsearch/rest-apis/vector-tile-search.md b/docs/reference/elasticsearch/rest-apis/vector-tile-search.md index b780534c0dfe6..97a06d29cd0f0 100644 --- a/docs/reference/elasticsearch/rest-apis/vector-tile-search.md +++ b/docs/reference/elasticsearch/rest-apis/vector-tile-search.md @@ -15,6 +15,7 @@ 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 @@ -267,3 +268,56 @@ tile contains the following data: ``` % 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] + From d84fae056cb4323ad8488a04dbdc810540da938e Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik <116336412+charlotte-hoblik@users.noreply.github.com> Date: Tue, 24 Jun 2025 10:10:37 +0200 Subject: [PATCH 4/5] Update docs/reference/elasticsearch/rest-apis/vector-tile-search.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/reference/elasticsearch/rest-apis/vector-tile-search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/rest-apis/vector-tile-search.md b/docs/reference/elasticsearch/rest-apis/vector-tile-search.md index 97a06d29cd0f0..3752c9ccb0d6b 100644 --- a/docs/reference/elasticsearch/rest-apis/vector-tile-search.md +++ b/docs/reference/elasticsearch/rest-apis/vector-tile-search.md @@ -6,7 +6,7 @@ applies_to: navigation_title: Vector tile search --- -# Vector tile search examples +# 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). From eab86ff559208ffd73d47efe9522c954a1d34dc1 Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik <116336412+charlotte-hoblik@users.noreply.github.com> Date: Tue, 24 Jun 2025 10:10:47 +0200 Subject: [PATCH 5/5] Update docs/reference/elasticsearch/rest-apis/vector-tile-search.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: István Zoltán Szabó --- docs/reference/elasticsearch/rest-apis/vector-tile-search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/rest-apis/vector-tile-search.md b/docs/reference/elasticsearch/rest-apis/vector-tile-search.md index 3752c9ccb0d6b..0acb4cab14a3c 100644 --- a/docs/reference/elasticsearch/rest-apis/vector-tile-search.md +++ b/docs/reference/elasticsearch/rest-apis/vector-tile-search.md @@ -3,7 +3,7 @@ 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 +navigation_title: Vector tile search API --- # Vector tile search API examples