From e798bb26cf848d53eb09a39e8650f43186e6fae4 Mon Sep 17 00:00:00 2001 From: Jim Ferenczi Date: Wed, 5 Apr 2017 09:29:26 +0200 Subject: [PATCH] Deprecate _field_stats endpoint _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. --- .../java/org/elasticsearch/client/Client.java | 12 ++++ .../rest/action/RestFieldStatsAction.java | 17 ++++-- docs/reference/search/field-stats.asciidoc | 9 +++ .../test/field_caps/10_basic.yaml | 12 ++-- .../test/field_stats/10_basics.yaml | 55 +++++++++++++++++-- 5 files changed, 89 insertions(+), 16 deletions(-) diff --git a/core/src/main/java/org/elasticsearch/client/Client.java b/core/src/main/java/org/elasticsearch/client/Client.java index 663b820dc3956..2080856e30204 100644 --- a/core/src/main/java/org/elasticsearch/client/Client.java +++ b/core/src/main/java/org/elasticsearch/client/Client.java @@ -456,10 +456,22 @@ public interface Client extends ElasticsearchClient, Releasable { */ void clearScroll(ClearScrollRequest request, ActionListener 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 fieldStats(FieldStatsRequest request); + /** + * @deprecated Use _field_caps instead or run a min/max aggregations on the desired fields + */ + @Deprecated void fieldStats(FieldStatsRequest request, ActionListener listener); /** diff --git a/core/src/main/java/org/elasticsearch/rest/action/RestFieldStatsAction.java b/core/src/main/java/org/elasticsearch/rest/action/RestFieldStatsAction.java index 1393f42937207..34e7b636aeb09 100644 --- a/core/src/main/java/org/elasticsearch/rest/action/RestFieldStatsAction.java +++ b/core/src/main/java/org/elasticsearch/rest/action/RestFieldStatsAction.java @@ -45,10 +45,19 @@ 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 diff --git a/docs/reference/search/field-stats.asciidoc b/docs/reference/search/field-stats.asciidoc index 78ce9e41f8ff8..2b4a48651293e 100644 --- a/docs/reference/search/field-stats.asciidoc +++ b/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 diff --git a/rest-api-spec/src/main/resources/rest-api-spec/test/field_caps/10_basic.yaml b/rest-api-spec/src/main/resources/rest-api-spec/test/field_caps/10_basic.yaml index edda7b6dbf3d0..cef72b6e3fe43 100644 --- a/rest-api-spec/src/main/resources/rest-api-spec/test/field_caps/10_basic.yaml +++ b/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: diff --git a/rest-api-spec/src/main/resources/rest-api-spec/test/field_stats/10_basics.yaml b/rest-api-spec/src/main/resources/rest-api-spec/test/field_stats/10_basics.yaml index 4e6cbd616232e..907432d2d668e 100644 --- a/rest-api-spec/src/main/resources/rest-api-spec/test/field_stats/10_basics.yaml +++ b/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]