diff --git a/open-api.yaml b/open-api.yaml index 17267fd7..b557ea49 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -570,6 +570,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: | @@ -2291,6 +2297,8 @@ paths: maxTotalHits: 1000 faceting: maxValuesPerFacet: 100 + sortFacetValuesBy: + "*": "alpha" '401': $ref: '#/components/responses/401' '404': @@ -2390,6 +2398,8 @@ paths: maxTotalHits: 1000 faceting: maxValuesPerFacet: 100 + sortFacetValuesBy: + "*": "alpha" responses: '202': description: Accepted @@ -2967,7 +2977,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. diff --git a/text/0034-telemetry-policies.md b/text/0034-telemetry-policies.md index 01e8e8b6..126798bf 100644 --- a/text/0034-telemetry-policies.md +++ b/text/0034-telemetry-policies.md @@ -157,6 +157,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` | @@ -449,6 +451,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` | @@ -522,6 +526,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` diff --git a/text/157-faceting-setting-api.md b/text/157-faceting-setting-api.md index c4d97072..8ada5cb2 100644 --- a/text/157-faceting-setting-api.md +++ b/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` \ No newline at end of file +n/a