root
/
elasticsearch
mirror of https://github.com/elastic/elasticsearch.git
1
0
Fork 0
Code Issues Actions 1 Packages Projects Releases Wiki Activity
elasticsearch/docs/reference/search/search-vector-tile-api.asci...

756 lines
19 KiB
Plaintext
Raw Blame History

[[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.
[[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`.
`<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.
// 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[]
[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-cardinality-aggregation,`cardinality`>>
* <<search-aggregations-metrics-max-aggregation,`max`>>
* <<search-aggregations-metrics-min-aggregation,`min`>>
* <<search-aggregations-metrics-sum-aggregation,`sum`>>
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.
[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.
`<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",
"name": "NEMO Science Museum",
"price": 1750
},
"id": 0,
"type": 1
},
{
"geometry": {
"type": "Point",
"coordinates": [
3429,
3496
]
},
"properties": {
"_id": "3",
"name": "Nederlands Scheepvaartmuseum",
"price": 1650
},
"id": 0,
"type": 1
},
{
"geometry": {
"type": "Point",
"coordinates": [
3429,
3496
]
},
"properties": {
"_id": "4",
"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
Reference in New Issue View Git Blame Copy Permalink