Merge branch 'main' into create-snapshot-501

Author: curquiza

.code-samples.meilisearch.yaml

@@ -4,8 +4,13 @@
 # You can read more on https://github.com/meilisearch/documentation/tree/master/.vuepress/code-samples
 ---
 getting_started_faceting: |-
-  var faceting = new Faceting {
-    MaxValuesPerFacet = 2
+  var faceting = new Faceting
+  {
+      MaxValuesPerFacet = 2,
+      SortFacetValuesBy = new Dictionary<string, SortFacetValuesByType>
+      {
+          ["*"] = SortFacetValuesByType.Count
+      }
   };
   await client.Index("movies").UpdateFacetingAsync(faceting);
 getting_started_pagination: |-
@@ -29,15 +34,15 @@ date_guide_filterable_attributes_1: |-
   await client.Index("games").UpdateFilterableAttributesAsync(new string[] { "release_timestamp" });
 date_guide_filter_1: |-
   var filters = new SearchQuery() { Filter = "release_timestamp >= 1514761200 AND release_timestamp < 1672527600" };
-  SearchResult<Game> games = await client.Index("games").SearchAsync<Game>("", filters);
+  var games = await client.Index("games").SearchAsync<Game>("", filters);
 date_guide_sortable_attributes_1: |-
   await client.Index("games").UpdateSortableAttributesAsync(new string[] { "release_timestamp" });
 date_guide_sort_1: |-
   SearchQuery sort = new SearchQuery() { Sort = new string[] { "release_timestamp:desc" }};
   await client.Index("games").SearchAsync<Game>("", sort);
 filtering_guide_nested_1: |-
   var filters = new SearchQuery() { Filter = "rating.users >= 90" };
-  SearchResult<MovieRating> movies = await client.Index("movie_ratings").SearchAsync<MovieRating>("thriller", filters);
+  var movies = await client.Index("movie_ratings").SearchAsync<MovieRating>("thriller", filters);
 sorting_guide_sort_nested_1: |-
   SearchQuery sort = new SearchQuery() { Sort = new string[] { "rating.users:asc" }};
   await client.Index("books").SearchAsync<Book>("science fiction", sort);
@@ -64,9 +69,15 @@ async_guide_canceled_by_1: |-
 swap_indexes_1: |-
   await client.SwapIndexesAsync(new List<IndexSwap> { new IndexSwap("indexA", "indexB"), new IndexSwap("indexX", "indexY") } });
 search_parameter_guide_hitsperpage_1: |-
-  await client.Index("movies").SearchAsync<Movie>("", new SearchQuery { HitsPerPage = 15 });
+  var result = await client.Index("movies").SearchAsync<Movie>("", new SearchQuery { HitsPerPage = 15 });
+  if(result is PaginatedSearchResult<Movie> pagedResults)
+  {
+  }
 search_parameter_guide_page_1: |-
-  await client.Index("movies").SearchAsync<Movie>("", new SearchQuery { Page = 2 });
+  var result = await client.Index("movies").SearchAsync<Movie>("", new SearchQuery { Page = 2 });
+  if(result is PaginatedSearchResult<Movie> pagedResults)
+  {
+  }
 get_one_index_1: |-
   await client.GetIndexAsync("movies");
 list_all_indexes_1: |-
@@ -264,28 +275,34 @@ field_properties_guide_displayed_1: |-
   });
 filtering_guide_1: |-
   SearchQuery filters = new SearchQuery() { Filter = "release_date > \"795484800\"" };
-  SearchResult<Movie> movies = await client.Index("movie_ratings").SearchAsync<Movie>("Avengers", filters);
+  var movies = await client.Index("movie_ratings").SearchAsync<Movie>("Avengers", filters);
 filtering_guide_2: |-
   SearchQuery filters = new SearchQuery() { Filter = "release_date > 795484800 AND (director =
   \"Tim Burton\" OR director = \"Christopher Nolan\")" };
-  SearchResult<Movie> movies = await client.Index("movie_ratings").SearchAsync<Movie>("Batman", filters);
+  var movies = await client.Index("movie_ratings").SearchAsync<Movie>("Batman", filters);
 filtering_guide_3: |-
   SearchQuery filters = new SearchQuery() { Filter = "release_date > 1577884550 AND (NOT director = \"Tim Burton\")" };
-  SearchResult<Movie> movies = await client.Index("movie_ratings").SearchAsync<Movie>("Planet of the Apes", filters);
+  var movies = await client.Index("movie_ratings").SearchAsync<Movie>("Planet of the Apes", filters);
 search_parameter_guide_query_1: |-
   await client.Index("movies").SearchAsync<Movie>("shifu");
 search_parameter_guide_offset_1: |-
   var sq = new SearchQuery
   {
       Offset = 1
   };
-  await client.Index("movies").SearchAsync<Movie>("shifu", sq);
+  var result = await client.Index("movies").SearchAsync<Movie>("shifu", sq);
+  if(result is SearchResult<Movie> pagedResults)
+  {
+  }
 search_parameter_guide_limit_1: |-
   var sq = new SearchQuery
   {
       Limit = 2
   };
-  await client.Index("movies").SearchAsync<Movie>("shifu", sq);
+  var result = await client.Index("movies").SearchAsync<Movie>("shifu", sq);
+  if(result is SearchResult<Movie> pagedResults)
+  {
+  }
 search_parameter_guide_retrieve_1: |-
   var sq = new SearchQuery
   {
@@ -389,7 +406,7 @@ getting_started_search_md: |-
   MeilisearchClient client = new MeilisearchClient("http://localhost:7700", "masterKey");
   var index = client.Index("movies");
 
-  SearchResult<Movie> movies = await index.SearchAsync<Movie>("botman");
+  var movies = await index.SearchAsync<Movie>("botman");
   foreach (var movie in movies.Hits)
   {
       Console.WriteLine(movie.Title);
@@ -543,14 +560,14 @@ geosearch_guide_filter_settings_1: |-
   TaskInfo result = await client.Index("movies").UpdateFilterableAttributesAsync(attributes);
 geosearch_guide_filter_usage_1: |-
   SearchQuery filters = new SearchQuery() { Filter = "_geoRadius(45.472735, 9.184019, 2000)" };
-  SearchResult<Restaurant> restaurants = await client.Index("restaurants").SearchAsync<Restaurant>("", filters);
+  var restaurants = await client.Index("restaurants").SearchAsync<Restaurant>("", filters);
 geosearch_guide_filter_usage_2: |-
   SearchQuery filters = new SearchQuery()
   {
       Filter = new string[] { "_geoRadius(45.472735, 9.184019, 2000) AND type = pizza" }
   };
 
-  SearchResult<Restaurant> restaurants = await client.Index("restaurants").SearchAsync<Restaurant>("restaurants", filters);
+  var restaurants = await client.Index("restaurants").SearchAsync<Restaurant>("restaurants", filters);
 geosearch_guide_sort_settings_1: |-
   List<string> attributes = new() { "_geo" };
   TaskInfo result = await client.Index("restaurants").UpdateSortableAttributesAsync(attributes);
@@ -560,7 +577,7 @@ geosearch_guide_sort_usage_1: |-
       Sort = new string[] { "_geoPoint(48.8561446,2.2978204):asc" }
   };
 
-  SearchResult<Restaurant> restaurants = await client.Index("restaurants").SearchAsync<Restaurant>("", filters);
+  var restaurants = await client.Index("restaurants").SearchAsync<Restaurant>("", filters);
 geosearch_guide_sort_usage_2: |-
   SearchQuery filters = new SearchQuery()
   {
@@ -570,13 +587,13 @@ geosearch_guide_sort_usage_2: |-
       }
   };
 
-  SearchResult<Restaurant> restaurants = await client.Index("restaurants").SearchAsync<Restaurant>("restaurants", filters);
+  var restaurants = await client.Index("restaurants").SearchAsync<Restaurant>("restaurants", filters);
 geosearch_guide_filter_usage_3: |-
   SearchQuery filters = new SearchQuery()
   {
       Filter = "_geoBoundingBox([45.494181, 9.214024], [45.449484, 9.179175])"
   };
-  SearchResult<Restaurant> restaurants = await client.Index("restaurants").SearchAsync<Restaurant>("restaurants", filters);
+  var restaurants = await client.Index("restaurants").SearchAsync<Restaurant>("restaurants", filters);
 primary_field_guide_create_index_primary_key: |-
   TaskInfo task = await client.CreateIndexAsync("books", "reference_number");
 primary_field_guide_update_document_primary_key: |-
@@ -619,7 +636,7 @@ delete_a_key_1: |-
   client.DeleteKeyAsync("6062abda-a5aa-4414-ac91-ecd7944c0f8d")
 security_guide_search_key_1: |-
   MeilisearchClient client = new MeilisearchClient("http://localhost:7700", "apiKey");
-  SearchResult<Patient> searchResult = await client.Index("patient_medical_records").SearchAsync<Patient>();
+  var searchResult = await client.Index("patient_medical_records").SearchAsync<Patient>();
 security_guide_update_key_1: |-
   MeilisearchClient client = new MeilisearchClient("http://localhost:7700", "masterKey");
   await client.UpdateKeyAsync("74c9c733-3368-4738-bbe5-1d18a5fecb37", description: "Default Search API Key");
@@ -654,7 +671,7 @@ tenant_token_guide_generate_sdk_1: |-
   );
 tenant_token_guide_search_sdk_1: |-
   frontEndClient = new MeilisearchClient("http://localhost:7700", token);
-  SearchResult<Patient> searchResult = await frontEndClient.Index("patient_medical_records").SearchAsync<Patient>("blood test");
+  var searchResult = await frontEndClient.Index("patient_medical_records").SearchAsync<Patient>("blood test");
 getting_started_typo_tolerance: |-
   var typoTolerance = new TypoTolerance {
     MinWordSizeTypos = new TypoTolerance.TypoSize {
@@ -716,10 +733,16 @@ reset_pagination_settings_1: |-
 get_faceting_settings_1: |-
   await client.Index("movies").GetFacetingAsync();
 update_faceting_settings_1: |-
-  var faceting = new Faceting {
-    MaxValuesPerFacet = 2
+  var faceting = new Faceting
+  {
+      MaxValuesPerFacet = 2,
+      SortFacetValuesBy = new Dictionary<string, SortFacetValuesByType>
+      {
+          ["*"] = SortFacetValuesByType.Alpha,
+          ["genres"] = SortFacetValuesByType.Count
+      }
   };
-  await client.Index("movies").UpdateFacetingAsync(faceting);
+  await client.Index("books").UpdateFacetingAsync(faceting);
 reset_faceting_settings_1: |-
   await client.Index("movies").ResetFacetingAsync();
 multi_search_1: |-
@@ -782,12 +805,6 @@ distinct_attribute_guide_distinct_parameter_1: |-
     Distinct = "sku"
   };
   await client.Index("products").SearchAsync<Product>("white shirt", params);
-search_parameter_reference_ranking_score_threshold_1: |-
-  var params = new SearchQuery()
-  {
-    RankingScoreThreshold = 0.2M
-  };
-  await client.Index("INDEX_NAME").SearchAsync<T>("badman", params);
 get_dictionary_1: |-
   var indexDictionary = await client.Index("books").GetDictionaryAsync();
 update_dictionary_1: |-
@@ -797,6 +814,15 @@ reset_dictionary_1: |-
   await client.Index("books").ResetDictionaryAsync();
 create_snapshot_1: |-
   await client.CreateSnapshotAsync();
+facet_search_2: |-
+  var newFaceting = new Faceting
+  {
+      SortFacetValuesBy = new Dictionary<string, SortFacetValuesByType>
+      {
+          ["genres"] = SortFacetValuesByType.Count
+      }
+  };
+  await client.Index("books").UpdateFacetingAsync(newFaceting);
 facet_search_1: |-
   var query = new SearchFacetsQuery()
   {

README.md

@@ -146,7 +146,7 @@ JSON Output:
 All the supported options are described in the [search parameters](https://www.meilisearch.com/docs/reference/api/search#search-parameters) section of the documentation.
 
 ```c#
-SearchResult<Movie> movies = await index.SearchAsync<Movie>(
+var movies = await index.SearchAsync<Movie>(
     "car",
     new SearchQuery
     {
@@ -197,7 +197,7 @@ Note that MeiliSearch will rebuild your index whenever you update `FilterableAtt
 Then, you can perform the search:
 
 ```c#
-SearchResult<Movie> movies = await index.SearchAsync<Movie>(
+var movies = await index.SearchAsync<Movie>(
     "wonder",
     new SearchQuery
     {
@@ -225,6 +225,41 @@ JSON Output:
 }
 ```
 
+#### Search with Limit and Offset
+
+You can paginate search results by making queries combining both [offset](https://www.meilisearch.com/docs/reference/api/search#offset) and [limit](https://www.meilisearch.com/docs/reference/api/search#limit).
+
+```c#
+var results = await index.SearchAsync<T>(query, new SearchQuery()
+{
+    Limit = 5,
+    Offset = 0
+});
+
+if (results is SearchResult<T> limitedResults)
+{
+    var estimatedTotalHits = limitedResults.EstimatedTotalHits;
+}
+```
+
+#### Search with defined number of results per page
+
+To get paginated results with page numbers, the [HitsPerPage](https://www.meilisearch.com/docs/reference/api/search#number-of-results-per-page) and [Page](https://www.meilisearch.com/docs/reference/api/search#page) properties must be defined.
+
+```c#
+var results = await index.SearchAsync<T>(query, new SearchQuery()
+{
+    HitsPerPage = pageSize,
+    Page = pageNumber,
+});
+
+if (results is PaginatedSearchResult<T> paginatedResults)
+{
+    var totalHits = paginatedResults.TotalHits;
+    var totalPages = paginatedResults.TotalPages;
+}
+```
+
 ## 🤖 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/Converters/SortFacetValuesConverter.cs

@@ -0,0 +1,29 @@
+using System;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Meilisearch.Converters
+{
+    public class SortFacetValuesConverter : JsonConverter<SortFacetValuesByType>
+    {
+        public override SortFacetValuesByType Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            if (reader.TokenType == JsonTokenType.String)
+            {
+                var enumValue = reader.GetString();
+                if (Enum.TryParse<SortFacetValuesByType>(enumValue, true, out var sortFacetValues))
+                {
+                    return sortFacetValues;
+                }
+            }
+
+            // If we reach here, it means we encountered an unknown value, so we'll use meilisearch default of Alpha
+            return SortFacetValuesByType.Alpha;
+        }
+
+        public override void Write(Utf8JsonWriter writer, SortFacetValuesByType value, JsonSerializerOptions options)
+        {
+            writer.WriteStringValue(value.ToString().ToLower());
+        }
+    }
+}

src/Meilisearch/Faceting.cs

@@ -1,13 +1,39 @@
+using System.Collections.Generic;
 using System.Text.Json.Serialization;
 
+using Meilisearch.Converters;
+
 namespace Meilisearch
 {
     /// <summary>
     /// Faceting configuration.
     /// </summary>
     public class Faceting
     {
+        /// <summary>
+        /// Gets or sets maxValuesPerFacet.
+        /// </summary>
         [JsonPropertyName("maxValuesPerFacet")]
         public int MaxValuesPerFacet { get; set; }
+
+        /// <summary>
+        /// Gets or sets sortFacetValuesBy.
+        /// </summary>
+        [JsonPropertyName("sortFacetValuesBy")]
+        public Dictionary<string, SortFacetValuesByType> SortFacetValuesBy { get; set; }
+    }
+
+    [JsonConverter(typeof(SortFacetValuesConverter))]
+    public enum SortFacetValuesByType
+    {
+        /// <summary>
+        /// Sort by alphanumerical value.
+        /// </summary>
+        Alpha,
+
+        /// <summary>
+        /// Sort by count value.
+        /// </summary>
+        Count
     }
 }

src/Meilisearch/Meilisearch.csproj

@@ -4,7 +4,7 @@
         <TargetFramework>netstandard2.0</TargetFramework>
         <OutputType>Library</OutputType>
         <PackageId>MeiliSearch</PackageId>
-        <Version>0.15.5</Version>
+        <Version>0.16.0</Version>
         <Description>.NET wrapper for Meilisearch, an open-source search engine</Description>
         <RepositoryUrl>https://github.com/meilisearch/meilisearch-dotnet</RepositoryUrl>
         <PackageTags>meilisearch;dotnet;sdk;search-engine;search;instant-search</PackageTags>

tests/Meilisearch.Tests/SettingsTests.cs

@@ -55,7 +55,11 @@ public SettingsTests(TFixture fixture)
                 },
                 Faceting = new Faceting
                 {
-                    MaxValuesPerFacet = 100
+                    MaxValuesPerFacet = 100,
+                    SortFacetValuesBy = new Dictionary<string, SortFacetValuesByType>()
+                    {
+                        ["*"] = SortFacetValuesByType.Alpha
+                    }
                 },
                 Pagination = new Pagination
                 {
@@ -517,7 +521,11 @@ public async Task UpdateFaceting()
         {
             var newFaceting = new Faceting
             {
-                MaxValuesPerFacet = 20
+                MaxValuesPerFacet = 20,
+                SortFacetValuesBy = new Dictionary<string, SortFacetValuesByType>
+                {
+                    ["*"] = SortFacetValuesByType.Count
+                }
             };
 
             await AssertUpdateSuccess(_index.UpdateFacetingAsync, newFaceting);
@@ -529,7 +537,11 @@ public async Task ResetFaceting()
         {
             var newFaceting = new Faceting
             {
-                MaxValuesPerFacet = 30
+                MaxValuesPerFacet = 30,
+                SortFacetValuesBy = new Dictionary<string, SortFacetValuesByType>
+                {
+                    ["*"] = SortFacetValuesByType.Count
+                }
             };
 
             await AssertUpdateSuccess(_index.UpdateFacetingAsync, newFaceting);