Deprecate CommonTermsQuery and cutoff_frequency

docs/reference/query-dsl/common-terms-query.asciidoc

@@ -1,7 +1,7 @@
 [[query-dsl-common-terms-query]]
 === Common Terms Query
 
-deprecated[7.3.0,Replaced by the more performant `max_score` optimization which is applied automatically without any configuration on a <<query-dsl-match-query>>]
+deprecated[7.3.0,`<<query-dsl-match-query>>` which can efficiently skip blocks of documents if the total number of hits is not tracked]
 
 The `common` terms query is a modern alternative to stopwords which
 improves the precision and recall of search results (by taking stopwords
@@ -85,7 +85,7 @@ GET /_search
 }
 --------------------------------------------------
 // CONSOLE
-// TEST[warning:[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration]
+// TEST[warning:Deprecated field [common] used, replaced by [[match] query which can efficiently skip blocks of documents if the total number of hits is not tracked]]
 
 The number of terms which should match can be controlled with the
 <<query-dsl-minimum-should-match,`minimum_should_match`>>
@@ -111,7 +111,7 @@ GET /_search
 }
 --------------------------------------------------
 // CONSOLE
-// TEST[warning:[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration]
+// TEST[warning:Deprecated field [common] used, replaced by [[match] query which can efficiently skip blocks of documents if the total number of hits is not tracked]]
 
 which is roughly equivalent to:
 
@@ -158,7 +158,7 @@ GET /_search
 }
 --------------------------------------------------
 // CONSOLE
-// TEST[warning:[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration]
+// TEST[warning:Deprecated field [common] used, replaced by [[match] query which can efficiently skip blocks of documents if the total number of hits is not tracked]]
 
 which is roughly equivalent to:
 
@@ -214,7 +214,7 @@ GET /_search
 }
 --------------------------------------------------
 // CONSOLE
-// TEST[warning:[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration]
+// TEST[warning:Deprecated field [common] used, replaced by [[match] query which can efficiently skip blocks of documents if the total number of hits is not tracked]]
 
 which is roughly equivalent to:
 
@@ -276,7 +276,7 @@ GET /_search
 }
 --------------------------------------------------
 // CONSOLE
-// TEST[warning:[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration]
+// TEST[warning:Deprecated field [common] used, replaced by [[match] query which can efficiently skip blocks of documents if the total number of hits is not tracked]]
 
 which is roughly equivalent to:
 

docs/reference/query-dsl/match-query.asciidoc

@@ -122,7 +122,7 @@ GET /_search
 [[query-dsl-match-query-cutoff]]
 ===== Cutoff frequency
 
-deprecated[7.3.0,Replaced by the more performant `max_score` optimization which is applied automatically without any configuration]
+deprecated[7.3.0,"This option can be omitted as the <<query-dsl-match-query>> can skip block of documents efficiently, without any configuration, provided that the total number of hits is not tracked."]
 
 The match query supports a `cutoff_frequency` that allows
 specifying an absolute or relative document frequency where high
@@ -160,7 +160,7 @@ GET /_search
 }
 --------------------------------------------------
 // CONSOLE
-// TEST[warning:[cutoff_frequency] has been deprecated in favor of the [max_score] optimization which is applied automatically without any configuration]
+// TEST[warning:Deprecated field [cutoff_frequency] used, replaced by [you can omit this option, the [match] query can skip block of documents efficiently if the total number of hits is not tracked]]
 
 IMPORTANT: The `cutoff_frequency` option operates on a per-shard-level. This means
 that when trying it out on test indexes with low document numbers you

modules/analysis-common/src/test/resources/rest-api-spec/test/search.query/50_queries_with_synonyms.yml

@@ -51,7 +51,7 @@
 
   - do:
       warnings:
-        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
+        - 'Deprecated field [common] used, replaced by [[match] query which can efficiently skip blocks of documents if the total number of hits is not tracked]'
       search:
         rest_total_hits_as_int: true
         body:
@@ -68,7 +68,7 @@
 
   - do:
       warnings:
-        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
+        - 'Deprecated field [common] used, replaced by [[match] query which can efficiently skip blocks of documents if the total number of hits is not tracked]'
       search:
         rest_total_hits_as_int: true
         body:
@@ -84,7 +84,7 @@
 
   - do:
       warnings:
-        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
+        - 'Deprecated field [common] used, replaced by [[match] query which can efficiently skip blocks of documents if the total number of hits is not tracked]'
       search:
         rest_total_hits_as_int: true
         body:
@@ -100,7 +100,7 @@
 
   - do:
       warnings:
-        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
+        - 'Deprecated field [common] used, replaced by [[match] query which can efficiently skip blocks of documents if the total number of hits is not tracked]'
       search:
         rest_total_hits_as_int: true
         body:
@@ -115,7 +115,7 @@
 
   - do:
       warnings:
-        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
+        - 'Deprecated field [common] used, replaced by [[match] query which can efficiently skip blocks of documents if the total number of hits is not tracked]'
       search:
         rest_total_hits_as_int: true
         body:
@@ -132,7 +132,7 @@
 
   - do:
       warnings:
-        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
+        - 'Deprecated field [common] used, replaced by [[match] query which can efficiently skip blocks of documents if the total number of hits is not tracked]'
       search:
         rest_total_hits_as_int: true
         body:
@@ -148,7 +148,7 @@
 
   - do:
       warnings:
-        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
+        - 'Deprecated field [common] used, replaced by [[match] query which can efficiently skip blocks of documents if the total number of hits is not tracked]'
       search:
         rest_total_hits_as_int: true
         body:
@@ -162,7 +162,7 @@
 
   - do:
       warnings:
-        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
+        - 'Deprecated field [common] used, replaced by [[match] query which can efficiently skip blocks of documents if the total number of hits is not tracked]'
       search:
         rest_total_hits_as_int: true
         body:
@@ -178,7 +178,7 @@
 
   - do:
       warnings:
-        - '[cutoff_frequency] has been deprecated in favor of the [max_score] optimization which is applied automatically without any configuration'
+        - 'Deprecated field [cutoff_frequency] used, replaced by [you can omit this option, the [match] query can skip block of documents efficiently if the total number of hits is not tracked]'
       search:
         rest_total_hits_as_int: true
         body:
@@ -194,7 +194,7 @@
 
   - do:
       warnings:
-        - '[cutoff_frequency] has been deprecated in favor of the [max_score] optimization which is applied automatically without any configuration'
+        - 'Deprecated field [cutoff_frequency] used, replaced by [you can omit this option, the [match] query can skip block of documents efficiently if the total number of hits is not tracked]'
       search:
         rest_total_hits_as_int: true
         body:
@@ -211,7 +211,7 @@
 
   - do:
       warnings:
-        - '[cutoff_frequency] has been deprecated in favor of the [max_score] optimization which is applied automatically without any configuration'
+        - 'Deprecated field [cutoff_frequency] used, replaced by [you can omit this option, the [match] query can skip block of documents efficiently if the total number of hits is not tracked]'
       search:
         rest_total_hits_as_int: true
         body:
@@ -227,7 +227,7 @@
 
   - do:
       warnings:
-        - '[cutoff_frequency] has been deprecated in favor of the [max_score] optimization which is applied automatically without any configuration'
+        - 'Deprecated field [cutoff_frequency] used, replaced by [you can omit this option, the [multi_match] query can skip block of documents efficiently if the total number of hits is not tracked]'
       search:
         rest_total_hits_as_int: true
         body:

server/src/main/java/org/elasticsearch/index/query/CommonTermsQueryBuilder.java

@@ -19,7 +19,6 @@
 
 package org.elasticsearch.index.query;
 
-import org.apache.logging.log4j.LogManager;
 import org.apache.lucene.analysis.Analyzer;
 import org.apache.lucene.analysis.TokenStream;
 import org.apache.lucene.analysis.tokenattributes.CharTermAttribute;
@@ -33,7 +32,6 @@
 import org.elasticsearch.common.Strings;
 import org.elasticsearch.common.io.stream.StreamInput;
 import org.elasticsearch.common.io.stream.StreamOutput;
-import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.common.xcontent.XContentBuilder;
 import org.elasticsearch.common.xcontent.XContentParser;
 import org.elasticsearch.index.mapper.MappedFieldType;
@@ -56,11 +54,8 @@
 @Deprecated
 public class CommonTermsQueryBuilder extends AbstractQueryBuilder<CommonTermsQueryBuilder> {
 
-    private static final DeprecationLogger deprecationLogger =
-        new DeprecationLogger(LogManager.getLogger(CommonTermsQueryBuilder.class));
-
-    public static final String COMMON_TERMS_QUERY_DEPRECATION_MSG = "[Common Terms Query] has been deprecated in favor of the " +
-        "MatchQuery [max_score] optimization which is applied automatically without any configuration";
+    public static final String COMMON_TERMS_QUERY_DEPRECATION_MSG = "[match] query which can efficiently " +
+        "skip blocks of documents if the total number of hits is not tracked";
 
     public static final String NAME = "common";
 
@@ -97,9 +92,10 @@ public class CommonTermsQueryBuilder extends AbstractQueryBuilder<CommonTermsQue
 
     /**
      * Constructs a new common terms query.
+     * @deprecated See {@link CommonTermsQueryBuilder} for more details.
      */
+    @Deprecated
     public CommonTermsQueryBuilder(String fieldName, Object text) {
-        deprecationLogger.deprecated(COMMON_TERMS_QUERY_DEPRECATION_MSG);
         if (Strings.isEmpty(fieldName)) {
             throw new IllegalArgumentException("field name is null or empty");
         }
@@ -112,10 +108,11 @@ public CommonTermsQueryBuilder(String fieldName, Object text) {
 
     /**
      * Read from a stream.
+     * @deprecated See {@link CommonTermsQueryBuilder} for more details.
      */
+    @Deprecated
     public CommonTermsQueryBuilder(StreamInput in) throws IOException {
         super(in);
-        deprecationLogger.deprecated(COMMON_TERMS_QUERY_DEPRECATION_MSG);
         fieldName = in.readString();
         text = in.readGenericValue();
         highFreqOperator = Operator.readFromStream(in);

server/src/main/java/org/elasticsearch/index/query/MatchQueryBuilder.java

@@ -19,14 +19,12 @@
 
 package org.elasticsearch.index.query;
 
-import org.apache.logging.log4j.LogManager;
 import org.apache.lucene.search.FuzzyQuery;
 import org.apache.lucene.search.Query;
 import org.elasticsearch.common.ParseField;
 import org.elasticsearch.common.ParsingException;
 import org.elasticsearch.common.io.stream.StreamInput;
 import org.elasticsearch.common.io.stream.StreamOutput;
-import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.common.lucene.search.Queries;
 import org.elasticsearch.common.unit.Fuzziness;
 import org.elasticsearch.common.xcontent.LoggingDeprecationHandler;
@@ -45,19 +43,17 @@
  */
 public class MatchQueryBuilder extends AbstractQueryBuilder<MatchQueryBuilder> {
 
-    private static final DeprecationLogger deprecationLogger =
-        new DeprecationLogger(LogManager.getLogger(MatchQueryBuilder.class));
-
-    static final String CUTOFF_FREQUENCY_DEPRECATION_MSG = "[cutoff_frequency] has been deprecated in favor of the " +
-        "[max_score] optimization which is applied automatically without any configuration";
+    private static final String CUTOFF_FREQUENCY_DEPRECATION_MSG = "you can omit this option, " +
+        "the [match] query can skip block of documents efficiently if the total number of hits is not tracked";
 
     public static final ParseField ZERO_TERMS_QUERY_FIELD = new ParseField("zero_terms_query");
     /**
      * @deprecated Since max_optimization optimization landed in 7.0, normal MatchQuery
      *             will achieve the same result without any configuration.
      */
     @Deprecated
-    public static final ParseField CUTOFF_FREQUENCY_FIELD = new ParseField("cutoff_frequency", "cutoff_frequency");
+    public static final ParseField CUTOFF_FREQUENCY_FIELD =
+        new ParseField("cutoff_frequency").withAllDeprecated(CUTOFF_FREQUENCY_DEPRECATION_MSG);
     public static final ParseField LENIENT_FIELD = new ParseField("lenient");
     public static final ParseField FUZZY_TRANSPOSITIONS_FIELD = new ParseField("fuzzy_transpositions");
     public static final ParseField FUZZY_REWRITE_FIELD = new ParseField("fuzzy_rewrite");
@@ -254,7 +250,6 @@ public int maxExpansions() {
      */
     @Deprecated
     public MatchQueryBuilder cutoffFrequency(float cutoff) {
-        deprecationLogger.deprecated(CUTOFF_FREQUENCY_DEPRECATION_MSG);
         this.cutoffFrequency = cutoff;
         return this;
     }

server/src/main/java/org/elasticsearch/index/query/MultiMatchQueryBuilder.java

@@ -19,7 +19,6 @@
 
 package org.elasticsearch.index.query;
 
-import org.apache.logging.log4j.LogManager;
 import org.apache.lucene.search.FuzzyQuery;
 import org.apache.lucene.search.Query;
 import org.elasticsearch.ElasticsearchParseException;
@@ -29,7 +28,6 @@
 import org.elasticsearch.common.io.stream.StreamInput;
 import org.elasticsearch.common.io.stream.StreamOutput;
 import org.elasticsearch.common.io.stream.Writeable;
-import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.common.unit.Fuzziness;
 import org.elasticsearch.common.xcontent.DeprecationHandler;
 import org.elasticsearch.common.xcontent.LoggingDeprecationHandler;
@@ -53,11 +51,8 @@
  */
 public class MultiMatchQueryBuilder extends AbstractQueryBuilder<MultiMatchQueryBuilder> {
 
-    private static final DeprecationLogger deprecationLogger =
-        new DeprecationLogger(LogManager.getLogger(MultiMatchQueryBuilder.class));
-
-    static final String CUTOFF_FREQUENCY_DEPRECATION_MSG = "[cutoff_frequency] has been deprecated in favor of the " +
-        "[max_score] optimization which is applied automatically without any configuration";
+    private static final String CUTOFF_FREQUENCY_DEPRECATION_MSG = "you can omit this option, " +
+        "the [multi_match] query can skip block of documents efficiently if the total number of hits is not tracked";
 
     public static final String NAME = "multi_match";
 
@@ -72,7 +67,8 @@ public class MultiMatchQueryBuilder extends AbstractQueryBuilder<MultiMatchQuery
     private static final ParseField SLOP_FIELD = new ParseField("slop");
     private static final ParseField ZERO_TERMS_QUERY_FIELD = new ParseField("zero_terms_query");
     private static final ParseField LENIENT_FIELD = new ParseField("lenient");
-    private static final ParseField CUTOFF_FREQUENCY_FIELD = new ParseField("cutoff_frequency", "cutoff_frequency");
+    private static final ParseField CUTOFF_FREQUENCY_FIELD =
+        new ParseField("cutoff_frequency").withAllDeprecated(CUTOFF_FREQUENCY_DEPRECATION_MSG);
     private static final ParseField TIE_BREAKER_FIELD = new ParseField("tie_breaker");
     private static final ParseField FUZZY_REWRITE_FIELD = new ParseField("fuzzy_rewrite");
     private static final ParseField MINIMUM_SHOULD_MATCH_FIELD = new ParseField("minimum_should_match");
@@ -499,7 +495,6 @@ public boolean lenient() {
      */
     @Deprecated
     public MultiMatchQueryBuilder cutoffFrequency(float cutoff) {
-        deprecationLogger.deprecated(CUTOFF_FREQUENCY_DEPRECATION_MSG);
         this.cutoffFrequency = cutoff;
         return this;
     }
@@ -514,9 +509,6 @@ public MultiMatchQueryBuilder cutoffFrequency(float cutoff) {
      */
     @Deprecated
     public MultiMatchQueryBuilder cutoffFrequency(Float cutoff) {
-        if (cutoff != null) {
-            deprecationLogger.deprecated(CUTOFF_FREQUENCY_DEPRECATION_MSG);
-        }
         this.cutoffFrequency = cutoff;
         return this;
     }

server/src/main/java/org/elasticsearch/search/SearchModule.java

@@ -21,6 +21,7 @@
 
 import org.apache.lucene.search.BooleanQuery;
 import org.elasticsearch.common.NamedRegistry;
+import org.elasticsearch.common.ParseField;
 import org.elasticsearch.common.geo.GeoShapeType;
 import org.elasticsearch.common.geo.ShapesAvailability;
 import org.elasticsearch.common.io.stream.NamedWriteableRegistry;
@@ -32,7 +33,6 @@
 import org.elasticsearch.common.xcontent.ParseFieldRegistry;
 import org.elasticsearch.common.xcontent.XContentParser;
 import org.elasticsearch.index.query.BoolQueryBuilder;
-import org.elasticsearch.index.query.MatchBoolPrefixQueryBuilder;
 import org.elasticsearch.index.query.BoostingQueryBuilder;
 import org.elasticsearch.index.query.CommonTermsQueryBuilder;
 import org.elasticsearch.index.query.ConstantScoreQueryBuilder;
@@ -49,6 +49,7 @@
 import org.elasticsearch.index.query.IntervalQueryBuilder;
 import org.elasticsearch.index.query.IntervalsSourceProvider;
 import org.elasticsearch.index.query.MatchAllQueryBuilder;
+import org.elasticsearch.index.query.MatchBoolPrefixQueryBuilder;
 import org.elasticsearch.index.query.MatchNoneQueryBuilder;
 import org.elasticsearch.index.query.MatchPhrasePrefixQueryBuilder;
 import org.elasticsearch.index.query.MatchPhraseQueryBuilder;
@@ -271,6 +272,7 @@
 
 import static java.util.Collections.unmodifiableMap;
 import static java.util.Objects.requireNonNull;
+import static org.elasticsearch.index.query.CommonTermsQueryBuilder.COMMON_TERMS_QUERY_DEPRECATION_MSG;
 import static org.elasticsearch.index.query.SpanNearQueryBuilder.SpanGapQueryBuilder;
 
 /**
@@ -767,7 +769,8 @@ private void registerQueryParsers(List<SearchPlugin> plugins) {
         registerQuery(new QuerySpec<>(MoreLikeThisQueryBuilder.NAME, MoreLikeThisQueryBuilder::new,
                 MoreLikeThisQueryBuilder::fromXContent));
         registerQuery(new QuerySpec<>(WrapperQueryBuilder.NAME, WrapperQueryBuilder::new, WrapperQueryBuilder::fromXContent));
-        registerQuery(new QuerySpec<>(CommonTermsQueryBuilder.NAME, CommonTermsQueryBuilder::new, CommonTermsQueryBuilder::fromXContent));
+        registerQuery(new QuerySpec<>(new ParseField(CommonTermsQueryBuilder.NAME).withAllDeprecated(COMMON_TERMS_QUERY_DEPRECATION_MSG),
+                CommonTermsQueryBuilder::new, CommonTermsQueryBuilder::fromXContent));
         registerQuery(
                 new QuerySpec<>(SpanMultiTermQueryBuilder.NAME, SpanMultiTermQueryBuilder::new, SpanMultiTermQueryBuilder::fromXContent));
         registerQuery(new QuerySpec<>(FunctionScoreQueryBuilder.NAME, FunctionScoreQueryBuilder::new,