Deprecate _field_stats endpoint (#23914)

_field_stats has evolved quite a lot to become a multi purpose API capable of retrieving the field capabilities and the min/max value for a field.
In the mean time a more focused API called `_field_caps` has been added, this enpoint is a good replacement for _field_stats since he can
retrieve the field capabilities by just looking at the field mapping (no lookup in the index structures).
Also the recent improvement made to range queries makes the _field_stats API obsolete since this queries are now rewritten per shard based on the min/max found for the field.
This means that a range query that does not match any document in a shard can return quickly and can be cached efficiently.
For these reasons this change deprecates _field_stats. The deprecation should happen in 5.4 but we won't remove this API in 6.x yet which is why
 this PR is made directly to 6.0.
 The rest tests have also been adapted to not throw an error while this change is backported to 5.4.

core/src/main/java/org/elasticsearch/client/Client.java

@@ -456,10 +456,22 @@ public interface Client extends ElasticsearchClient, Releasable {
      */
     void clearScroll(ClearScrollRequest request, ActionListener<ClearScrollResponse> listener);
 
+    /**
+     * @deprecated Use _field_caps instead or run a min/max aggregations on the desired fields
+     */
+    @Deprecated
     FieldStatsRequestBuilder prepareFieldStats();
 
+    /**
+     * @deprecated Use _field_caps instead or run a min/max aggregations on the desired fields
+     */
+    @Deprecated
     ActionFuture<FieldStatsResponse> fieldStats(FieldStatsRequest request);
 
+    /**
+     * @deprecated Use _field_caps instead or run a min/max aggregations on the desired fields
+     */
+    @Deprecated
     void fieldStats(FieldStatsRequest request, ActionListener<FieldStatsResponse> listener);
 
     /**

core/src/main/java/org/elasticsearch/rest/action/RestFieldStatsAction.java

@@ -45,10 +45,19 @@ import static org.elasticsearch.rest.action.RestActions.buildBroadcastShardsHead
 public class RestFieldStatsAction extends BaseRestHandler {
     public RestFieldStatsAction(Settings settings, RestController controller) {
         super(settings);
-        controller.registerHandler(GET, "/_field_stats", this);
-        controller.registerHandler(POST, "/_field_stats", this);
-        controller.registerHandler(GET, "/{index}/_field_stats", this);
-        controller.registerHandler(POST, "/{index}/_field_stats", this);
+        controller.registerAsDeprecatedHandler(GET, "/_field_stats", this,
+             deprecationMessage(), deprecationLogger);
+        controller.registerAsDeprecatedHandler(POST, "/_field_stats", this,
+            deprecationMessage(), deprecationLogger);
+        controller.registerAsDeprecatedHandler(GET, "/{index}/_field_stats", this,
+            deprecationMessage(), deprecationLogger);
+        controller.registerAsDeprecatedHandler(POST, "/{index}/_field_stats", this,
+            deprecationMessage(), deprecationLogger);
+    }
+
+    static String deprecationMessage() {
+        return "[_field_stats] endpoint is deprecated! Use [_field_caps] instead or " +
+            "run a min/max aggregations on the desired fields.";
     }
 
     @Override

docs/reference/search/field-stats.asciidoc

@@ -3,6 +3,8 @@
 
 experimental[]
 
+deprecated[5.4.0, `_field_stats` is deprecated, use `_field_caps` instead or run an min/max aggregation on the desired fields]
+
 The field stats api allows one to find statistical properties of a field
 without executing a search, but looking up measurements that are natively
 available in the Lucene index. This can be useful to explore a dataset which
@@ -19,6 +21,7 @@ All indices:
 GET _field_stats?fields=rating
 --------------------------------------------------
 // CONSOLE
+// TEST[warning:[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields.]
 
 Specific indices:
 
@@ -27,6 +30,7 @@ Specific indices:
 GET twitter/_field_stats?fields=rating
 --------------------------------------------------
 // CONSOLE
+// TEST[warning:[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields.]
 // TEST[setup:twitter]
 
 Supported request options:
@@ -47,6 +51,7 @@ POST _field_stats?level=indices
 }
 --------------------------------------------------
 // CONSOLE
+// TEST[warning:[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields.]
 
 This is equivalent to the previous request.
 
@@ -122,6 +127,7 @@ Request:
 GET _field_stats?fields=rating,answer_count,creation_date,display_name
 --------------------------------------------------
 // CONSOLE
+// TEST[warning:[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields.]
 
 Response:
 
@@ -235,6 +241,7 @@ Request:
 GET _field_stats?fields=rating,answer_count,creation_date,display_name&level=indices
 --------------------------------------------------
 // CONSOLE
+// TEST[warning:[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields.]
 
 Response:
 
@@ -330,6 +337,7 @@ POST _field_stats?level=indices
 }
 --------------------------------------------------
 // CONSOLE
+// TEST[warning:[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields.]
 
 <1> The fields to compute and return field stats for.
 <2> The set index constraints. Note that index constrains can be defined for fields that aren't defined in the `fields` option.
@@ -368,5 +376,6 @@ POST _field_stats?level=indices
 }
 --------------------------------------------------
 // CONSOLE
+// TEST[warning:[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields.]
 
 <1> Custom date format

rest-api-spec/src/main/resources/rest-api-spec/test/field_caps/10_basic.yaml

@@ -76,8 +76,8 @@ setup:
 ---
 "Get simple field caps":
   - skip:
-      version: " - 5.99.99"
-      reason:  this uses a new API that has been added in 6.0
+      version: " - 5.3.99"
+      reason:  this uses a new API that has been added in 5.4.0
 
   - do:
       field_caps:
@@ -117,8 +117,8 @@ setup:
 ---
 "Get nested field caps":
   - skip:
-      version: " - 5.99.99"
-      reason:  this uses a new API that has been added in 6.0
+      version: " - 5.3.99"
+      reason:  this uses a new API that has been added in 5.4.0
 
   - do:
       field_caps:
@@ -148,8 +148,8 @@ setup:
 ---
 "Get prefix field caps":
   - skip:
-      version: " - 5.99.99"
-      reason:  this uses a new API that has been added in 6.0
+      version: " - 5.3.99"
+      reason:  this uses a new API that has been added in 5.4.0
 
   - do:
       field_caps:

rest-api-spec/src/main/resources/rest-api-spec/test/field_stats/10_basics.yaml

@@ -59,7 +59,14 @@ setup:
 
 ---
 "Basic field stats":
+  - skip:
+      version: " - 5.99.99"
+      reason:  Deprecation was added in 6.0.0
+      features: warnings
+
   - do:
+      warnings:
+          - "[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields."
       field_stats:
           fields:  [foo, number]
 
@@ -87,10 +94,13 @@ setup:
 ---
 "Geo field stats":
   - skip:
-      version: " - 5.3.0"
-      reason:  geo_point fields don't return min/max for versions greater than 5.2.0
+      version: " - 5.99.99"
+      reason:  Deprecation was added in 6.0.0
+      features: warnings
 
   - do:
+      warnings:
+          - "[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields."
       field_stats:
           fields:  [geo, geo_shape]
 
@@ -116,7 +126,14 @@ setup:
 
 ---
 "Basic field stats with level set to indices":
+  - skip:
+      version: " - 5.99.99"
+      reason:  Deprecation was added in 6.0.0
+      features: warnings
+
   - do:
+      warnings:
+          - "[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields."
       field_stats:
           fields:  [foo, number]
           level: indices
@@ -164,10 +181,13 @@ setup:
 ---
 "Geo field stats with level set to indices":
   - skip:
-      version: " - 5.3.0"
-      reason:  geo_point fields don't return min/max for versions greater than 5.2.0
+      version: " - 5.99.99"
+      reason:  Deprecation was added in 6.0.0
+      features: warnings
 
   - do:
+      warnings:
+          - "[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields."
       field_stats:
           fields:  [geo, geo_shape]
           level: indices
@@ -196,10 +216,13 @@ setup:
 ---
 "Geopoint field stats":
   - skip:
-      version: " - 5.3.0"
-      reason:  geo_point type not handled for versions earlier than 6.0.0
+      version: " - 5.99.99"
+      reason:  Deprecation was added in 6.0.0
+      features: warnings
 
   - do:
+      warnings:
+          - "[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields."
       field_stats:
           fields:  [geo]
           level: indices
@@ -216,8 +239,14 @@ setup:
 
 ---
 "Field stats with filtering":
+  - skip:
+      version: " - 5.99.99"
+      reason:  Deprecation was added in 6.0.0
+      features: warnings
 
   - do:
+      warnings:
+          - "[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields."
       field_stats:
           level:  indices
           index:  test_1
@@ -234,6 +263,8 @@ setup:
   - is_false: conflicts
 
   - do:
+      warnings:
+          - "[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields."
       field_stats:
           level:  indices
           index:  test_1
@@ -243,6 +274,11 @@ setup:
 
 ---
 "Field stats both source and fields":
+  - skip:
+      version: " - 5.99.99"
+      reason:  Deprecation was added in 6.0.0
+      features: warnings
+
   - do:
       catch: request
       field_stats:
@@ -252,7 +288,14 @@ setup:
 
 ---
 "Field stats with conflicts":
+  - skip:
+      version: " - 5.99.99"
+      reason:  Deprecation was added in 6.0.0
+      features: warnings
+
   - do:
+      warnings:
+          - "[_field_stats] endpoint is deprecated! Use [_field_caps] instead or run a min/max aggregations on the desired fields."
       field_stats:
           fields:  [foo, number, bar]