From 2007d9fd4bde950a833ed9c2f25084df218511d3 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Fri, 23 Jun 2023 10:45:45 +0200 Subject: [PATCH 1/5] init spec --- text/157-faceting-setting-api.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/text/157-faceting-setting-api.md b/text/157-faceting-setting-api.md index c4d97072..3ffa8486 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,18 @@ 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" +} +``` + ## 3.2. API Endpoints Definition ### 3.2.1. Global Settings API Endpoints Definition From 59f52f78dbf556912b67ebb08686884805093f14 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Mon, 26 Jun 2023 09:38:47 +0200 Subject: [PATCH 2/5] Add property description and open-api.yaml --- open-api.yaml | 12 +++++++++++- text/157-faceting-setting-api.md | 21 ++++++++++++++++++++- 2 files changed, 31 insertions(+), 2 deletions(-) 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/157-faceting-setting-api.md b/text/157-faceting-setting-api.md index 3ffa8486..5a65f7ff 100644 --- a/text/157-faceting-setting-api.md +++ b/text/157-faceting-setting-api.md @@ -47,6 +47,21 @@ The facets that are returned are sorted in ascending lexicographical order. } ``` +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 @@ -67,7 +82,10 @@ Allow fetching the current definition of the faceting setting for an index. ```json { - "maxValuesPerFacet": 100 + "maxValuesPerFacet": 100, + "sortFacetValuesBy": { + "*": "alpha" + } } ``` @@ -118,6 +136,7 @@ See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-t - 🔴 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. +- TODO: ERRORS DEFINITION ###### 3.2.2.2.2.1. Async Errors From d4625ca2ca71588b947216c5f27054af5dab6575 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Mon, 26 Jun 2023 13:58:39 +0200 Subject: [PATCH 3/5] Removes future possibility --- text/157-faceting-setting-api.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/text/157-faceting-setting-api.md b/text/157-faceting-setting-api.md index 5a65f7ff..293da995 100644 --- a/text/157-faceting-setting-api.md +++ b/text/157-faceting-setting-api.md @@ -181,5 +181,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 \ No newline at end of file From d37116474342b28d1e76030de539246253c8d939 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Renault?= Date: Thu, 29 Jun 2023 17:15:16 +0200 Subject: [PATCH 4/5] Update the telemetry --- text/0034-telemetry-policies.md | 6 ++++++ 1 file changed, 6 insertions(+) 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` From 7d9721a96dca067a2183c2d986426bece5985593 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Renault?= Date: Thu, 29 Jun 2023 17:29:20 +0200 Subject: [PATCH 5/5] Update the error of the sortFacetValuesBy setting --- text/157-faceting-setting-api.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/text/157-faceting-setting-api.md b/text/157-faceting-setting-api.md index 293da995..8ada5cb2 100644 --- a/text/157-faceting-setting-api.md +++ b/text/157-faceting-setting-api.md @@ -134,9 +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. -- TODO: ERRORS DEFINITION +- 🔴 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 @@ -181,4 +180,4 @@ The auth layer can return the following errors if Meilisearch is secured (a mast n/a ## 3. Future Possibilities -n/a \ No newline at end of file +n/a