# Licensed to Elasticsearch B.V. under one or more contributor # license agreements. See the NOTICE file distributed with # this work for additional information regarding copyright # ownership. Elasticsearch B.V. licenses this file to you under # the Apache License, Version 2.0 (the "License"); you may # not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, # software distributed under the License is distributed on an # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY # KIND, either express or implied. See the License for the # specific language governing permissions and limitations # under the License. # # Auto generated from commit f284cc16f4d4b4289bc679aa1529bb504190fe80 # @see https://github.com/elastic/elasticsearch-specification # module ElasticsearchServerless module API module Actions # Search a vector tile. # Search a vector tile for geospatial values. # Before using this API, you should be familiar with the Mapbox vector tile specification. # The API returns results as a binary mapbox vector tile. # Internally, Elasticsearch translates a vector tile search API request into a search containing: # * A +geo_bounding_box+ query on the ++. The query uses the +//+ tile as a bounding box. # * A +geotile_grid+ or +geohex_grid+ aggregation on the ++. The +grid_agg+ parameter determines the aggregation type. The aggregation uses the +//+ tile as a bounding box. # * Optionally, a +geo_bounds+ aggregation on the ++. The search only includes this aggregation if the +exact_bounds+ parameter is +true+. # * If the optional parameter +with_labels+ is +true+, the internal search will include a dynamic runtime field that calls the +getLabelPosition+ function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label. # For example, Elasticsearch 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 # + # 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 # } # } # } # } # + # The API returns results as a binary Mapbox vector tile. # Mapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers: # * A +hits+ layer containing a feature for each ++ value matching the +geo_bounding_box+ query. # * An +aggs+ layer containing a feature for each cell of the +geotile_grid+ or +geohex_grid+. 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+ or +geohex_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. # 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. # **Grid precision for geotile** # For a +grid_agg+ of +geotile+, you can use cells in the +aggs+ layer as tiles for lower zoom levels. # +grid_precision+ represents the additional zoom levels available through these cells. The final precision is computed by as follows: + + grid_precision+. # For example, if ++ is 7 and +grid_precision+ is 8, then the +geotile_grid+ aggregation will use a precision of 15. # The maximum final precision is 29. # The +grid_precision+ also determines the number of cells for the 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. # **Grid precision for geohex** # For a +grid_agg+ of +geohex+, Elasticsearch uses ++ and +grid_precision+ to calculate a final precision as follows: + + grid_precision+. # This precision determines the H3 resolution of the hexagonal cells produced by the +geohex+ aggregation. # The following table maps the H3 resolution for each precision. # For example, if ++ is 3 and +grid_precision+ is 3, the precision is 6. # At a precision of 6, hexagonal cells have an H3 resolution of 2. # If ++ is 3 and +grid_precision+ is 4, the precision is 7. # At a precision of 7, hexagonal cells have an H3 resolution of 3. # | Precision | Unique tile bins | H3 resolution | Unique hex bins | Ratio | # | --------- | ---------------- | ------------- | ----------------| ----- | # | 1 | 4 | 0 | 122 | 30.5 | # | 2 | 16 | 0 | 122 | 7.625 | # | 3 | 64 | 1 | 842 | 13.15625 | # | 4 | 256 | 1 | 842 | 3.2890625 | # | 5 | 1024 | 2 | 5882 | 5.744140625 | # | 6 | 4096 | 2 | 5882 | 1.436035156 | # | 7 | 16384 | 3 | 41162 | 2.512329102 | # | 8 | 65536 | 3 | 41162 | 0.6280822754 | # | 9 | 262144 | 4 | 288122 | 1.099098206 | # | 10 | 1048576 | 4 | 288122 | 0.2747745514 | # | 11 | 4194304 | 5 | 2016842 | 0.4808526039 | # | 12 | 16777216 | 6 | 14117882 | 0.8414913416 | # | 13 | 67108864 | 6 | 14117882 | 0.2103728354 | # | 14 | 268435456 | 7 | 98825162 | 0.3681524172 | # | 15 | 1073741824 | 8 | 691776122 | 0.644266719 | # | 16 | 4294967296 | 8 | 691776122 | 0.1610666797 | # | 17 | 17179869184 | 9 | 4842432842 | 0.2818666889 | # | 18 | 68719476736 | 10 | 33897029882 | 0.4932667053 | # | 19 | 274877906944 | 11 | 237279209162 | 0.8632167343 | # | 20 | 1099511627776 | 11 | 237279209162 | 0.2158041836 | # | 21 | 4398046511104 | 12 | 1660954464122 | 0.3776573213 | # | 22 | 17592186044416 | 13 | 11626681248842 | 0.6609003122 | # | 23 | 70368744177664 | 13 | 11626681248842 | 0.165225078 | # | 24 | 281474976710656 | 14 | 81386768741882 | 0.2891438866 | # | 25 | 1125899906842620 | 15 | 569707381193162 | 0.5060018015 | # | 26 | 4503599627370500 | 15 | 569707381193162 | 0.1265004504 | # | 27 | 18014398509482000 | 15 | 569707381193162 | 0.03162511259 | # | 28 | 72057594037927900 | 15 | 569707381193162 | 0.007906278149 | # | 29 | 288230376151712000 | 15 | 569707381193162 | 0.001976569537 | # Hexagonal cells don't align perfectly on a vector tile. # Some cells may intersect more than one vector tile. # To compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level. # Elasticsearch uses the H3 resolution that is closest to the corresponding geotile density. # # @option arguments [String, Array] :index Comma-separated list of data streams, indices, or aliases to search (*Required*) # @option arguments [String] :field Field containing geospatial data to return (*Required*) # @option arguments [Integer] :zoom Zoom level for the vector tile to search (*Required*) # @option arguments [Integer] :x X coordinate for the vector tile to search (*Required*) # @option arguments [Integer] :y Y coordinate for the vector tile to search (*Required*) # @option arguments [Boolean] :exact_bounds If +false+, the meta layer's feature is the bounding box of the tile. # If true, the meta layer's feature is a bounding box resulting from a # geo_bounds aggregation. The aggregation runs on values that intersect # the // tile with wrap_longitude set to false. The resulting # bounding box may be larger than the vector tile. # @option arguments [Integer] :extent The size, in pixels, of a side of the tile. Vector tiles are square with equal sides. Server default: 4096. # @option arguments [String] :grid_agg Aggregation used to create a grid for +field+. # @option arguments [Integer] :grid_precision Additional zoom levels available through the aggs layer. For example, if is 7 # and grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results # don't include the aggs layer. Server default: 8. # @option arguments [String] :grid_type Determines the geometry type for features in the aggs layer. In the aggs layer, # each feature represents a geotile_grid cell. If 'grid' each feature is a Polygon # of the cells bounding box. If 'point' each feature is a Point that is the centroid # of the cell. Server default: grid. # @option arguments [Integer] :size Maximum number of features to return in the hits layer. Accepts 0-10000. # If 0, results don't include the hits layer. Server default: 10000. # @option arguments [Boolean] :with_labels If +true+, the hits and aggs layers will contain additional point features representing # suggested label positions for the original features. # - +Point+ and +MultiPoint+ features will have one of the points selected. # - +Polygon+ and +MultiPolygon+ features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree. # - +LineString+ features will likewise provide a roughly central point selected from the triangle-tree. # - The aggregation results will provide one central point for each aggregation bucket. # All attributes from the original features will also be copied to the new label features. # In addition, the new features will be distinguishable using the tag +_mvt_label_position+. # @option arguments [Hash] :headers Custom HTTP headers # @option arguments [Hash] :body request body # # @see https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search-mvt # def search_mvt(arguments = {}) request_opts = { endpoint: arguments[:endpoint] || 'search_mvt' } defined_params = [:index, :field, :zoom, :x, :y].each_with_object({}) do |variable, set_variables| set_variables[variable] = arguments[variable] if arguments.key?(variable) end request_opts[:defined_params] = defined_params unless defined_params.empty? raise ArgumentError, "Required argument 'index' missing" unless arguments[:index] raise ArgumentError, "Required argument 'field' missing" unless arguments[:field] raise ArgumentError, "Required argument 'zoom' missing" unless arguments[:zoom] raise ArgumentError, "Required argument 'x' missing" unless arguments[:x] raise ArgumentError, "Required argument 'y' missing" unless arguments[:y] arguments = arguments.clone headers = arguments.delete(:headers) || {} body = arguments.delete(:body) _index = arguments.delete(:index) _field = arguments.delete(:field) _zoom = arguments.delete(:zoom) _x = arguments.delete(:x) _y = arguments.delete(:y) method = ElasticsearchServerless::API::HTTP_POST path = "#{Utils.listify(_index)}/_mvt/#{Utils.listify(_field)}/#{Utils.listify(_zoom)}/#{Utils.listify(_x)}/#{Utils.listify(_y)}" params = Utils.process_params(arguments) ElasticsearchServerless::API::Response.new( perform_request(method, path, params, body, headers, request_opts) ) end end end end