From 8810fc7a96e96a7372afb7e28dd2c6ae49ff3280 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Wed, 23 Jun 2021 14:26:15 -0400 Subject: [PATCH] [DOCS] Remove deprecated `geo_shape` parameters * Removes docs and references for the following `geo_shape` mapping parameters: * `tree` * `tree_levels` * `strategy` * `distance_error_pct` * Updates a related breaking change. --- .../ingest/processors/enrich.asciidoc | 2 +- .../mapping/types/geo-shape.asciidoc | 183 +----------------- .../migration/migrate_8_0/mappings.asciidoc | 23 +-- docs/reference/query-dsl.asciidoc | 2 - .../query-dsl/geo-shape-query.asciidoc | 9 - 5 files changed, 16 insertions(+), 203 deletions(-) diff --git a/docs/reference/ingest/processors/enrich.asciidoc b/docs/reference/ingest/processors/enrich.asciidoc index a7cd21a408663..431c089744aad 100644 --- a/docs/reference/ingest/processors/enrich.asciidoc +++ b/docs/reference/ingest/processors/enrich.asciidoc @@ -20,7 +20,7 @@ See <> section for more information about how | `ignore_missing` | no | false | If `true` and `field` does not exist, the processor quietly exits without modifying the document | `override` | no | true | If processor will update fields with pre-existing non-null-valued field. When set to `false`, such fields will not be touched. | `max_matches` | no | 1 | The maximum number of matched documents to include under the configured target field. The `target_field` will be turned into a json array if `max_matches` is higher than 1, otherwise `target_field` will become a json object. In order to avoid documents getting too large, the maximum allowed value is 128. -| `shape_relation` | no | `INTERSECTS` | A spatial relation operator used to match the <> of incoming documents to documents in the enrich index. This option is only used for `geo_match` enrich policy types. The <> mapping parameter determines which spatial relation operators are available. See <<_spatial_relations>> for operators and more information. +| `shape_relation` | no | `INTERSECTS` | A spatial relation operator used to match the <> of incoming documents to documents in the enrich index. This option is only used for `geo_match` enrich policy types. See <<_spatial_relations>> for operators and more information. include::common-options.asciidoc[] |====== diff --git a/docs/reference/mapping/types/geo-shape.asciidoc b/docs/reference/mapping/types/geo-shape.asciidoc index caea17a6121a6..7365ae074006d 100644 --- a/docs/reference/mapping/types/geo-shape.asciidoc +++ b/docs/reference/mapping/types/geo-shape.asciidoc @@ -24,61 +24,6 @@ type. |======================================================================= |Option |Description| Default -|`tree` |deprecated[6.6, PrefixTrees no longer used] Name of the PrefixTree -implementation to be used: `geohash` for GeohashPrefixTree and `quadtree` -for QuadPrefixTree. Note: This parameter is only relevant for `term` and -`recursive` strategies. -| `quadtree` - -|`precision` |deprecated[6.6, PrefixTrees no longer used] This parameter may -be used instead of `tree_levels` to set an appropriate value for the -`tree_levels` parameter. The value specifies the desired precision and -Elasticsearch will calculate the best tree_levels value to honor this -precision. The value should be a number followed by an optional distance -unit. Valid distance units include: `in`, `inch`, `yd`, `yard`, `mi`, -`miles`, `km`, `kilometers`, `m`,`meters`, `cm`,`centimeters`, `mm`, -`millimeters`. Note: This parameter is only relevant for `term` and -`recursive` strategies. -| `50m` - -|`tree_levels` |deprecated[6.6, PrefixTrees no longer used] Maximum number -of layers to be used by the PrefixTree. This can be used to control the -precision of shape representations andtherefore how many terms are -indexed. Defaults to the default value of the chosen PrefixTree -implementation. Since this parameter requires a certain level of -understanding of the underlying implementation, users may use the -`precision` parameter instead. However, Elasticsearch only uses the -tree_levels parameter internally and this is what is returned via the -mapping API even if you use the precision parameter. Note: This parameter -is only relevant for `term` and `recursive` strategies. -| various - -|`strategy` |deprecated[6.6, PrefixTrees no longer used] The strategy -parameter defines the approach for how to represent shapes at indexing -and search time. It also influences the capabilities available so it -is recommended to let Elasticsearch set this parameter automatically. -There are two strategies available: `recursive`, and `term`. -Recursive and Term strategies are deprecated and will be removed in a -future version. While they are still available, the Term strategy -supports point types only (the `points_only` parameter will be -automatically set to true) while Recursive strategy supports all -shape types. (IMPORTANT: see <> for more -detailed information about these strategies) -| `recursive` - -|`distance_error_pct` |deprecated[6.6, PrefixTrees no longer used] Used as a -hint to the PrefixTree about how precise it should be. Defaults to 0.025 (2.5%) -with 0.5 as the maximum supported value. PERFORMANCE NOTE: This value will -default to 0 if a `precision` or `tree_level` definition is explicitly defined. -This guarantees spatial precision at the level defined in the mapping. This can -lead to significant memory usage for high resolution shapes with low error -(e.g., large shapes at 1m with < 0.001 error). To improve indexing performance -(at the cost of query accuracy) explicitly define `tree_level` or `precision` -along with a reasonable `distance_error_pct`, noting that large shapes will have -greater false positives. Note: This parameter is only relevant for `term` and -`recursive` strategies. -| `0.025` - |`orientation` a|Optional. Vertex order for the shape's coordinates list. @@ -106,15 +51,6 @@ ring (hole) vertices in clockwise order. Individual GeoJSON or WKT documents can override this parameter. | `RIGHT` -|`points_only` |deprecated[6.6, PrefixTrees no longer used] Setting this option to -`true` (defaults to `false`) configures the `geo_shape` field type for point -shapes only (NOTE: Multi-Points are not yet supported). This optimizes index and -search performance for the `geohash` and `quadtree` when it is known that only points -will be indexed. At present geo_shape queries can not be executed on `geo_point` -field types. This option bridges the gap by improving point performance on a -`geo_shape` field so that `geo_shape` queries are optimal on a point only field. -| `false` - |`ignore_malformed` |If true, malformed GeoJSON or WKT shapes are ignored. If false (default), malformed GeoJSON and WKT shapes throw an exception and reject the entire document. @@ -139,86 +75,8 @@ GeoShape types are indexed by decomposing the shape into a triangular mesh and indexing each triangle as a 7 dimension point in a BKD tree. This provides near perfect spatial resolution (down to 1e-7 decimal degree precision) since all spatial relations are computed using an encoded vector representation of the -original shape instead of a raster-grid representation as used by the -<> indexing approach. Performance of the tessellator primarily -depends on the number of vertices that define the polygon/multi-polygon. While -this is the default indexing technique prefix trees can still be used by setting -the `tree` or `strategy` parameters according to the appropriate -<>. Note that these parameters are now deprecated -and will be removed in a future version. - -*IMPORTANT NOTES* - -`CONTAINS` relation query - when using the new default vector indexing strategy, `geo_shape` -queries with `relation` defined as `contains` are supported for indices created with -ElasticSearch 7.5.0 or higher. - - -[[prefix-trees]] -[discrete] -==== Prefix trees - -deprecated[6.6, PrefixTrees no longer used] To efficiently represent shapes in -an inverted index, Shapes are converted into a series of hashes representing -grid squares (commonly referred to as "rasters") using implementations of a -PrefixTree. The tree notion comes from the fact that the PrefixTree uses multiple -grid layers, each with an increasing level of precision to represent the Earth. -This can be thought of as increasing the level of detail of a map or image at higher -zoom levels. Since this approach causes precision issues with indexed shape, it has -been deprecated in favor of a vector indexing approach that indexes the shapes as a -triangular mesh (see <>). - -Multiple PrefixTree implementations are provided: - -* GeohashPrefixTree - Uses -{wikipedia}/Geohash[geohashes] for grid squares. -Geohashes are base32 encoded strings of the bits of the latitude and -longitude interleaved. So the longer the hash, the more precise it is. -Each character added to the geohash represents another tree level and -adds 5 bits of precision to the geohash. A geohash represents a -rectangular area and has 32 sub rectangles. The maximum number of levels -in Elasticsearch is 24; the default is 9. -* QuadPrefixTree - Uses a -{wikipedia}/Quadtree[quadtree] for grid squares. -Similar to geohash, quad trees interleave the bits of the latitude and -longitude the resulting hash is a bit set. A tree level in a quad tree -represents 2 bits in this bit set, one for each coordinate. The maximum -number of levels for the quad trees in Elasticsearch is 29; the default is 21. - -[[spatial-strategy]] -[discrete] -===== Spatial strategies -deprecated[6.6, PrefixTrees no longer used] The indexing implementation -selected relies on a SpatialStrategy for choosing how to decompose the shapes -(either as grid squares or a tessellated triangular mesh). Each strategy -answers the following: - -* What type of Shapes can be indexed? -* What types of Query Operations and Shapes can be used? -* Does it support more than one Shape per field? - -The following Strategy implementations (with corresponding capabilities) -are provided: - -[cols="<,<,<,<",options="header",] -|======================================================================= -|Strategy |Supported Shapes |Supported Queries |Multiple Shapes - -|`recursive` |<> |`INTERSECTS`, `DISJOINT`, `WITHIN`, `CONTAINS` |Yes -|`term` |<> |`INTERSECTS` |Yes - -|======================================================================= - -[discrete] -===== Accuracy - -`Recursive` and `Term` strategies do not provide 100% accuracy and depending on -how they are configured it may return some false positives for `INTERSECTS`, -`WITHIN` and `CONTAINS` queries, and some false negatives for `DISJOINT` queries. -To mitigate this, it is important to select an appropriate value for the tree_levels -parameter and to adjust expectations accordingly. For example, a point may be near -the border of a particular grid cell and may thus not match a query that only matches -the cell right next to it -- even though the shape is very close to the point. +original shape. Performance of the tessellator primarily +depends on the number of vertices that define the polygon/multi-polygon. [discrete] ===== Example @@ -238,33 +96,6 @@ PUT /example -------------------------------------------------- // TESTSETUP -This mapping definition maps the location field to the geo_shape -type using the default vector implementation. It provides -approximately 1e-7 decimal degree precision. - -[discrete] -===== Performance considerations with Prefix Trees - -deprecated[6.6, PrefixTrees no longer used] With prefix trees, -Elasticsearch uses the paths in the tree as terms in the inverted index -and in queries. The higher the level (and thus the precision), the more -terms are generated. Of course, calculating the terms, keeping them in -memory, and storing them on disk all have a price. Especially with higher -tree levels, indices can become extremely large even with a modest amount -of data. Additionally, the size of the features also matters. Big, complex -polygons can take up a lot of space at higher tree levels. Which setting -is right depends on the use case. Generally one trades off accuracy against -index size and query performance. - -The defaults in Elasticsearch for both implementations are a compromise -between index size and a reasonable level of precision of 50m at the -equator. This allows for indexing tens of millions of shapes without -overly bloating the resulting index too much relative to the input size. - -[NOTE] -Geo-shape queries on geo-shapes implemented with PrefixTrees will not be executed if -<> is set to false. - [[input-structure]] [discrete] ==== Input Structure @@ -292,8 +123,6 @@ points. and a LineString). |`N/A` |`BBOX` |`envelope` |A bounding rectangle, or envelope, specified by specifying only the top left and bottom right points. -|`N/A` |`N/A` |`circle` |A circle specified by a center point and radius with -units, which default to `METERS`. |======================================================================= [NOTE] @@ -641,16 +470,10 @@ POST /example/_doc [discrete] ===== Circle -Elasticsearch supports a `circle` type, which consists of a center -point with a radius. - -IMPORTANT: You cannot index the `circle` type using the default -<>. Instead, use a +Neither GeoJSON nor WKT supports a point-radius circle type. Instead, use a <> to approximate the circle as a <>. -*NOTE:* Neither GeoJSON or WKT support a point-radius circle type. - [discrete] ==== Sorting and Retrieving index Shapes diff --git a/docs/reference/migration/migrate_8_0/mappings.asciidoc b/docs/reference/migration/migrate_8_0/mappings.asciidoc index 3d6ac3e24f4a5..18441036e9297 100644 --- a/docs/reference/migration/migrate_8_0/mappings.asciidoc +++ b/docs/reference/migration/migrate_8_0/mappings.asciidoc @@ -94,22 +94,23 @@ mappings with java-time formats. For a detailed migration guide, see the {ref}/migrate-to-java-time.html[Java time migration guide]. ==== -// end::notable-breaking-changes[] [[geo-shape-strategy]] -.The `strategy` parameter on `geo_shape` mappings now rejects unknown strategies. +.Several `geo_shape` mapping parameters have been removed. [%collapsible] ==== *Details* + -The only permissible values for the `strategy` parameter on `geo_shape` mappings -are `term` and `recursive`. In 7.x if a non-permissible value was used as a -parameter here, the mapping would silently fall back to using `recursive`. The -mapping will now be rejected instead. +The following `geo_shape` mapping parameters were deprecated in 6.6: + +* `tree` +* `tree_levels` +* `strategy` +* `distance_error_pct` + +These parameters have been removed in 8.0.0. *Impact* + -This will have no impact on existing mappings created with non-permissible -strategy values, as they will already be serializing themselves as if they -had been configured as `recursive`. New indexes will need to use one of the -permissible strategies, or preferably not define a strategy at all and use -the far more efficient BKD index. +In 8.0, you can no longer create mappings that include these parameters. +However, 7.x indices that use these mapping parameters will continue to work. ==== +// end::notable-breaking-changes[] diff --git a/docs/reference/query-dsl.asciidoc b/docs/reference/query-dsl.asciidoc index 35af3104d0594..c2d8718f06bb3 100644 --- a/docs/reference/query-dsl.asciidoc +++ b/docs/reference/query-dsl.asciidoc @@ -49,8 +49,6 @@ the stability of the cluster. Those queries can be categorised as follows: * <> -* Queries on <> - * Queries that may have a high per-document cost: ** <> ** <> diff --git a/docs/reference/query-dsl/geo-shape-query.asciidoc b/docs/reference/query-dsl/geo-shape-query.asciidoc index bc2bc63b83dde..da0f42327188a 100644 --- a/docs/reference/query-dsl/geo-shape-query.asciidoc +++ b/docs/reference/query-dsl/geo-shape-query.asciidoc @@ -230,9 +230,6 @@ GET /example/_search ==== Spatial Relations -The <> mapping parameter determines which -spatial relation operators may be used at search time. - The following is a complete list of spatial relation operators available when searching a geo field: @@ -257,12 +254,6 @@ is not mapped. [[geo-shape-query-notes]] ==== Notes -* Geo-shape queries on geo-shapes implemented with - <> will not be executed if - <> is set - to false. - - * When data is indexed in a `geo_shape` field as an array of shapes, the arrays are treated as one shape. For this reason, the following requests are equivalent.