From 1a0ab74323fdbb5296bc5ad3d17e787448c51307 Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik <116336412+charlotte-hoblik@users.noreply.github.com> Date: Tue, 24 Jun 2025 10:30:16 +0200 Subject: [PATCH] [DOCS]: Add Vector tile search API examples (#129520) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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ó * Update docs/reference/elasticsearch/rest-apis/vector-tile-search.md Co-authored-by: István Zoltán Szabó --------- Co-authored-by: István Zoltán Szabó --- .../rest-apis/vector-tile-search.md | 323 ++++++++++++++++++ docs/reference/elasticsearch/toc.yml | 1 + 2 files changed, 324 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 000000000000..0acb4cab14a3 --- /dev/null +++ b/docs/reference/elasticsearch/rest-apis/vector-tile-search.md @@ -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] + diff --git a/docs/reference/elasticsearch/toc.yml b/docs/reference/elasticsearch/toc.yml index b885a2308f8d..16bffed9e069 100644 --- a/docs/reference/elasticsearch/toc.yml +++ b/docs/reference/elasticsearch/toc.yml @@ -106,6 +106,7 @@ toc: - file: rest-apis/shard-request-cache.md - file: rest-apis/term-vectors-examples.md - file: rest-apis/update-cc-api-key-examples.md + - file: rest-apis/vector-tile-search.md - file: mapping-reference/index.md children: - file: mapping-reference/document-metadata-fields.md