[Backport master] Add support for _shard_doc sort with pit (#5393)

* Add support for _shard_doc sort with pit (#5374)

* Add support for _shard_doc sort with pit

* Update test

* Fixup namespaces

Co-authored-by: Steve Gordon <sgordon@hotmail.co.uk>

Author: github-actions[bot]

src/Nest/Search/Search/Sort/FieldSort.cs

@@ -23,7 +23,14 @@ public interface IFieldSort : ISort
 
 	public class FieldSort : SortBase, IFieldSort
 	{
+		private const string ShardDoc = "_shard_doc";
+		
 		public static readonly IList<ISort> ByDocumentOrder = new ReadOnlyCollection<ISort>(new List<ISort> { new FieldSort { Field = "_doc" } });
+		public static readonly IList<ISort> ByShardDocumentOrder = new ReadOnlyCollection<ISort>(new List<ISort> { new FieldSort { Field = ShardDoc } });
+
+		public static readonly FieldSort ShardDocumentOrderAscending = new() { Field = ShardDoc, Order = SortOrder.Ascending };
+		public static readonly FieldSort ShardDocumentOrderDescending = new() { Field = ShardDoc, Order = SortOrder.Descending };
+
 		public Field Field { get; set; }
 		public bool? IgnoreUnmappedFields { get; set; }
 		public FieldType? UnmappedType { get; set; }

src/Nest/Search/Search/Sort/SortSpecialField.cs

@@ -15,6 +15,9 @@ public enum SortSpecialField
 		Score,
 
 		[EnumMember(Value = "_doc")]
-		DocumentIndexOrder
+		DocumentIndexOrder,
+
+		[EnumMember(Value = "_shard_doc")]
+		ShardDocumentOrder
 	}
 }

tests/Tests/Search/PointInTime/PointInTimeApiTests.cs

@@ -2,7 +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 System;
+using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
 using Elastic.Elasticsearch.Xunit.XunitPlumbing;
@@ -21,6 +21,7 @@ public class PointInTimeApiTests : CoordinatedIntegrationTestBase<ReadOnlyCluste
 	{
 		private const string OpenPointInTimeStep = nameof(OpenPointInTimeStep);
 		private const string SearchPointInTimeStep = nameof(SearchPointInTimeStep);
+		private const string SearchPointInTimeWithSortStep = nameof(SearchPointInTimeWithSortStep);
 		private const string ClosePointInTimeStep = nameof(ClosePointInTimeStep);
 
 		public PointInTimeApiTests(ReadOnlyCluster cluster, EndpointUsage usage) : base(new CoordinatedUsage(cluster, usage)
@@ -60,6 +61,31 @@ public PointInTimeApiTests(ReadOnlyCluster cluster, EndpointUsage usage) : base(
 						uniqueValueSelector: values => values.ExtendedValue<string>("pitId")
 					)
 			},
+			{
+				SearchPointInTimeWithSortStep, ">=7.12.0", u =>
+					u.Calls<SearchDescriptor<Project>, SearchRequest<Project>, ISearchRequest<Project>, ISearchResponse<Project>>(
+						v => new SearchRequest<Project>
+						{
+							Size = 1,
+							Query = new QueryContainer(new MatchAllQuery()),
+							PointInTime = new Nest.PointInTime(v, "1m"),
+							Sort =new List<ISort>
+							{
+								FieldSort.ShardDocumentOrderDescending
+							}
+						},
+						(v, d) => d
+							.Size(1)
+							.Query(q => q.MatchAll())
+							.PointInTime(v, p => p.KeepAlive("1m"))
+							.Sort(s => s.Descending(SortSpecialField.ShardDocumentOrder)),
+						(v, c, f) => c.Search(f),
+						(v, c, f) => c.SearchAsync(f),
+						(v, c, r) => c.Search<Project>(r),
+						(v, c, r) => c.SearchAsync<Project>(r),
+						uniqueValueSelector: values => values.ExtendedValue<string>("pitId")
+					)
+			},
 			{
 				ClosePointInTimeStep, u =>
 					u.Calls<ClosePointInTimeDescriptor, ClosePointInTimeRequest, IClosePointInTimeRequest, ClosePointInTimeResponse>(
@@ -74,13 +100,13 @@ public PointInTimeApiTests(ReadOnlyCluster cluster, EndpointUsage usage) : base(
 			}
 		}) { }
 
-		[I] public async Task OpenPointInTimeResponse() => await Assert<OpenPointInTimeResponse>(OpenPointInTimeStep, (v, r) =>
+		[I] public async Task OpenPointInTimeResponse() => await Assert<OpenPointInTimeResponse>(OpenPointInTimeStep, r =>
 		{
 			r.ShouldBeValid();
 			r.Id.Should().NotBeNullOrEmpty();
 		});
 
-		[I] public async Task SearchPointInTimeResponse() => await Assert<SearchResponse<Project>>(SearchPointInTimeStep, (v, r) =>
+		[I] public async Task SearchPointInTimeResponse() => await Assert<SearchResponse<Project>>(SearchPointInTimeStep, r =>
 		{
 			r.ShouldBeValid();
 			r.PointInTimeId.Should().NotBeNullOrEmpty();
@@ -93,7 +119,15 @@ [I] public async Task SearchPointInTimeResponse() => await Assert<SearchResponse
 			r.Took.Should().BeGreaterOrEqualTo(0);
 		});
 
-		[I] public async Task ClosePointInTimeResponse() => await Assert<ClosePointInTimeResponse>(ClosePointInTimeStep, (v, r) =>
+		[I] public async Task SearchPointInTimeWithSortResponse() => await Assert<SearchResponse<Project>>(SearchPointInTimeWithSortStep, r =>
+		{
+			r.ShouldBeValid();
+			r.PointInTimeId.Should().NotBeNullOrEmpty();
+			r.Total.Should().BeGreaterThan(0);
+			r.Hits.Count.Should().BeGreaterThan(0);
+		});
+
+		[I] public async Task ClosePointInTimeResponse() => await Assert<ClosePointInTimeResponse>(ClosePointInTimeStep, r =>
 		{
 			r.ShouldBeValid();
 			r.Succeeded.Should().BeTrue();

tests/Tests/Search/Request/SortUsageTests.cs

@@ -6,9 +6,12 @@
 using System.Collections.Generic;
 using System.Linq;
 using Elastic.Elasticsearch.Xunit.XunitPlumbing;
+using Elastic.Transport;
+using Elasticsearch.Net;
 using Nest;
 using Tests.Core.ManagedElasticsearch.Clusters;
 using Tests.Domain;
+using Tests.Framework.EndpointTests;
 using Tests.Framework.EndpointTests.TestState;
 using static Nest.Infer;
 
@@ -400,4 +403,56 @@ public NumericTypeUsageTests(ReadOnlyCluster cluster, EndpointUsage usage) : bas
 				}
 			};
 	}
+
+	//hide
+	[SkipVersion("<7.12.0", "_shard_doc added in 7.12.0")]
+	public class ShardDocUsageTests : ApiIntegrationTestBase<ReadOnlyCluster, ISearchResponse<Project>, ISearchRequest, SearchDescriptor<Project>, SearchRequest<Project>>
+	{
+		public ShardDocUsageTests(ReadOnlyCluster cluster, EndpointUsage usage) : base(cluster, usage) { }
+
+		private string _pit = string.Empty;
+		
+		protected override void IntegrationSetup(IElasticClient client, CallUniqueValues values)
+		{
+			var response = client.OpenPointInTime(Nest.Indices.Index<Project>(), f => f.KeepAlive("1m"));
+			_pit = response.Id;
+		}
+
+		protected override object ExpectJson =>
+			new
+			{
+				pit = new
+				{
+					id = ""
+				},
+				sort = new object[]
+				{
+					new { _shard_doc = new { order = "asc" } }
+				}
+			};
+
+		protected override HttpMethod HttpMethod => HttpMethod.POST;
+		protected override string UrlPath => "/project/_search";
+		protected override Func<SearchDescriptor<Project>, ISearchRequest> Fluent => s => s
+			.PointInTime(_pit)
+			.Sort(ss => ss.Ascending(SortSpecialField.ShardDocumentOrder));
+
+		protected override bool ExpectIsValid => true;
+		protected override int ExpectStatusCode => 200;
+
+		protected override SearchRequest<Project> Initializer => new()
+			{
+				PointInTime = new Nest.PointInTime(_pit),
+				Sort = new List<ISort>
+				{
+					FieldSort.ShardDocumentOrderAscending
+				}
+		};
+
+		protected override LazyResponses ClientUsage() => Calls(
+			(client, f) => client.Search(f),
+			(client, f) => client.SearchAsync(f),
+			(client, r) => client.Search<Project>(r),
+			(client, r) => client.SearchAsync<Project>(r));
+	}
 }