Include cluster statistics on search response (#3601)

* Include cluster statistics on search response

This commit includes cluster statistics returned on a search response
under the key _clusters when a cross cluster search is performed.

Closes #3512

Author: russcam

src/Nest/CommonOptions/Hit/ShardStatistics.cs

@@ -7,16 +7,29 @@ namespace Nest
 	[JsonObject]
 	public class ShardStatistics
 	{
-		[JsonProperty]
+		[JsonProperty("failed")]
 		public int Failed { get; internal set; }
 
 		[JsonProperty("failures")]
 		public IReadOnlyCollection<ShardFailure> Failures { get; internal set; } = EmptyReadOnly<ShardFailure>.Collection;
 
-		[JsonProperty]
+		[JsonProperty("successful")]
 		public int Successful { get; internal set; }
 
-		[JsonProperty]
+		[JsonProperty("total")]
+		public int Total { get; internal set; }
+	}
+
+	[JsonObject]
+	public class ClusterStatistics
+	{
+		[JsonProperty("skipped")]
+		public int Skipped { get; internal set; }
+
+		[JsonProperty("successful")]
+		public int Successful { get; internal set; }
+
+		[JsonProperty("total")]
 		public int Total { get; internal set; }
 	}
 }

src/Nest/Search/Search/SearchResponse.cs

@@ -5,16 +5,29 @@
 
 namespace Nest
 {
+	/// <summary>
+	/// A response to a search request
+	/// </summary>
+	/// <typeparam name="T">The document type</typeparam>
 	public interface ISearchResponse<T> : IResponse where T : class
 	{
 		/// <summary>
 		/// Gets the collection of aggregations
 		/// </summary>
 		AggregateDictionary Aggregations { get; }
 
+		/// <inheritdoc cref="Aggregations"/>
 		[Obsolete("Aggs has been renamed to Aggregations and will be removed in NEST 7.x")]
 		AggregateDictionary Aggs { get; }
 
+		/// <summary>
+		/// Gets the statistics about the clusters on which the search query was executed.
+		/// </summary>
+		/// <remarks>
+		/// Valid for cross cluster searches and Elasticsearch 6.1.0+
+		/// </remarks>
+		ClusterStatistics Clusters { get; }
+
 		/// <summary>
 		/// Gets the documents inside the hits, by deserializing <see cref="IHitMetadata{T}.Source" /> into T.
 		/// <para>
@@ -70,7 +83,7 @@ public interface ISearchResponse<T> : IResponse where T : class
 		string ScrollId { get; }
 
 		/// <summary>
-		/// Gets the meta data about the shards on which the search query was executed.
+		/// Gets the statistics about the shards on which the search query was executed.
 		/// </summary>
 		ShardStatistics Shards { get; }
 
@@ -100,21 +113,26 @@ public interface ISearchResponse<T> : IResponse where T : class
 		long Total { get; }
 	}
 
+	/// <inheritdoc cref="ISearchResponse{T}"/>
 	[JsonObject]
 	public class SearchResponse<T> : ResponseBase, ISearchResponse<T> where T : class
 	{
 		private IReadOnlyCollection<T> _documents;
-
 		private IReadOnlyCollection<FieldValues> _fields;
-
 		private IReadOnlyCollection<IHit<T>> _hits;
 
+		/// <inheritdoc />
 		[JsonProperty("aggregations")]
 		public AggregateDictionary Aggregations { get; internal set; } = AggregateDictionary.Default;
 
+		/// <inheritdoc />
 		[JsonIgnore]
 		public AggregateDictionary Aggs => Aggregations;
 
+		/// <inheritdoc />
+		[JsonProperty("_clusters")]
+		public ClusterStatistics Clusters { get; internal set; }
+
 		/// <inheritdoc />
 		[JsonIgnore]
 		public IReadOnlyCollection<T> Documents =>
@@ -128,43 +146,52 @@ public class SearchResponse<T> : ResponseBase, ISearchResponse<T> where T : clas
 				.Select(h => h.Fields)
 				.ToList());
 
+		/// <inheritdoc />
 		[JsonIgnore]
 		public IReadOnlyCollection<IHit<T>> Hits =>
 			_hits ?? (_hits = HitsMetadata?.Hits ?? EmptyReadOnly<IHit<T>>.Collection);
 
+		/// <inheritdoc />
 		[JsonProperty("hits")]
 		public HitsMetadata<T> HitsMetadata { get; internal set; }
 
+		/// <inheritdoc />
 		[JsonIgnore]
 		public double MaxScore => HitsMetadata?.MaxScore ?? 0;
 
+		/// <inheritdoc />
 		[JsonProperty("num_reduce_phases")]
 		public long NumberOfReducePhases { get; internal set; }
 
+		/// <inheritdoc />
 		[JsonProperty("profile")]
 		public Profile Profile { get; internal set; }
 
-		/// <summary>
-		/// Only set when search type = scan and scroll specified
-		/// </summary>
+		/// <inheritdoc />
 		[JsonProperty("_scroll_id")]
 		public string ScrollId { get; internal set; }
 
+		/// <inheritdoc />
 		[JsonProperty("_shards")]
 		public ShardStatistics Shards { get; internal set; }
 
+		/// <inheritdoc />
 		[JsonProperty("suggest")]
 		public SuggestDictionary<T> Suggest { get; internal set; } = SuggestDictionary<T>.Default;
 
+		/// <inheritdoc />
 		[JsonProperty("terminated_early")]
 		public bool TerminatedEarly { get; internal set; }
 
+		/// <inheritdoc />
 		[JsonProperty("timed_out")]
 		public bool TimedOut { get; internal set; }
 
+		/// <inheritdoc />
 		[JsonProperty("took")]
 		public long Took { get; internal set; }
 
+		/// <inheritdoc />
 		[JsonIgnore]
 		public long Total => HitsMetadata?.Total ?? 0;
 	}

src/Tests/Tests.Configuration/tests.default.yaml

@@ -0,0 +1,23 @@
+# IMPORTANT! This file is just a template and provides the default settings
+# for the test runner.  Do not edit this file in anyway unless you intend
+# to change the defaults.  To change your settings locally make a copy of
+# this file in this directory and rename it to `tests.yaml` (which isn't
+# tracked by git).
+
+# mode either u (unit test), i (integration test) or m (mixed mode)
+mode: i
+# the elasticsearch version that should be started
+# Can be a snapshot version of sonatype or "latest" to get the latest snapshot of sonatype
+elasticsearch_version: 6.6.2
+# cluster filter allows you to only run the integration tests of a particular cluster (cluster suffix not needed)
+# cluster_filter:
+# whether we want to forcefully reseed on the node, if you are starting the tests with a node already running
+#force_reseed: true
+# do not spawn nodes as part of the test setup if we find a node is already running
+# this is opt in during development in CI we never want to see our tests running against an already running node
+test_against_already_running_elasticsearch: true
+# elasticsearch_out_after_started: true
+
+#random_source_serializer: true
+#random_old_connection: true
+#seed: 69819

src/Tests/Tests.Core/ManagedElasticsearch/Clusters/CrossClusterSearchCluster.cs

@@ -0,0 +1,20 @@
+using Tests.Core.ManagedElasticsearch.NodeSeeders;
+
+namespace Tests.Core.ManagedElasticsearch.Clusters
+{
+	public class CrossClusterSearchCluster : ClientTestClusterBase
+	{
+		protected override void SeedCluster()
+		{
+			new DefaultSeeder(Client).SeedNode();
+
+			// persist settings for cross cluster search, when cluster_two is not available
+			Client.ClusterPutSettings(s => s
+				.Persistent(d => d
+					.Add("cluster.remote.cluster_two.seeds", new [] { "127.0.0.1:9399" })
+					.Add("cluster.remote.cluster_two.skip_unavailable", true)
+				)
+			);
+		}
+	}
+}

src/Tests/Tests/Search/Search/SearchApiTests.cs

@@ -502,4 +502,53 @@ protected override void ExpectResponse(IListTasksResponse response)
 			}
 		}
 	}
+
+	[SkipVersion("<6.1.0", "_clusters on response only available in 6.1.0+")]
+	public class CrossClusterSearchApiTests
+		: ApiIntegrationTestBase<CrossClusterSearchCluster, ISearchResponse<Project>, ISearchRequest, SearchDescriptor<Project>, SearchRequest<Project>>
+	{
+		public CrossClusterSearchApiTests(CrossClusterSearchCluster cluster, EndpointUsage usage) : base(cluster, usage) { }
+
+		protected override bool ExpectIsValid => true;
+
+		protected override object ExpectJson => new
+		{
+			query = new
+			{
+				match_all = new { }
+			}
+		};
+
+		protected override int ExpectStatusCode => 200;
+
+		protected override Func<SearchDescriptor<Project>, ISearchRequest> Fluent => s => s
+			.Index(Nest.Indices.Index<Project>().And("cluster_two:project"))
+			.Query(q => q
+				.MatchAll()
+			);
+
+		protected override HttpMethod HttpMethod => HttpMethod.POST;
+
+		protected override SearchRequest<Project> Initializer => new SearchRequest<Project>(Nest.Indices.Index<Project>().And("cluster_two:project"))
+		{
+			Query = new QueryContainer(new MatchAllQuery())
+		};
+
+		protected override string UrlPath => $"/project%2Ccluster_two%3Aproject/doc/_search";
+
+		protected override LazyResponses ClientUsage() => Calls(
+			(c, f) => c.Search(f),
+			(c, f) => c.SearchAsync(f),
+			(c, r) => c.Search<Project>(r),
+			(c, r) => c.SearchAsync<Project>(r)
+		);
+
+		protected override void ExpectResponse(ISearchResponse<Project> response)
+		{
+			response.Clusters.Should().NotBeNull();
+			response.Clusters.Total.Should().Be(2);
+			response.Clusters.Skipped.Should().Be(1);
+			response.Clusters.Successful.Should().Be(1);
+		}
+	}
 }