elasticsearch/docs/reference/search/search-vector-tile-api.asciidoc

[[search-vector-tile-api]]
=== Vector tile search API
++++
<titleabbrev>Vector tile search</titleabbrev>
++++

experimental::[]

Searches a vector tile for geospatial values. Returns results as a binary
https://docs.mapbox.com/vector-tiles/specification[Mapbox vector tile].

////
[source,console]
----
PUT my-index
{
  "mappings": {
    "properties": {
      "my-geo-field": {
        "type": "geo_point"
      }
    }
  }
}

PUT my-index/_doc/0?refresh
{
  "my-geo-field": "37.3864953,-122.0863176"
}
----
////

[source,console]
----
GET my-index/_mvt/my-geo-field/15/5271/12710
----
// TEST[continued]

[[search-vector-tile-api-request]]
==== {api-request-title}

`GET <target>/_mvt/<field>/<zoom>/<x>/<y>`

`POST <target>/_mvt/<field>/<zoom>/<x>/<y>`

[[search-vector-tile-api-prereqs]]
==== {api-prereq-title}

* Before using this API, you should be familiar with the
https://github.com/mapbox/vector-tile-spec[Mapbox vector tile specification].

* If the {es} {security-features} are enabled, you must have the `read`
<<privileges-list-indices,index privilege>> for the target data stream, index,
or alias. For cross-cluster search, see <<cross-cluster-configuring>>.

[[search-vector-tile-api-path-params]]
==== {api-path-parms-title}

`<target>`::
(Required, string) Comma-separated list of data streams, indices, or aliases to
search. Supports wildcards (`*`). To search all data streams and indices, omit
this parameter or use `*` or `_all`.
+
To search a remote cluster, use the `<cluster>:<target>` syntax. See
<<modules-cross-cluster-search>>.

`<field>`::
(Required, string) Field containing geospatial values to return. Must be a
<<geo-point,`geo_point`>> or <<geo-shape,`geo_shape`>> field. The field must
have <<doc-values,doc values>> enabled. Cannot be a nested field.
+
NOTE: Vector tiles do not natively support geometry collections. For
`geometrycollection` values in a `geo_shape` field, the API returns a `hits`
layer feature for each element of the collection. This behavior may change may
change in a future release.

`<zoom>`::
(Required, integer) Zoom level for the vector tile to search. Accepts `0`-`29`.

`<x>`::
(Required, integer) X coordinate for the vector tile to search.

`<y>`::
(Required, integer) Y coordinate for the vector tile to search.

[[search-vector-tile-api-desc]]
==== {api-description-title}

Internally, {es} translates a vector tile search API request into a
<<search-search,search>> containing:

* A <<query-dsl-geo-bounding-box-query,`geo_bounding_box`>> query on the
`<field>`. The query uses the `<zoom>/<x>/<y>` tile as a bounding box.

* A <<search-aggregations-bucket-geotilegrid-aggregation,`geotile_grid`>>
aggregation on the `<field>`. The aggregation uses the `<zoom>/<x>/<y>` tile as
a bounding box.

* Optionally, a
<<search-aggregations-metrics-geobounds-aggregation,`geo_bounds`>> aggregation
on the `<field>`. The search only includes this aggregation if the
`exact_bounds` parameter is `true`.

For example, {es} may translate a vector tile search API request with an
`exact_bounds` argument of `true` into the following search:

[source,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]

The API returns results as a binary
https://github.com/mapbox/vector-tile-spec[Mapbox vector tile]. Mapbox vector
tiles are encoded as https://github.com/protocolbuffers/protobuf[Google
Protobufs (PBF)]. By default, the tile contains three layers:

* A `hits` layer containing a feature for each `<field>` value matching the
`geo_bounding_box` query.

*  An `aggs` layer containing a feature for each cell of the `geotile_grid`. You
can use these cells as tiles for lower zoom levels. The layer only contains
features for cells with matching data.

* A `meta` layer containing:
** A feature containing a bounding box. By default, this is the bounding box of
the tile.
** Value ranges for any sub-aggregations on the `geotile_grid`.
** Metadata for the search.

The API only returns features that can display at its zoom level. For example,
if a polygon feature has no area at its zoom level, the API omits it.

The API returns errors as UTF-8 encoded JSON.

[[search-vector-tile-api-query-params]]
==== {api-query-parms-title}

IMPORTANT: You can specify several options for this API as either a query
parameter or request body parameter. If you specify both parameters, the query
parameter takes precedence.

// tag::exact-bounds[]
`exact_bounds`::
(Optional, Boolean)
If `false`, the `meta` layer's feature is the bounding box of the tile. Defaults
to `false`.
+
If `true`, the `meta` layer's feature is a bounding box resulting from a
<<search-aggregations-metrics-geobounds-aggregation,`geo_bounds`>> aggregation.
The aggregation runs on `<field>` values that intersect the `<zoom>/<x>/<y>`
tile with `wrap_longitude` set to `false`. The resulting bounding box may be
larger than the vector tile.
// end::exact-bounds[]

// tag::extent-param[]
`extent`::
(Optional, integer) Size, in pixels, of a side of the tile. Vector tiles are
square with equal sides. Defaults to `4096`.
// end::extent-param[]

// tag::grid-precision[]
`grid_precision`::
(Optional, integer) Additional zoom levels available through the `aggs` layer.
For example, if `<zoom>` is `7` and `grid_precision` is `8`, you can zoom in up to
level 15. Accepts `0`-`8`. Defaults to `8`. If `0`, results don't include the
`aggs` layer.
+
This value determines the grid size of the `geotile_grid` as follows:
+
`(2^grid_precision) x (2^grid_precision)`
+
For example, a value of `8` divides the tile into a grid of 256 x 256 cells. The
`aggs` layer only contains features for cells with matching data.
// end::grid-precision[]

// tag::grid-type[]
`grid_type`::
(Optional, string) Determines the geometry type for features in the `aggs`
layer. In the `aggs` layer, each feature represents a `geotile_grid` cell.
Accepts:

`grid` (Default):::
Each feature is a `Polygon` of the cell's bounding box.

`point`:::
Each feature is a `Point` that's the centroid of the cell.

`centroid`:::
Each feature is a `Point` that's the centroid of the data within the cell. For
complex geometries, the actual centroid may be outside the cell. In these cases,
the feature is set to the closest point to the centroid inside the cell.
// end::grid-type[]

// tag::size[]
`size`::
(Optional, integer) Maximum number of features to return in the `hits` layer.
Accepts `0`-`10000`. Defaults to `10000`. If `0`, results don't include the
`hits` layer.
// end::size[]

// tag::track_total_hits[]
`track_total_hits`::
(Optional, integer or Boolean)
Number of hits matching the query to count accurately. Defaults to `10000`.
+
If `true`, the exact number of hits is returned at the cost of some performance.
If `false`, the response does not include the total number of hits matching the query.
// end::track_total_hits[]

[role="child_attributes"]
[[search-vector-tile-api-request-body]]
==== {api-request-body-title}

`aggs`::
(Optional, <<search-aggregations,aggregation object>>)
<<run-sub-aggs,Sub-aggregations>> for the `geotile_grid`. Supports the following
aggregation types:
+
* <<search-aggregations-metrics-avg-aggregation,`avg`>>
* <<search-aggregations-metrics-boxplot-aggregation,`boxplot`>>
* <<search-aggregations-metrics-cardinality-aggregation,`cardinality`>>
* <<search-aggregations-metrics-extendedstats-aggregation,`extended stats`>>
* <<search-aggregations-metrics-max-aggregation,`max`>>
* <<search-aggregations-metrics-median-absolute-deviation-aggregation,`median absolute deviation`>>
* <<search-aggregations-metrics-min-aggregation,`min`>>
* <<search-aggregations-metrics-percentile-aggregation,`percentile`>>
* <<search-aggregations-metrics-percentile-rank-aggregation,`percentile-rank`>>
* <<search-aggregations-metrics-stats-aggregation,`stats`>>
* <<search-aggregations-metrics-sum-aggregation,`sum`>>
* <<search-aggregations-metrics-valuecount-aggregation,`value count`>>
+
The aggregation names can't start with `_mvt_`. The `_mvt_` prefix is reserved
for internal aggregations.

include::search-vector-tile-api.asciidoc[tag=exact-bounds]

include::search-vector-tile-api.asciidoc[tag=extent-param]

`fields`::
(Optional, array of strings and objects) Fields to return in the `hits` layer.
Supports wildcards (`*`).
+
This parameter does not support fields with <<array,array values>>. Fields with
array values may return inconsistent results.
+
You can specify fields in the array as a string or object.
+
.Properties of `fields` objects
[%collapsible%open]
====
include::search.asciidoc[tag=fields-api-props]
====

include::search-vector-tile-api.asciidoc[tag=grid-precision]

include::search-vector-tile-api.asciidoc[tag=grid-type]

`query`::
(Optional, object) <<query-dsl,Query DSL>> used to filter documents for the
search.

include::{es-repo-dir}/search/search.asciidoc[tag=runtime-mappings-def]

include::search-vector-tile-api.asciidoc[tag=size]

`sort`::
(Optional, array of <<sort-search-results,sort objects>>) Sorts features in the
`hits` layer.
+
By default, the API calculates a bounding box for each feature. It sorts
features based on this box's diagonal length, from longest to shortest.

include::search-vector-tile-api.asciidoc[tag=track_total_hits]

[role="child_attributes"]
[[search-vector-tile-api-response]]
==== Response

Returned vector tiles contain the following data:

`hits`::
(object) Layer containing results for the `geo_bounding_box` query.
+
.Properties of `hits`
[%collapsible%open]
====
// tag::extent[]
`extent`::
(integer) Size, in pixels, of a side of the tile. Vector tiles are square with
equal sides.
// end::extent[]

// tag::version[]
`version`::
(integer) Major version number of the
https://github.com/mapbox/vector-tile-spec[Mapbox vector tile specification].
// end::version[]

`features`::
(array of objects) Array of features. Contains a feature for each `<field>`
value that matches the `geo_bounding_box` query.
+
.Properties of `features` objects
[%collapsible%open]
=====
// tag::geometry[]
`geometry`::
(object) Geometry for the feature.
+
.Properties of `geometry`
[%collapsible%open]
======
`type`::
(string) Geometry type for the feature. Valid values are:

* `UNKNOWN`
* `POINT`
* `LINESTRING`
* `POLYGON`

`coordinates`::
(array of integers or array of arrays) Tile coordinates for the feature.
======
// end::geometry[]

`properties`::
(object) Properties for the feature.
+
.Properties of `properties`
[%collapsible%open]
======
`_id`::
(string) Document `_id` for the feature's document.

`_index`::
(string) Name of the index for the feature's document.

`<field>`::
Field value. Only returned for fields in the `fields` parameter.
======
// tag::feature-id[]
`id`::
(integer) Unique ID for the feature within the layer.
// end::feature-id[]

// tag::feature-type[]
`type`::
(integer) Identifier for the feature's geometry type. Values are:
+
* `1` (`POINT`)
* `2` (`LINESTRING`)
* `3` (`POLYGON`)
// end::feature-type[]
=====
====

`aggs`::
(object) Layer containing results for the `geotile_grid` aggregation and its
sub-aggregations.
+
.Properties of `aggs`
[%collapsible%open]
====
include::search-vector-tile-api.asciidoc[tag=extent]

include::search-vector-tile-api.asciidoc[tag=version]

`features`::
(array of objects) Array of features. Contains a feature for each cell of the
`geotile_grid`.
+
.Properties of `features` objects
[%collapsible%open]
=====
include::search-vector-tile-api.asciidoc[tag=geometry]

`properties`::
(object) Properties for the feature.
+
.Properties of `properties`
[%collapsible%open]
======
`_count`::
(string) Count of the cell's documents.

`<sub-aggregation>.value`::
Sub-aggregation results for the cell. Only returned for sub-aggregations in the
`aggs` parameter.
======
include::search-vector-tile-api.asciidoc[tag=feature-id]

include::search-vector-tile-api.asciidoc[tag=feature-type]
=====
====

`meta`::
(object) Layer containing metadata for the request.
+
.Properties of `meta`
[%collapsible%open]
====
include::search-vector-tile-api.asciidoc[tag=extent]

include::search-vector-tile-api.asciidoc[tag=version]

`features`::
(array of objects) Contains a feature for a bounding box.
+
.Properties of `features` objects
[%collapsible%open]
=====
include::search-vector-tile-api.asciidoc[tag=geometry]

`properties`::
(object) Properties for the feature.
+
.Properties of `properties`
[%collapsible%open]
======
`_shards.failed`::
(integer) Number of shards that failed to execute the search. See the search
API's <<search-api-shards,`shards`>> response property.

`_shards.skipped`::
(integer) Number of shards that skipped the search. See the search
API's <<search-api-shards,`shards`>> response property.

`_shards.successful`::
(integer)  Number of shards that executed the search successfully. See the
search API's <<search-api-shards,`shards`>> response property.

`_shards.total`::
(integer) Total number of shards that required querying, including unallocated
shards. See the search API's <<search-api-shards,`shards`>> response property.

`aggregations._count.avg`::
(float) Average `_count` value for features in the `aggs` layer.

`aggregations._count.count`::
(integer) Number of unique `_count` values for features in the `aggs` layer.

`aggregations._count.max`::
(float) Largest `_count` value for features in the `aggs` layer.

`aggregations._count.min`::
(float) Smallest `_count` value for features in the `aggs` layer.

`aggregations._count.sum`::
(float) Sum of `_count` values for features in the `aggs` layer.

`aggregations.<sub-aggregation>.avg`::
(float) Average value for the sub-aggregation's results.

`aggregations.<agg_name>.count`::
(integer) Number of unique values from the sub-aggregation's results.

`aggregations.<agg_name>.max`::
(float) Largest value from the sub-aggregation's results.

`aggregations.<agg_name>.min`::
(float) Smallest value from the sub-aggregation's results.

`aggregations.<agg_name>.sum`::
(float) Sum of values for the sub-aggregation's results.

`hits.max_score`::
(float) Highest document `_score` for the search's hits.

`hits.total.relation`::
(string) Indicates whether `hits.total.value` is accurate or a lower bound.
Possible values are:

`eq`::: Accurate

`gte`::: Lower bound

`hits.total.value`::
(integer) Total number of hits for the search.

`timed_out`::
(Boolean) If `true`, the search timed out before completion. Results may be
partial or empty.

`took`::
(integer) Milliseconds it took {es} to run the search. See the search API's
<<search-api-took,`took`>> response property.
======
include::search-vector-tile-api.asciidoc[tag=feature-id]

include::search-vector-tile-api.asciidoc[tag=feature-type]
=====
====

[[search-vector-tile-api-api-example]]
==== {api-examples-title}

The following requests create the `museum` index and add several geospatial
`location` values.

[source,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": "52.374081,4.912350", "name": "NEMO Science Museum",  "price": 1750, "included": true }
{ "index": { "_id": "2" } }
{ "location": "52.369219,4.901618", "name": "Museum Het Rembrandthuis", "price": 1500, "included": false }
{ "index": { "_id": "3" } }
{ "location": "52.371667,4.914722", "name": "Nederlands Scheepvaartmuseum", "price":1650, "included": true }
{ "index": { "_id": "4" } }
{ "location": "52.371667,4.914722", "name": "Amsterdam Centre for Architecture", "price":0, "included": true }
----

The following request searches the index for `location` values that intersect
the `13/4207/2692` vector tile.

[source,console]
----
GET museums/_mvt/location/13/4207/2692
{
  "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]

The API returns results as a binary vector tile. When decoded into JSON, the
tile contains the following data:

[source,js]
----
{
  "hits": {
    "extent": 4096,
    "version": 2,
    "features": [
      {
        "geometry": {
          "type": "Point",
          "coordinates": [
            3208,
            3864
          ]
        },
        "properties": {
          "_id": "1",
          "_index": "museums",
          "name": "NEMO Science Museum",
          "price": 1750
        },
        "id": 0,
        "type": 1
      },
      {
        "geometry": {
          "type": "Point",
          "coordinates": [
            3429,
            3496
          ]
        },
        "properties": {
          "_id": "3",
          "_index": "museums",
          "name": "Nederlands Scheepvaartmuseum",
          "price": 1650
        },
        "id": 0,
        "type": 1
      },
      {
        "geometry": {
          "type": "Point",
          "coordinates": [
            3429,
            3496
          ]
        },
        "properties": {
          "_id": "4",
          "_index": "museums",
          "name": "Amsterdam Centre for Architecture",
          "price": 0
        },
        "id": 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
        },
        "id": 0,
        "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
        },
        "id": 0,
        "type": 3
      }
    ]
  }
}
----
// NOTCONSOLE