Add Params to PhraseSuggestCollate

PhraseSuggestCollate Query takes an ITemplateQuery that allows the specification of parameters. The API of phrase suggester however specifies the parameters for the query at the same level as the query, not nested within the query object. This commit adds a Parameters dictionary to IPhraseSuggestCollate so that parameters are serialized to the correct query form. If parameters are specified on the ITemplateQuery, these are assigned to the parameters on IPhraseSuggestCollate.

Add XML documentation to indicate the usage of each property.

Closes #2849

Author: russcam

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

@@ -4,34 +4,99 @@
 
 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
 	{
-		[JsonProperty(PropertyName = "query")]
+		/// <summary>
+		/// The collate query to run.
+		/// </summary>
+		/// <remarks>
+		/// Query parameters should be specified using <see cref="Params"/>
+		/// </remarks>
+		[JsonProperty("query")]
 		ITemplateQuery Query { get; set; }
 
-		[JsonProperty(PropertyName = "prune")]
+		/// <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; }
+		private ITemplateQuery _query;
+
+		/// <inheritdoc />
+		public ITemplateQuery Query
+		{
+			get => _query;
+			set
+			{
+				_query = value;
+				if (_query != null) Params = _query.Params;
+			}
+		}
 
+		/// <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; }
-
+		IDictionary<string, object> IPhraseSuggestCollate.Params { get; set; }
 		bool? IPhraseSuggestCollate.Prune { get; set; }
 
+		/// <summary>
+		/// The collate query to run.
+		/// </summary>
+		/// <remarks>
+		/// Query parameters should be specified using <see cref="Params(IDictionary&lt;string, object&gt;)"/> or
+		/// Params(Func&lt;FluentDictionary&lt;string, object&gt;, FluentDictionary&lt;string, object&gt;&gt;)
+		/// </remarks>
 		public PhraseSuggestCollateDescriptor<T> Query(Func<TemplateQueryDescriptor<T>, ITemplateQuery> selector) =>
-			Assign(a => a.Query = selector?.Invoke(new TemplateQueryDescriptor<T>()));
+			Assign(a =>
+			{
+				var templateQuery = selector?.Invoke(new TemplateQueryDescriptor<T>());
+				a.Query = templateQuery;
+				if (templateQuery != null) Self.Params = templateQuery.Params;
+			});
 
+		/// <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/Tests/Search/Suggesters/SuggestApiTests.cs

@@ -80,9 +80,9 @@ protected override LazyResponses ClientUsage() => Calls(
 				.Confidence(1)
 				.Collate(c => c
 					.Query(q => q
-						.Inline("{ \"match_all\": { }}")
-						.Params(p => p.Add("field_name", _phraseSuggestField))
+						.Inline("{ \"match\": { \"{{field_name}}\" : \"{{suggestion}}\" }}")
 					)
+					.Params(p => p.Add("field_name", _phraseSuggestField))
 					.Prune()
 				)
 				.DirectGenerator(d => d
@@ -170,11 +170,11 @@ protected override LazyResponses ClientUsage() => Calls(
 								{
 									Query = new TemplateQuery
 									{
-										Inline = "{ \"match_all\": { }}",
-										Params = new Dictionary<string, object>
-										{
-											{"field_name", _phraseSuggestField}
-										}
+										Inline = "{ \"match\": { \"{{field_name}}\" : \"{{suggestion}}\" }}",
+									},
+									Params = new Dictionary<string, object>
+									{
+										{"field_name", _phraseSuggestField}
 									},
 									Prune = true
 								},
@@ -322,11 +322,11 @@ private static void AssertCompletionSuggestResponse(ISuggestResponse<Project> re
 						{
 							query = new
 							{
-								inline = "{ \"match_all\": { }}",
-								@params = new
-								{
-									field_name = _phraseSuggestField
-								}
+								inline = "{ \"match\": { \"{{field_name}}\" : \"{{suggestion}}\" }}",
+							},
+							@params = new
+							{
+								field_name = _phraseSuggestField
 							},
 							prune = true,
 						},