Add linear function to rank_feature query (#5373) (#5391)

* Add linear function to rank_feature query

* Update docs and skip version in tests

Co-authored-by: Steve Gordon <[email protected]>

Author: github-actions[bot]

docs/query-dsl/specialized/rank-feature/rank-feature-query-usage.asciidoc

@@ -99,3 +99,41 @@ new RankFeatureQuery
 }
 ----
 
+==== Fluent DSL example
+
+[source,csharp]
+----
+q
+.RankFeature(rf => rf
+    .Name("named_query")
+    .Boost(1.1)
+    .Field(f => f.Rank)
+    .Linear())
+----
+
+==== Object Initializer syntax example
+
+[source,csharp]
+----
+new RankFeatureQuery
+{
+    Name = "named_query",
+    Boost = 1.1,
+    Field = Infer.Field<Project>(f => f.Rank),
+    Function = new RankFeatureLinearFunction()
+}
+----
+
+[source,javascript]
+.Example json output
+----
+{
+  "rank_feature": {
+    "_name": "named_query",
+    "boost": 1.1,
+    "field": "rank",
+    "linear": {}
+  }
+}
+----
+

src/Nest/QueryDsl/Specialized/RankFeature/RankFeatureQuery.cs

@@ -54,6 +54,13 @@ public RankFeatureQueryDescriptor<T> Logarithm(Func<RankFeatureLogarithmFunction
 		/// <inheritdoc cref="IRankFeatureSigmoidFunction"/>
 		public RankFeatureQueryDescriptor<T> Sigmoid(Func<RankFeatureSigmoidFunctionDescriptor, IRankFeatureSigmoidFunction> selector) =>
 			Assign(selector, (a, v) => a.Function = v?.Invoke(new RankFeatureSigmoidFunctionDescriptor()));
+
+		/// <inheritdoc cref="IRankFeatureLinearFunction"/>
+		public RankFeatureQueryDescriptor<T> Linear()
+		{
+			Self.Function = new RankFeatureLinearFunction();
+			return this;
+		}
 	}
 
 	/// <summary>
@@ -162,6 +169,24 @@ public class RankFeatureSigmoidFunctionDescriptor
 		public RankFeatureSigmoidFunctionDescriptor Pivot(float pivot) => Assign(pivot, (a, v) => a.Pivot = v);
 	}
 
+	/// <summary>
+	/// Gives a score equal to the indexed value of S, where S is the value of the rank feature field.
+	///
+	/// If a rank feature field is indexed with "positive_score_impact": true, its indexed value is equal to S and rounded to preserve
+	/// only 9 significant bits for the precision.
+	/// 
+	/// If a rank feature field is indexed with "positive_score_impact": false, its indexed value is equal to 1/S and rounded to
+	/// preserve only 9 significant bits for the precision.
+	/// </summary>
+	public interface IRankFeatureLinearFunction : IRankFeatureFunction
+	{
+	}
+
+	/// <inheritdoc cref="IRankFeatureLinearFunction" />
+	public class RankFeatureLinearFunction : IRankFeatureLinearFunction
+	{
+	}
+
 	internal class RankFeatureQueryFormatter : IJsonFormatter<IRankFeatureQuery>
 	{
 		public void Serialize(ref JsonWriter writer, IRankFeatureQuery value, IJsonFormatterResolver formatterResolver)
@@ -206,6 +231,9 @@ public void Serialize(ref JsonWriter writer, IRankFeatureQuery value, IJsonForma
 					case IRankFeatureLogarithmFunction log:
 						SerializeScoreFunction(ref writer, "log", log, formatterResolver);
 						break;
+					case IRankFeatureLinearFunction log:
+						SerializeScoreFunction(ref writer, "linear", log, formatterResolver);
+						break;
 				}
 			}
 
@@ -232,7 +260,8 @@ private static IRankFeatureFunction DeserializeScoreFunction<TScoreFunction>(ref
 			{ "field", 2 },
 			{ "saturation", 3 },
 			{ "log", 4 },
-			{ "sigmoid", 5 }
+			{ "sigmoid", 5 },
+			{ "linear", 6 }
 		};
 
 		public IRankFeatureQuery Deserialize(ref JsonReader reader, IJsonFormatterResolver formatterResolver)
@@ -266,6 +295,9 @@ public IRankFeatureQuery Deserialize(ref JsonReader reader, IJsonFormatterResolv
 						case 5:
 							query.Function = DeserializeScoreFunction<RankFeatureSigmoidFunction>(ref reader, formatterResolver);
 							break;
+						case 6:
+							query.Function = DeserializeScoreFunction<RankFeatureLinearFunction>(ref reader, formatterResolver);
+							break;
 					}
 				}
 				else

tests/Tests/QueryDsl/Specialized/RankFeature/RankFeatureQueryUsageTests.cs

@@ -2,6 +2,7 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using Elastic.Elasticsearch.Xunit.XunitPlumbing;
 using Nest;
 using Tests.Core.ManagedElasticsearch.Clusters;
 using Tests.Domain;
@@ -71,4 +72,27 @@ protected override QueryContainer QueryFluent(QueryContainerDescriptor<Project>
 				.Field(f => f.Rank)
 			);
 	}
+
+	[SkipVersion("<7.12.0", "Introduced in 7.12.0")]
+	public class RankFeatureLinearFunctionUsageTests : QueryDslUsageTestsBase
+	{
+		public RankFeatureLinearFunctionUsageTests(ReadOnlyCluster i, EndpointUsage usage) : base(i, usage) { }
+		protected override QueryContainer QueryInitializer => new RankFeatureQuery
+		{
+			Name = "named_query",
+			Boost = 1.1,
+			Field = Infer.Field<Project>(f => f.Rank),
+			Function = new RankFeatureLinearFunction()
+		};
+
+		protected override object QueryJson =>
+			new { rank_feature = new { _name = "named_query", boost = 1.1, field = "rank", linear = new { } } };
+
+		protected override QueryContainer QueryFluent(QueryContainerDescriptor<Project> q) => q
+			.RankFeature(rf => rf
+				.Name("named_query")
+				.Boost(1.1)
+				.Field(f => f.Rank)
+				.Linear());
+	}
 }