Deprecate CommonTermsQuery and cutoff_frequency

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java

@@ -25,6 +25,7 @@
 import org.elasticsearch.common.geo.builders.CoordinatesBuilder;
 import org.elasticsearch.common.geo.builders.MultiPointBuilder;
 import org.elasticsearch.common.unit.DistanceUnit;
+import org.elasticsearch.index.query.CommonTermsQueryBuilder;
 import org.elasticsearch.index.query.GeoShapeQueryBuilder;
 import org.elasticsearch.index.query.functionscore.FunctionScoreQueryBuilder;
 import org.elasticsearch.index.query.functionscore.FunctionScoreQueryBuilder.FilterFunctionBuilder;
@@ -111,6 +112,7 @@ public void testCommonTerms() {
         commonTermsQuery("name",                                     // <1>
                          "kimchy");                                  // <2>
         // end::common_terms
+        assertWarnings(CommonTermsQueryBuilder.COMMON_TERMS_QUERY_DEPRECATION_MSG);
     }
 
     public void testConstantScore() {

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

@@ -1,6 +1,8 @@
 [[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>>]
+
 The `common` terms query is a modern alternative to stopwords which
 improves the precision and recall of search results (by taking stopwords
 into account), without sacrificing performance.
@@ -83,6 +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]
 
 The number of terms which should match can be controlled with the
 <<query-dsl-minimum-should-match,`minimum_should_match`>>
@@ -108,6 +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]
 
 which is roughly equivalent to:
 
@@ -154,6 +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]
 
 which is roughly equivalent to:
 
@@ -209,6 +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]
 
 which is roughly equivalent to:
 
@@ -270,6 +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]
 
 which is roughly equivalent to:
 

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

@@ -122,6 +122,8 @@ 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]
+
 The match query supports a `cutoff_frequency` that allows
 specifying an absolute or relative document frequency where high
 frequency terms are moved into an optional subquery and are only scored
@@ -158,6 +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]
 
 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

@@ -1,5 +1,8 @@
 ---
 "Test common terms query with stacked tokens":
+  - skip:
+      features: "warnings"
+
   - do:
       indices.create:
           index: test
@@ -47,6 +50,8 @@
           refresh: true
 
   - do:
+      warnings:
+        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
       search:
         rest_total_hits_as_int: true
         body:
@@ -62,6 +67,8 @@
   - match: { hits.hits.2._id: "3" }
 
   - do:
+      warnings:
+        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
       search:
         rest_total_hits_as_int: true
         body:
@@ -76,6 +83,8 @@
   - match: { hits.hits.1._id: "2" }
 
   - do:
+      warnings:
+        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
       search:
         rest_total_hits_as_int: true
         body:
@@ -90,6 +99,8 @@
   - match: { hits.hits.2._id: "3" }
 
   - do:
+      warnings:
+        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
       search:
         rest_total_hits_as_int: true
         body:
@@ -103,6 +114,8 @@
   - match: { hits.hits.0._id: "2" }
 
   - do:
+      warnings:
+        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
       search:
         rest_total_hits_as_int: true
         body:
@@ -118,6 +131,8 @@
   - match: { hits.hits.1._id: "1" }
 
   - do:
+      warnings:
+        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
       search:
         rest_total_hits_as_int: true
         body:
@@ -132,6 +147,8 @@
   - match: { hits.hits.0._id: "2" }
 
   - do:
+      warnings:
+        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
       search:
         rest_total_hits_as_int: true
         body:
@@ -144,6 +161,8 @@
   - match: { hits.hits.0._id: "2" }
 
   - do:
+      warnings:
+        - '[Common Terms Query] has been deprecated in favor of the MatchQuery [max_score] optimization which is applied automatically without any configuration'
       search:
         rest_total_hits_as_int: true
         body:
@@ -158,6 +177,8 @@
   - match: { hits.hits.2._id: "3" }
 
   - do:
+      warnings:
+        - '[cutoff_frequency] has been deprecated in favor of the [max_score] optimization which is applied automatically without any configuration'
       search:
         rest_total_hits_as_int: true
         body:
@@ -172,6 +193,8 @@
   - match: { hits.hits.1._id: "2" }
 
   - do:
+      warnings:
+        - '[cutoff_frequency] has been deprecated in favor of the [max_score] optimization which is applied automatically without any configuration'
       search:
         rest_total_hits_as_int: true
         body:
@@ -187,6 +210,8 @@
   - match: { hits.hits.2._id: "3" }
 
   - do:
+      warnings:
+        - '[cutoff_frequency] has been deprecated in favor of the [max_score] optimization which is applied automatically without any configuration'
       search:
         rest_total_hits_as_int: true
         body:
@@ -201,6 +226,8 @@
   - match: { hits.hits.1._id: "2" }
 
   - do:
+      warnings:
+        - '[cutoff_frequency] has been deprecated in favor of the [max_score] optimization which is applied automatically without any configuration'
       search:
         rest_total_hits_as_int: true
         body:

server/src/main/java/org/apache/lucene/queries/BlendedTermQuery.java

@@ -278,6 +278,11 @@ public int hashCode() {
         return Objects.hash(classHash(), Arrays.hashCode(equalsTerms()));
     }
 
+    /**
+     * @deprecated Since max_score optimization landed in 7.0, normal MultiMatchQuery
+     *             will achieve the same result without any configuration.
+     */
+    @Deprecated
     public static BlendedTermQuery commonTermsBlendedQuery(Term[] terms, final float[] boosts, final float maxTermFrequency) {
         return new BlendedTermQuery(terms, boosts) {
             @Override

server/src/main/java/org/apache/lucene/queries/ExtendedCommonTermsQuery.java

@@ -26,7 +26,11 @@
  * Extended version of {@link CommonTermsQuery} that allows to pass in a
  * {@code minimumNumberShouldMatch} specification that uses the actual num of high frequent terms
  * to calculate the minimum matching terms.
+ *
+ * @deprecated Since max_optimization optimization landed in 7.0, normal MatchQuery
+ *             will achieve the same result without any configuration.
  */
+@Deprecated
 public class ExtendedCommonTermsQuery extends CommonTermsQuery {
 
     public ExtendedCommonTermsQuery(Occur highFreqOccur, Occur lowFreqOccur, float maxTermFrequency) {

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

@@ -19,6 +19,7 @@
 
 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;
@@ -32,6 +33,7 @@
 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;
@@ -47,9 +49,19 @@
  * and high-frequency terms are added to an optional boolean clause. The
  * optional clause is only executed if the required "low-frequency' clause
  * matches.
+ *
+ * @deprecated Since max_optimization optimization landed in 7.0, normal MatchQuery
+ *             will achieve the same result without any configuration.
  */
+@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 NAME = "common";
 
     public static final float DEFAULT_CUTOFF_FREQ = 0.01f;
@@ -87,6 +99,7 @@ public class CommonTermsQueryBuilder extends AbstractQueryBuilder<CommonTermsQue
      * Constructs a new common terms query.
      */
     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");
         }
@@ -102,6 +115,7 @@ public CommonTermsQueryBuilder(String fieldName, Object text) {
      */
     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,12 +19,14 @@
 
 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;
@@ -42,8 +44,20 @@
  * result of the analysis.
  */
 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";
+
     public static final ParseField ZERO_TERMS_QUERY_FIELD = new ParseField("zero_terms_query");
-    public static final ParseField CUTOFF_FREQUENCY_FIELD = new ParseField("cutoff_frequency");
+    /**
+     * @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 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");
@@ -85,6 +99,10 @@ public class MatchQueryBuilder extends AbstractQueryBuilder<MatchQueryBuilder> {
 
     private MatchQuery.ZeroTermsQuery zeroTermsQuery = MatchQuery.DEFAULT_ZERO_TERMS_QUERY;
 
+    /**
+     * @deprecated See {@link MatchQueryBuilder#CUTOFF_FREQUENCY_FIELD} for more details
+     */
+    @Deprecated
     private Float cutoffFrequency = null;
 
     private boolean autoGenerateSynonymsPhraseQuery = true;
@@ -235,8 +253,12 @@ public int maxExpansions() {
      * Set a cutoff value in [0..1] (or absolute number &gt;=1) representing the
      * maximum threshold of a terms document frequency to be considered a low
      * frequency term.
+     *
+     * @deprecated see {@link MatchQueryBuilder#CUTOFF_FREQUENCY_FIELD} for more details
      */
+    @Deprecated
     public MatchQueryBuilder cutoffFrequency(float cutoff) {
+        deprecationLogger.deprecated(CUTOFF_FREQUENCY_DEPRECATION_MSG);
         this.cutoffFrequency = cutoff;
         return this;
     }