Merge #579

579: Update search docs r=ahmednfwela a=danFbach

# Pull Request

## Related issue
Fixes #577, references #578 

## What does this PR do?
- Updates docs to better reflect how results can be consumed.
- Some of the existing docs are wrong as `SearchResult<T> result = await index.SearchAsync(...);` is actually invalid since an explicit cast is required from `ISearchable<T>` to the type of result.
- There was no context showing that the result should be cast to either `SearchResult<T>` or `PaginatedResult<T>` in order to populate properties `EstimatedTotalHits` or `TotalHits` and `TotalPages` respectively.

## 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?

If you have any critiques or anything you want added to the docs for this purpose, let me know. Just hoping to clarify how transform the interface correctly.

Technically the proper type could be derive by one of two methods:
```c#
var result = (SearchResult<T>)await index.SearchAsync<T>(...);
```
or
```c#
var result = await index.SearchAsync<T>(...);
if (result is SearchResult<T> searchResult)
{
    //...
}
```
I prefer the latter, so that's how i changed the docs.

Co-authored-by: Dan Fehrenbach <[email protected]>
Co-authored-by: Clémentine <[email protected]>

Author: 3 people

.code-samples.meilisearch.yaml

@@ -34,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);
@@ -69,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: |-
@@ -269,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
   {
@@ -394,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);
@@ -548,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);
@@ -565,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()
   {
@@ -575,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: |-
@@ -624,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");
@@ -659,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 {

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.