Faceting Setting API - sortFacetValuesBy (#247)

* init spec

* Add property description and open-api.yaml

* Removes future possibility

* Update the telemetry

* Update the error of the sortFacetValuesBy setting

---------

Co-authored-by: Clément Renault <[email protected]>

Author: gmourier

open-api.yaml

@@ -606,6 +606,12 @@ components:
           type: integer
           default: 100
           nullable: false
+        sortFacetValuesBy:
+          description: Defines how facet values are sorted. By default, all facets (`*`) are sorted by name, alphanumerically in ascending order (`alpha`). `count` sorts facet values by the number of documents containing a facet value in descending order.
+          type: object
+          example:
+            "*": 'alpha'
+            "genres": 'count'
     filterableAttributes:
       type: array
       description: |
@@ -2401,6 +2407,8 @@ paths:
                       maxTotalHits: 1000
                     faceting:
                       maxValuesPerFacet: 100
+                      sortFacetValuesBy:
+                        "*": "alpha"
         '401':
           $ref: '#/components/responses/401'
         '404':
@@ -2500,6 +2508,8 @@ paths:
                     maxTotalHits: 1000
                   faceting:
                     maxValuesPerFacet: 100
+                    sortFacetValuesBy:
+                      "*": "alpha"
       responses:
         '202':
           description: Accepted
@@ -3077,7 +3087,7 @@ paths:
       operationId: indexes.settings.faceting.update
       summary: Update faceting settings
       description: |
-        Update the typo tolerance faceting of an index.
+        Update the faceting settings of an index.
 
         > info
         > If the provided index does not exist, it will be created.

text/0034-telemetry-policies.md

@@ -158,6 +158,8 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat
 | `typo_tolerance.min_word_size_for_typos.two_typos`| The defined value for `minWordSizeForTypos.twoTypos` property | `9` | `Settings Updated`, `TypoTolerance Updated` |
 | `pagination.max_total_hits`                 | The defined value for `pagination.maxTotalHits` property | `1000` | `Settings Updated`, `Pagination Updated` |
 | `faceting.max_values_per_facet`         | The defined value for `faceting.maxValuesPerFacet` property | `100` | `Settings Updated`, `Faceting Updated` |
+| `faceting.sort_facet_values_by_star_count` | Whether the user set all fields to be sort by count | `true` | `Settings Updated`, `Faceting Updated` |
+| `faceting.sort_facet_values_by_total`      | The number of different values that were set | `10` | `Settings Updated`, `Faceting Updated` |
 | `distinct_attribute.set` | `true` if a field name is specified as a distrinct attribute, otherwise `false`. | `false` | `Settings Updated`, `DistinctAttribute Updated` |
 | `displayed_attributes.total`   | Number of displayed attributes. | `3` | `SettingUpdated`, `DisplayedAttributes Updated` |
 | `displayed_attributes.with_wildcard` | `true` if `*` is specified as a displayed attribute, otherwise `false`. | `false` | `SettingUpdated`, `DisplayedAttributes Updated` |
@@ -467,6 +469,8 @@ This property allows us to gather essential information to better understand on
 | typo_tolerance.min_word_size_for_typos.two_typos | The defined value for `minWordSizeForTypos.twoTypos` property. | `9` |
 | pagination.max_total_hits                 | The defined value for `pagination.maxTotalHits` property | `1000` |
 | faceting.max_values_per_facet         | The defined value for `faceting.maxValuesPerFacet` property | `100` |
+| faceting.sort_facet_values_by_star_count | Whether the user set all fields to be sort by count | `true` |
+| faceting.sort_facet_values_by_total | The number of different values that were set | `10` |
 | distinct_attribute.set | `true` if a field name is specified, otherwise `false`. | `false` |
 | displayed_attributes.total   | Number of displayed attributes. | `3` |
 | displayed_attributes.with_wildcard | `true` if `*` is specified as a displayed attribute, otherwise `false`. | `false` |
@@ -540,6 +544,8 @@ This property allows us to gather essential information to better understand on
 |---------------|-------------|---------|
 | user_agent    | Represents the user-agent encountered on this call. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` |
 | faceting.max_values_per_facet | The defined value for `maxValuesPerFacet` property | `100` |
+| faceting.sort_facet_values_by_star_count | Whether the user set all fields to be sort by count | `true` |
+| faceting.sort_facet_values_by_total | The number of different values that were set | `10` |
 
 ## `DistinctAttribute Updated`
 

text/157-faceting-setting-api.md

@@ -17,6 +17,7 @@ This settings will host the parameters to configure the faceting behavior for an
 | Field                                            | Type            | Required |
 |--------------------------------------------------|-----------------|----------|
 | [maxValuesPerFacet](#311-maxValuesPerFacet)      | Integer         | False    |
+| [sortFacetValuesBy](#312-sortFacetValuesBy)      | Object          | False    |
 
 #### 3.1.1. `maxValuesPerFacet`
 
@@ -34,6 +35,33 @@ Increasing this value can degrade performance as well as expose the data of an i
 
 The facets that are returned are sorted in ascending lexicographical order.
 
+#### 3.1.2 `sortFacetValuesBy`
+
+- Type: Object
+- Required: False
+- Default:
+
+```json
+{
+    "*": "alpha"
+}
+```
+
+Defines how facet values are sorted. By default, all facets (`*`) are sorted by name, alphanumerically in ascending order (`alpha`).
+
+It is possible to sort them by the number of documents containing a facet value in descending order using `count`.
+
+It is possible to specify a particular order for a facet.
+
+```json
+{
+    "*": "alpha",
+    "genre": "count"
+}
+```
+
+In this example, values from facets other than `genres` will be displayed sorted by their name in ascending alphanumeric order, while values from the `genres` facet will be sorted in descending order by the count of the number of documents containing each value.
+
 ## 3.2. API Endpoints Definition
 
 ### 3.2.1. Global Settings API Endpoints Definition
@@ -54,7 +82,10 @@ Allow fetching the current definition of the faceting setting for an index.
 
 ```json
     {
-        "maxValuesPerFacet": 100
+        "maxValuesPerFacet": 100,
+        "sortFacetValuesBy": {
+            "*": "alpha"
+        }
     }
 ```
 
@@ -103,8 +134,8 @@ See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-t
 - 🔴 Sending an empty payload returns a [missing_payload](0061-error-format-and-definitions.md#missing_payload) error.
 - 🔴 Sending an invalid JSON payload returns a [malformed_payload](0061-error-format-and-definitions.md#malformed_payload) error.
 - 🔴 Sending an invalid index uid format for the `:index_uid` path parameter returns an [invalid_index_uid](0061-error-format-and-definitions.md#invalid_index_uid) error.
-- 🔴 Sending a value different from `null` or with a different type than `Integer` for the `maxValuesPerFacet` field returns
-an [invalid_settings_faceting](0061-error-format-and-definitions.md#invalid_settings_faceting) error.
+- 🔴 Sending a value different from `null` or with a different type than `Integer` for the `maxValuesPerFacet` field returns an [invalid_settings_faceting](0061-error-format-and-definitions.md#invalid_settings_faceting) error.
+- 🔴 Sending a value different from `null` or an object with value with a different type than `"alpha"` or `"count"` for the `sortFacetValuesBy` field returns an [invalid_settings_faceting](0061-error-format-and-definitions.md#invalid_settings_faceting) error.
 
 ###### 3.2.2.2.2.1. Async Errors
 
@@ -149,5 +180,4 @@ The auth layer can return the following errors if Meilisearch is secured (a mast
 n/a
 
 ## 3. Future Possibilities
-
-- Introduces a field to define the sorting of facets. e.g `sort` by `count`/`alphanumeric`
+n/a