Deprecate CommonTerms query and CutoffFrequency of MatchQuery

relates: #4001

Author: russcam

src/Nest/QueryDsl/Abstractions/Container/IQueryContainer.cs

@@ -14,7 +14,9 @@ public interface IQueryContainer
 		IBoostingQuery Boosting { get; set; }
 
 		[DataMember(Name ="common")]
+#pragma warning disable 618
 		ICommonTermsQuery CommonTerms { get; set; }
+#pragma warning restore 618
 
 		[DataMember(Name ="constant_score")]
 		IConstantScoreQuery ConstantScore { get; set; }

src/Nest/QueryDsl/Abstractions/Container/QueryContainer-Assignments.cs

@@ -8,7 +8,9 @@ public partial class QueryContainer : IQueryContainer, IDescriptor
 	{
 		private IBoolQuery _bool;
 		private IBoostingQuery _boosting;
+#pragma warning disable 618
 		private ICommonTermsQuery _commonTerms;
+#pragma warning restore 618
 		private IConstantScoreQuery _constantScore;
 		private IDisMaxQuery _disMax;
 		private IDistanceFeatureQuery _distanceFeature;
@@ -74,11 +76,14 @@ IBoostingQuery IQueryContainer.Boosting
 			set => _boosting = Set(value);
 		}
 
+#pragma warning disable 618
 		ICommonTermsQuery IQueryContainer.CommonTerms
+
 		{
 			get => _commonTerms;
 			set => _commonTerms = Set(value);
 		}
+#pragma warning restore 618
 
 		IConstantScoreQuery IQueryContainer.ConstantScore
 		{

src/Nest/QueryDsl/Abstractions/Container/QueryContainerDescriptor.cs

@@ -187,8 +187,10 @@ public QueryContainer GeoBoundingBox(Func<GeoBoundingBoxQueryDescriptor<T>, IGeo
 		/// 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.
 		/// </summary>
+#pragma warning disable 618
 		public QueryContainer CommonTerms(Func<CommonTermsQueryDescriptor<T>, ICommonTermsQuery> selector) =>
 			WrapInContainer(selector, (query, container) => container.CommonTerms = query);
+#pragma warning restore 618
 
 		/// <summary>
 		/// The has_child query works the same as the has_child filter, by automatically wrapping the filter with a

src/Nest/QueryDsl/FullText/CommonTerms/CommonTermsQuery.cs

@@ -1,8 +1,10 @@
-using System.Runtime.Serialization;
+using System;
+using System.Runtime.Serialization;
 using Elasticsearch.Net.Utf8Json;
 
 namespace Nest
 {
+	[Obsolete("Deprecated in 7.3.0. Use MatchQuery instead, which skips blocks of documents efficiently, without any configuration, provided that the total number of hits is not tracked.")]
 	[InterfaceDataContract]
 	[JsonFormatter(typeof(FieldNameQueryFormatter<CommonTermsQuery, ICommonTermsQuery>))]
 	public interface ICommonTermsQuery : IFieldNameQuery
@@ -28,6 +30,7 @@ public interface ICommonTermsQuery : IFieldNameQuery
 		string Query { get; set; }
 	}
 
+	[Obsolete("Deprecated in 7.3.0. Use MatchQuery instead, which skips blocks of documents efficiently, without any configuration, provided that the total number of hits is not tracked.")]
 	public class CommonTermsQuery : FieldNameQueryBase, ICommonTermsQuery
 	{
 		public string Analyzer { get; set; }
@@ -43,6 +46,7 @@ public class CommonTermsQuery : FieldNameQueryBase, ICommonTermsQuery
 		internal static bool IsConditionless(ICommonTermsQuery q) => q.Field.IsConditionless() || q.Query.IsNullOrEmpty();
 	}
 
+	[Obsolete("Deprecated in 7.3.0. Use MatchQuery instead, which skips blocks of documents efficiently, without any configuration, provided that the total number of hits is not tracked.")]
 	public class CommonTermsQueryDescriptor<T>
 		: FieldNameQueryDescriptorBase<CommonTermsQueryDescriptor<T>, ICommonTermsQuery, T>
 			, ICommonTermsQuery

src/Nest/QueryDsl/FullText/Match/MatchQuery.cs

@@ -1,4 +1,5 @@
-using System.Runtime.Serialization;
+using System;
+using System.Runtime.Serialization;
 using Elasticsearch.Net.Utf8Json;
 
 namespace Nest
@@ -27,6 +28,7 @@ public interface IMatchQuery : IFieldNameQuery
 		/// or all of the low frequency terms in the case of an <see cref="Nest.Operator.And" /> match.
 		/// </summary>
 		[DataMember(Name = "cutoff_frequency")]
+		[Obsolete("Deprecated in 7.3.0. This option can be omitted since MatchQuery can skips blocks of documents efficiently if the total number of hits is not tracked.")]
 		double? CutoffFrequency { get; set; }
 
 		/// <summary>
@@ -112,6 +114,7 @@ public class MatchQuery : FieldNameQueryBase, IMatchQuery
 		public bool? AutoGenerateSynonymsPhraseQuery { get; set; }
 
 		/// <inheritdoc />
+		[Obsolete("Deprecated in 7.3.0. This option can be omitted since MatchQuery can skips blocks of documents efficiently if the total number of hits is not tracked.")]
 		public double? CutoffFrequency { get; set; }
 
 		/// <inheritdoc />
@@ -161,6 +164,7 @@ public class MatchQueryDescriptor<T>
 		protected virtual string MatchQueryType => null;
 		string IMatchQuery.Analyzer { get; set; }
 		bool? IMatchQuery.AutoGenerateSynonymsPhraseQuery { get; set; }
+		[Obsolete("Deprecated in 7.3.0. This option can be omitted since MatchQuery can skips blocks of documents efficiently if the total number of hits is not tracked.")]
 		double? IMatchQuery.CutoffFrequency { get; set; }
 		IFuzziness IMatchQuery.Fuzziness { get; set; }
 		MultiTermQueryRewrite IMatchQuery.FuzzyRewrite { get; set; }
@@ -190,6 +194,7 @@ public MatchQueryDescriptor<T> FuzzyTranspositions(bool? fuzzyTranspositions = t
 			Assign(fuzzyTranspositions, (a, v) => a.FuzzyTranspositions = v);
 
 		/// <inheritdoc cref="IMatchQuery.CutoffFrequency" />
+		[Obsolete("Deprecated in 7.3.0. This option can be omitted since MatchQuery can skips blocks of documents efficiently if the total number of hits is not tracked.")]
 		public MatchQueryDescriptor<T> CutoffFrequency(double? cutoffFrequency) => Assign(cutoffFrequency, (a, v) => a.CutoffFrequency = v);
 
 		/// <inheritdoc cref="IMatchQuery.FuzzyRewrite" />

src/Nest/QueryDsl/Query.cs

@@ -11,6 +11,7 @@ public static QueryContainer Bool(Func<BoolQueryDescriptor<T>, IBoolQuery> selec
 		public static QueryContainer Boosting(Func<BoostingQueryDescriptor<T>, IBoostingQuery> selector) =>
 			new QueryContainerDescriptor<T>().Boosting(selector);
 
+		[Obsolete("Deprecated in 7.3.0. Use MatchQuery instead, which skips blocks of documents efficiently, without any configuration, provided that the total number of hits is not tracked.")]
 		public static QueryContainer CommonTerms(Func<CommonTermsQueryDescriptor<T>, ICommonTermsQuery> selector) =>
 			new QueryContainerDescriptor<T>().CommonTerms(selector);
 

src/Nest/QueryDsl/Visitor/DslPrettyPrintVisitor.cs

@@ -49,7 +49,9 @@ public virtual void Visit(IQuery query) { }
 
 		public virtual void Visit(IBoostingQuery query) => Write("boosting");
 
+#pragma warning disable 618
 		public virtual void Visit(ICommonTermsQuery query) => Write("common_terms", query.Field);
+#pragma warning restore 618
 
 		public virtual void Visit(IConstantScoreQuery query) => Write("constant_score");
 

src/Nest/QueryDsl/Visitor/QueryVisitor.cs

@@ -28,7 +28,9 @@ public interface IQueryVisitor
 
 		void Visit(IBoostingQuery query);
 
+#pragma warning disable 618
 		void Visit(ICommonTermsQuery query);
+#pragma warning restore 618
 
 		void Visit(IConstantScoreQuery query);
 
@@ -155,7 +157,9 @@ public virtual void Visit(IBoolQuery query) { }
 
 		public virtual void Visit(IBoostingQuery query) { }
 
+#pragma warning disable 618
 		public virtual void Visit(ICommonTermsQuery query) { }
+#pragma warning restore 618
 
 		public virtual void Visit(IConstantScoreQuery query) { }
 

src/Tests/Tests/QueryDsl/FullText/CommonTerms/CommonTermsUsageTests.cs

@@ -4,6 +4,9 @@
 using Tests.Framework.EndpointTests.TestState;
 using static Nest.Infer;
 
+// CommonTerms is deprecated in 7.3.0
+#pragma warning disable 618,612
+
 namespace Tests.QueryDsl.FullText.CommonTerms
 {
 	public class CommonTermsUsageTests : QueryDslUsageTestsBase

src/Tests/Tests/QueryDsl/FullText/Match/MatchUsageTests.cs

@@ -23,7 +23,6 @@ public MatchUsageTests(ReadOnlyCluster i, EndpointUsage usage) : base(i, usage)
 			Analyzer = "standard",
 			Boost = 1.1,
 			Name = "named_query",
-			CutoffFrequency = 0.001,
 			Query = "hello world",
 			Fuzziness = Fuzziness.AutoLength(3, 6),
 			FuzzyTranspositions = true,
@@ -47,7 +46,6 @@ public MatchUsageTests(ReadOnlyCluster i, EndpointUsage usage) : base(i, usage)
 					fuzzy_rewrite = "top_terms_blended_freqs_10",
 					fuzziness = "AUTO:3,6",
 					fuzzy_transpositions = true,
-					cutoff_frequency = 0.001,
 					lenient = true,
 					minimum_should_match = 2,
 					@operator = "or",
@@ -61,7 +59,6 @@ protected override QueryContainer QueryFluent(QueryContainerDescriptor<Project>
 				.Field(p => p.Description)
 				.Analyzer("standard")
 				.Boost(1.1)
-				.CutoffFrequency(0.001)
 				.Query("hello world")
 				.Fuzziness(Fuzziness.AutoLength(3, 6))
 				.Lenient()