Update geo_shape/query docs, fix TermStrategy defaults

This commit adds the following:
* SpatialStrategy documentation to the geo-shape reference docs.
* Updates relation documentation to geo-shape-query reference docs.
* Updates GeoShapeFiledMapper to set points_only to true if TERM strategy is used (to be consistent with documentation)

core/src/main/java/org/elasticsearch/index/mapper/geo/GeoShapeFieldMapper.java

@@ -193,7 +193,8 @@ public class GeoShapeFieldMapper extends FieldMapper {
                 } else if (Names.COERCE.equals(fieldName)) {
                     builder.coerce(nodeBooleanValue(fieldNode));
                     iterator.remove();
-                } else if (Names.STRATEGY_POINTS_ONLY.equals(fieldName)) {
+                } else if (Names.STRATEGY_POINTS_ONLY.equals(fieldName)
+                    && builder.fieldType().strategyName.equals(SpatialStrategy.TERM.getStrategyName()) == false) {
                     builder.fieldType().setPointsOnly(XContentMapValues.nodeBooleanValue(fieldNode));
                     iterator.remove();
                 }
@@ -284,6 +285,7 @@ public class GeoShapeFieldMapper extends FieldMapper {
             termStrategy = new TermQueryPrefixTreeStrategy(prefixTree, names().indexName());
             termStrategy.setDistErrPct(distanceErrorPct());
             defaultStrategy = resolveStrategy(strategyName);
+            defaultStrategy.setPointsOnly(pointsOnly);
         }
 
         @Override
@@ -347,6 +349,9 @@ public class GeoShapeFieldMapper extends FieldMapper {
         public void setStrategyName(String strategyName) {
             checkIfFrozen();
             this.strategyName = strategyName;
+            if (this.strategyName.equals(SpatialStrategy.TERM)) {
+                this.pointsOnly = true;
+            }
         }
 
         public boolean pointsOnly() {
@@ -406,7 +411,6 @@ public class GeoShapeFieldMapper extends FieldMapper {
 
         public PrefixTreeStrategy resolveStrategy(String strategyName) {
             if (SpatialStrategy.RECURSIVE.getStrategyName().equals(strategyName)) {
-                recursiveStrategy.setPointsOnly(pointsOnly());
                 return recursiveStrategy;
             }
             if (SpatialStrategy.TERM.getStrategyName().equals(strategyName)) {
@@ -446,7 +450,7 @@ public class GeoShapeFieldMapper extends FieldMapper {
                 }
                 shape = shapeBuilder.build();
             }
-            if (fieldType().defaultStrategy() instanceof RecursivePrefixTreeStrategy && fieldType().pointsOnly() && !(shape instanceof Point)) {
+            if (fieldType().pointsOnly() && !(shape instanceof Point)) {
                 throw new MapperParsingException("[{" + fieldType().names().fullName() + "}] is configured for points only but a " +
                         ((shape instanceof JtsGeometry) ? ((JtsGeometry)shape).getGeom().getGeometryType() : shape.getClass()) + " was found");
             }

docs/reference/mapping/types/geo-shape.asciidoc

@@ -17,13 +17,13 @@ The geo_shape mapping maps geo_json geometry objects to the geo_shape
 type. To enable it, users must explicitly map fields to the geo_shape
 type.
 
-[cols="<,<",options="header",]
+[cols="<,<,<",options="header",]
 |=======================================================================
-|Option |Description
+|Option |Description| Default
 
 |`tree` |Name of the PrefixTree implementation to be used: `geohash` for
-GeohashPrefixTree and `quadtree` for QuadPrefixTree. Defaults to
-`geohash`.
+GeohashPrefixTree and `quadtree` for QuadPrefixTree.
+| `geohash`
 
 |`precision` |This parameter may be used instead of `tree_levels` to set
 an appropriate value for the `tree_levels` parameter. The value
@@ -31,7 +31,8 @@ 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` (default), `cm`,`centimeters`, `mm`, `millimeters`.
+`m`,`meters`, `cm`,`centimeters`, `mm`, `millimeters`.
+| `meters`
 
 |`tree_levels` |Maximum number of layers to be used by the PrefixTree.
 This can be used to control the precision of shape representations and
@@ -41,27 +42,40 @@ 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.
+| `50m`
+
+|`strategy` |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`. 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
+<<prefix-trees, Prefix trees>> for more detailed information)
+| `recursive`
 
 |`distance_error_pct` |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 be default to 0 if a `precision` or
+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.
+| `0.025`
 
 |`orientation` |Optionally define how to interpret vertex order for
 polygons / multipolygons.  This parameter defines one of two coordinate
 system rules (Right-hand or Left-hand) each of which can be specified in three
-different ways. 1. Right-hand rule (default): `right`, `ccw`, `counterclockwise`,
+different ways. 1. Right-hand rule: `right`, `ccw`, `counterclockwise`,
 2. Left-hand rule: `left`, `cw`, `clockwise`. The default orientation
 (`counterclockwise`) complies with the OGC standard which defines
 outer ring vertices in counterclockwise order with inner ring(s) vertices (holes)
 in clockwise order. Setting this parameter in the geo_shape mapping explicitly
 sets vertex order for the coordinate list of a geo_shape field but can be
 overridden in each individual GeoJSON document.
+| `ccw`
 
 |`points_only` |Setting this option to `true` (defaults to `false`) configures
 the `geo_shape` field type for point shapes only (NOTE: Multi-Points are not
@@ -70,18 +84,21 @@ yet supported). This optimizes index and search performance for the `geohash` an
 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`
 
 
 |=======================================================================
 
+[[prefix-trees]]
 [float]
 ==== Prefix trees
 
 To efficiently represent shapes in the index, Shapes are converted into
-a series of hashes representing grid squares 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.
+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.
 
 Multiple PrefixTree implementations are provided:
 
@@ -100,6 +117,29 @@ 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
 amount of levels for the quad trees in Elasticsearch is 50.
 
+[[spatial-strategy]]
+[float]
+===== Spatial strategies
+The PrefixTree implementations rely on a SpatialStrategy for decomposing
+the provided Shape(s) into approximated grid squares. 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` |<<input-structure, All>> |`INTERSECTS`, `DISJOINT`, `WITHIN`, `CONTAINS` |Yes
+|`term` |<<point, Points>> |`INTERSECTS` |Yes
+
+|=======================================================================
+
 [float]
 ===== Accuracy
 
@@ -149,6 +189,7 @@ 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.
 
+[[input-structure]]
 [float]
 ==== Input Structure
 
@@ -189,6 +230,7 @@ differs from many Geospatial APIs (e.g., Google Maps) that generally
 use the colloquial latitude, longitude (Y, X).
 =============================================
 
+[[point]]
 [float]
 ===== http://geojson.org/geojson-spec.html#id2[Point]
 

docs/reference/query-dsl/geo-shape-query.asciidoc

@@ -104,7 +104,10 @@ shape:
 
 ==== Spatial Relations
 
-The Query supports the following spatial relations:
+The <<spatial-strategy, geo_shape strategy>> mapping parameter determines
+which spatial relation operators may be used at search time.
+
+The following is a complete list of spatial relation operators available:
 
 * `INTERSECTS` - (default) Return all documents whose `geo_shape` field
 intersects the query geometry.