Add Params to PhraseSuggestCollate

This commit adds a Parameters dictionary to IPhraseSuggestCollate so that parameters are serialized to the correct query form and introduces a PhraseSuggestCollateQuery to specify the query.

Add XML documentation to indicate the usage of each property.

Closes #2849

(cherry-picked from commit f905270)

Author: russcam

docs/search/request/suggest-usage.asciidoc

@@ -62,8 +62,8 @@ s => s
         .Collate(c => c
             .Query(q => q
                 .Source("{ \"match\": { \"{{field_name}}\": \"{{suggestion}}\" }}")
-                .Params(p => p.Add("field_name", "title"))
             )
+            .Params(p => p.Add("field_name", "title"))
             .Prune()
         )
         .Confidence(10.1)
@@ -134,13 +134,13 @@ new SearchRequest<Project>
             {
                 Collate = new PhraseSuggestCollate
                 {
-                    Query = new TemplateQuery
+                    Query = new PhraseSuggestCollateQuery
                     {
                         Source = "{ \"match\": { \"{{field_name}}\": \"{{suggestion}}\" }}",
-                        Params = new Dictionary<string, object>
-                        {
-                            { "field_name", "title" }
-                        }
+                    },
+                    Params = new Dictionary<string, object>
+                    {
+                        { "field_name", "title" }
                     },
                     Prune = true
                 },
@@ -189,10 +189,10 @@ new SearchRequest<Project>
       "phrase": {
         "collate": {
           "query": {
-            "source": "{ \"match\": { \"{{field_name}}\": \"{{suggestion}}\" }}",
-            "params": {
-              "field_name": "title"
-            }
+            "source": "{ \"match\": { \"{{field_name}}\": \"{{suggestion}}\" }}"
+          },
+          "params": {
+            "field_name": "title"
           },
           "prune": true
         },

src/Nest/Search/Suggesters/PhraseSuggester/PhraseSuggestCollate.cs

@@ -4,34 +4,77 @@
 
 namespace Nest
 {
+	/// <summary>
+	/// Checks each suggestion against the specified query to prune suggestions
+	/// for which no matching docs exist in the index.
+	/// </summary>
 	[JsonObject(MemberSerialization = MemberSerialization.OptIn)]
 	[JsonConverter(typeof(ReadAsTypeJsonConverter<PhraseSuggestCollate>))]
 	public interface IPhraseSuggestCollate
 	{
+		/// <summary>
+		/// The collate query to run.
+		/// </summary>
 		[JsonProperty("query")]
-		ITemplateQuery Query { get; set; }
+		IPhraseSuggestCollateQuery Query { get; set; }
 
+		/// <summary>
+		/// Controls if all phrase suggestions will be returned. When set to <c>true</c>, the suggestions will have
+		/// an additional option collate_match, which will be <c>true</c> if matching documents for the phrase was found,
+		/// <c>false</c> otherwise. The default value for <see cref="Prune"/> is <c>false</c>.
+		/// </summary>
 		[JsonProperty("prune")]
 		bool? Prune { get; set; }
+
+		/// <summary>
+		/// The parameters for the query. the suggestion value will be added to the variables you specify.
+		/// </summary>
+		[JsonProperty("params")]
+		IDictionary<string, object> Params { get; set; }
 	}
 
+	/// <inheritdoc />
 	public class PhraseSuggestCollate : IPhraseSuggestCollate
 	{
-		public ITemplateQuery Query { get; set; }
+		/// <inheritdoc />
+		public IPhraseSuggestCollateQuery Query { get; set; }
 
+		/// <inheritdoc />
 		public bool? Prune { get; set; }
+
+		/// <inheritdoc />
+		public IDictionary<string, object> Params { get; set; }
 	}
 
 	public class PhraseSuggestCollateDescriptor<T> : DescriptorBase<PhraseSuggestCollateDescriptor<T>, IPhraseSuggestCollate>, IPhraseSuggestCollate
 		where T : class
 	{
-		ITemplateQuery IPhraseSuggestCollate.Query { get; set; }
-
+		IPhraseSuggestCollateQuery IPhraseSuggestCollate.Query { get; set; }
+		IDictionary<string, object> IPhraseSuggestCollate.Params { get; set; }
 		bool? IPhraseSuggestCollate.Prune { get; set; }
 
-		public PhraseSuggestCollateDescriptor<T> Query(Func<TemplateQueryDescriptor<T>, ITemplateQuery> selector) =>
-			Assign(a => a.Query = selector?.Invoke(new TemplateQueryDescriptor<T>()));
+		/// <summary>
+		/// The collate query to run
+		/// </summary>
+		public PhraseSuggestCollateDescriptor<T> Query(Func<PhraseSuggestCollateQueryDescriptor, IPhraseSuggestCollateQuery> selector) =>
+			Assign(a => a.Query = selector?.Invoke(new PhraseSuggestCollateQueryDescriptor()));
 
+		/// <summary>
+		/// Controls if all phrase suggestions will be returned. When set to <c>true</c>, the suggestions will have
+		/// an additional option collate_match, which will be <c>true</c> if matching documents for the phrase was found,
+		/// <c>false</c> otherwise. The default value for <see cref="Prune"/> is <c>false</c>.
+		/// </summary>
 		public PhraseSuggestCollateDescriptor<T> Prune(bool? prune = true) => Assign(a => a.Prune = prune);
+
+		/// <summary>
+		/// The parameters for the query. the suggestion value will be added to the variables you specify.
+		/// </summary>
+		public PhraseSuggestCollateDescriptor<T> Params(IDictionary<string, object> paramsDictionary) => Assign(a => a.Params = paramsDictionary);
+
+		/// <summary>
+		/// The parameters for the query. the suggestion value will be added to the variables you specify.
+		/// </summary>
+		public PhraseSuggestCollateDescriptor<T> Params(Func<FluentDictionary<string, object>, FluentDictionary<string, object>> paramsDictionary) =>
+			Assign(a => a.Params = paramsDictionary(new FluentDictionary<string, object>()));
 	}
 }

src/Nest/Search/Suggesters/PhraseSuggester/PhraseSuggestCollateQuery.cs

@@ -0,0 +1,48 @@
+using Newtonsoft.Json;
+
+namespace Nest
+{
+	/// <summary>
+	/// A query to run for a phrase suggester collate
+	/// </summary>
+	[JsonObject(MemberSerialization = MemberSerialization.OptIn)]
+	[JsonConverter(typeof(ReadAsTypeJsonConverter<PhraseSuggestCollateQuery>))]
+	public interface IPhraseSuggestCollateQuery
+	{
+		/// <summary>
+		/// The source script to be executed
+		/// </summary>
+		[JsonProperty("source")]
+		string Source { get; set; }
+
+		/// <summary>
+		/// The id for a stored script to execute
+		/// </summary>
+		[JsonProperty("id")]
+		Id Id { get; set; }
+	}
+
+	/// <inheritdoc />
+	public class PhraseSuggestCollateQuery : IPhraseSuggestCollateQuery
+	{
+		/// <inheritdoc />
+		public string Source { get; set; }
+
+		/// <inheritdoc />
+		public Id Id { get; set; }
+	}
+
+	/// <inheritdoc />
+	public class PhraseSuggestCollateQueryDescriptor :
+		DescriptorBase<PhraseSuggestCollateQueryDescriptor, IPhraseSuggestCollateQuery>, IPhraseSuggestCollateQuery
+	{
+		string IPhraseSuggestCollateQuery.Source { get; set; }
+		Id IPhraseSuggestCollateQuery.Id { get; set; }
+
+		/// <inheritdoc />
+		public PhraseSuggestCollateQueryDescriptor Source(string source) => Assign(a => a.Source = source);
+
+		/// <inheritdoc />
+		public PhraseSuggestCollateQueryDescriptor Id(Id id) => Assign(a => a.Id = id);
+	}
+}

src/Tests/Search/Request/SuggestUsageTests.cs

@@ -50,9 +50,9 @@ public SuggestUsageTests(ReadOnlyCluster cluster, EndpointUsage usage) : base(cl
 						collate = new {
 						  query = new {
 							source = "{ \"match\": { \"{{field_name}}\": \"{{suggestion}}\" }}",
-							@params = new {
-						      field_name = "title"
-							}
+						  },
+						  @params = new {
+					        field_name = "title"
 						  },
 						  prune = true,
 						},
@@ -81,7 +81,8 @@ public SuggestUsageTests(ReadOnlyCluster cluster, EndpointUsage usage) : base(cl
 						suggest_mode = "always"
 					  },
 					  text = "hello world"
-					} }
+					  }
+					}
 				  }
 			};
 
@@ -123,8 +124,8 @@ public SuggestUsageTests(ReadOnlyCluster cluster, EndpointUsage usage) : base(cl
 					.Collate(c => c
 						.Query(q => q
 							.Source("{ \"match\": { \"{{field_name}}\": \"{{suggestion}}\" }}")
-							.Params(p => p.Add("field_name", "title"))
 						)
+						.Params(p => p.Add("field_name", "title"))
 						.Prune()
 					)
 					.Confidence(10.1)
@@ -190,13 +191,13 @@ public SuggestUsageTests(ReadOnlyCluster cluster, EndpointUsage usage) : base(cl
 						{
 							Collate = new PhraseSuggestCollate
 							{
-								Query = new TemplateQuery
+								Query = new PhraseSuggestCollateQuery
 								{
 									Source = "{ \"match\": { \"{{field_name}}\": \"{{suggestion}}\" }}",
-									Params = new Dictionary<string, object>
-									{
-										{ "field_name", "title" }
-									}
+								},
+								Params = new Dictionary<string, object>
+								{
+									{ "field_name", "title" }
 								},
 								Prune = true
 							},