Merge #666

666: Add support for sort in documents api r=curquiza a=kashifsoofi

# Pull Request

## Related issue
Fixes #665

## What does this PR do?
- Add Sort to DocumentsQuery

## PR checklist
Please check if your PR fulfills the following requirements:
- [x] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [x] Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!


<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## Summary by CodeRabbit

* **New Features**
  * Added support for sorting document query results, including multi-field ordering and ID-based sorts; works with filters and limits.

* **Documentation**
  * Added "Search with sort" guidance and a C# example showing how to specify sort options.

* **Tests**
  * Added tests validating ascending/descending, multi-field sort with filters, and that sort parameters appear in query strings.

* **Chores**
  * Bumped Meilisearch version used in CI from v1.10.0 to v1.16.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Kashif Soofi <kashif.soofi+git@gmail.com>

Author: meili-bors[bot]

.env

@@ -1,3 +1,3 @@
-MEILISEARCH_VERSION=v1.10.0
+MEILISEARCH_VERSION=v1.16
 PROXIED_MEILISEARCH=http://nginx/api/
 MEILISEARCH_URL=http://meilisearch:7700

README.md

@@ -260,6 +260,17 @@ if (results is PaginatedSearchResult<T> paginatedResults)
 }
 ```
 
+#### Search with sort
+
+To get results sorted by attributes and preferred sorting order, the [Sort](https://www.meilisearch.com/docs/reference/api/search#sort) property must be defined.
+
+```c#
+var results = await index.SearchAsync<T>(query, new SearchQuery()
+{
+    Sort = new List<string> { "genre:asc", "name:desc" }
+});
+```
+
 ## 🤖 Compatibility with Meilisearch
 
 This package guarantees compatibility with [version v1.x of Meilisearch](https://github.com/meilisearch/meilisearch/releases/latest), but some features may not be present. Please check the [issues](https://github.com/meilisearch/meilisearch-dotnet/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+label%3Aenhancement) for more info.

src/Meilisearch/QueryParameters/DocumentsQuery.cs

@@ -31,5 +31,11 @@ public class DocumentsQuery
         /// </summary>
         [JsonPropertyName("filter")]
         public object Filter { get; set; }
+
+        /// <summary>
+        /// An optional sort to apply
+        /// </summary>
+        [JsonPropertyName("sort")]
+        public List<string> Sort { get; set; }
     }
 }

tests/Meilisearch.Tests/DocumentTests.cs

@@ -643,6 +643,64 @@ await index.GetDocumentsAsync<Movie>(new DocumentsQuery()
             documents.Results.Last().Id.Should().Be("11");
         }
 
+        [Theory]
+        [InlineData("id:asc", true)]
+        [InlineData("id:desc", false)]
+        public async Task GetMultipleExistingDocumentsWithIdSort(string sort, bool ascending)
+        {
+            var index = await _fixture.SetUpBasicIndexWithIntId($"GetMultipleExistingDocumentsWithIdSort_{(ascending ? "Asc" : "Desc")}Test");
+            var updateSortable = await index.UpdateSortableAttributesAsync(new[] { "id" });
+            updateSortable.TaskUid.Should().BeGreaterOrEqualTo(0);
+            await index.WaitForTaskAsync(updateSortable.TaskUid);
+
+            var results = (await index.GetDocumentsAsync<MovieWithIntId>(
+                new DocumentsQuery { Sort = new List<string> { sort } }
+            )).Results.ToList();
+
+            Assert.Equal(7, results.Count);
+            if (ascending)
+                results.Should().BeInAscendingOrder(x => x.Id);
+            else
+                results.Should().BeInDescendingOrder(x => x.Id);
+        }
+
+        [Fact]
+        public async Task GetMultipleExistingDocumentsWithMultiSort()
+        {
+            var index = await _fixture.SetUpBasicIndexWithIntId("GetMultipleExistingDocumentsWithMultiSort");
+            var updateFilterable = await index.UpdateFilterableAttributesAsync(new[] { "genre" });
+            updateFilterable.TaskUid.Should().BeGreaterOrEqualTo(0);
+            await index.WaitForTaskAsync(updateFilterable.TaskUid);
+
+            var updateSortable = await index.UpdateSortableAttributesAsync(new[] { "genre", "name" });
+            updateSortable.TaskUid.Should().BeGreaterOrEqualTo(0);
+            await index.WaitForTaskAsync(updateSortable.TaskUid);
+
+            var results = (await index.GetDocumentsAsync<MovieWithIntId>(
+                new DocumentsQuery
+                {
+                    Filter = "genre IN ['SF','Action']",
+                    Sort = new List<string> { "genre:asc", "name:desc" }
+                }
+            )).Results.ToList();
+
+            Assert.Equal(4, results.Count);
+            var first = results.First();
+            first.Genre.Should().Be("Action");
+            first.Name.Should().Be("Spider-Man");
+            var last = results.Last();
+            last.Genre.Should().Be("SF");
+            last.Name.Should().Be("Harry Potter");
+
+            results.Should().BeInAscendingOrder(x => x.Genre);
+            var split = results.FindIndex(x => x.Genre == "SF");
+            split.Should().BeGreaterThan(0); // at least one Action before SF
+            results.Take(split).Should().OnlyContain(x => x.Genre == "Action");
+            results.Skip(split).Should().OnlyContain(x => x.Genre == "SF");
+            results.Take(split).Should().BeInDescendingOrder(x => x.Name);
+            results.Skip(split).Should().BeInDescendingOrder(x => x.Name);
+        }
+
         [Fact]
         public async Task DeleteOneExistingDocumentWithStringId()
         {

tests/Meilisearch.Tests/ObjectExtensionsTests.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Linq;
 
 using Meilisearch.Extensions;
 using Meilisearch.QueryParameters;
@@ -157,5 +158,19 @@ public void QueryStringsWithListAreEqualsForDocumentsQuery(int? offset, int? lim
                 Assert.Contains(String.Join(",", dq.Fields), actualQuery);
             }
         }
+
+        [Theory]
+        [InlineData(null, new string[] { "id:asc", "title:desc" })]
+        public void QueryStringsWithSortAreEqualForDocumentsQuery(int? limit, string[] sort)
+        {
+            var uri = "indexes/myindex/documents";
+            var dq = new DocumentsQuery { Limit = limit, Sort = sort.ToList() };
+            var actualQuery = dq.ToQueryString(uri: uri);
+
+            Assert.NotEmpty(actualQuery);
+            Assert.NotNull(actualQuery);
+            Assert.Contains("sort", actualQuery);
+            Assert.Contains(String.Join(",", dq.Sort), actualQuery);
+        }
     }
 }