From 1d0b291f732ddd56644c706418809e520382c1f3 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 23 Feb 2023 13:37:00 +0100 Subject: [PATCH 1/9] update search-api.md --- text/0118-search-api.md | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/text/0118-search-api.md b/text/0118-search-api.md index cc15c596..1cd1a827 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -410,6 +410,8 @@ Attributes used in `facets` must be added to the `filterableAttributes` list of The distribution of the different facets is returned in the `facetDistribution` response parameter. +Statistics are computed and returned within the `facetStats` object for distributed facets that contain only strictly numerical values. See [`facetStats`](#3210-facetstats) section. + #### 3.1.5. `limit` - Type: Integer @@ -839,8 +841,9 @@ Only the documents containing ALL the query words (i.e. in the `q` parameter) ar | [`totalPages`](#327-totalpages) | Integer | False | | [`totalHits`](#328-totalhits) | Integer | False | | [`facetDistribution`](#329-facetdistribution) | Object | False | -| [`processingTimeMs`](#3210-processingtimems) | Integer | True | -| [`query`](#3211-query) | String | True | +| [`facetStats`](#3210-facetstats) | Object | False | +| [`processingTimeMs`](#3211-processingtimems) | Integer | True | +| [`query`](#3212-query) | String | True | #### 3.2.1. `hits` @@ -1152,16 +1155,27 @@ Added to the search response when `facets` is set for a search query. It contain If a field distributed as a facet contains no value, it is returned as a `facetDistribution` field with an empty object as value. -> See [3.1.4. `facet`](#314-facets) section. +> See [3.1.4. `facets`](#314-facets) section. + +#### 3.2.10. `facetStats` + +- Type: Object +- Required: False + +When using the `facets` parameter at search to distribute facets, the facets that strictly contains numeric values are displayed in a `facetStats` object that contains, per facet, the numeric `min` and `max` values of the hits returned by the search query. + +It ignores string values even if parseable. e.g `"21"` isn't considered by the engine when computing the `facetStats` `min` and `max`. + +> See [3.1.4. `facets`](#314-facets) section. -#### 3.2.10. `processingTimeMs` +#### 3.2.11. `processingTimeMs` - Type: Integer - Required: True Processing time of the search query in **milliseconds**. -#### 3.2.11. `query` +#### 3.2.12. `query` - Type: String - Required: True From fd59323c8a30bbdd2c6fb0fe421ff50283294c68 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 23 Feb 2023 13:46:35 +0100 Subject: [PATCH 2/9] rephrase --- text/0118-search-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0118-search-api.md b/text/0118-search-api.md index 1cd1a827..1da74ed0 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -1162,7 +1162,7 @@ If a field distributed as a facet contains no value, it is returned as a `facetD - Type: Object - Required: False -When using the `facets` parameter at search to distribute facets, the facets that strictly contains numeric values are displayed in a `facetStats` object that contains, per facet, the numeric `min` and `max` values of the hits returned by the search query. +When using the `facets` parameter at to distribute facets, the facets that stricly contain numeric values are displayed in a `facetStats` object that contains, per facet, the numeric `min` and `max` values of the hits returned by the search query. It ignores string values even if parseable. e.g `"21"` isn't considered by the engine when computing the `facetStats` `min` and `max`. From 7c8da8af91478600c8a0547661a52d447f91d53d Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 23 Feb 2023 13:50:39 +0100 Subject: [PATCH 3/9] update open-api.yml --- open-api.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/open-api.yaml b/open-api.yaml index 27d6296d..975f057b 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -279,6 +279,18 @@ components: comedy: 475 mystery: 70 thriller: 217 + facetStats: + type: object + additionalProperties: + type: object + min: + type: number + description: The minimum value for the numerical facet being distributed. + max: + type: number + description: The maximum value for the numerical facet being distributed. + description: | + When using the facets parameter at to distribute facets, the facets that stricly contain numeric values are displayed in a facetStats object that contains, per facet, the numeric min and max values of the hits returned by the search query. processingTimeMs: type: integer description: Processing time of the query. From ce46ad4969ed56391c1a48c702dcfd30f29f6df1 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 23 Feb 2023 13:53:52 +0100 Subject: [PATCH 4/9] rephrase, add example on open-api.yml --- open-api.yaml | 6 +++++- text/0118-search-api.md | 4 ++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index 975f057b..e905db9f 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -290,7 +290,11 @@ components: type: number description: The maximum value for the numerical facet being distributed. description: | - When using the facets parameter at to distribute facets, the facets that stricly contain numeric values are displayed in a facetStats object that contains, per facet, the numeric min and max values of the hits returned by the search query. + When using the facets parameter, the distributed facets that stricly contain numeric values are displayed in a facetStats object that contains, per facet, the numeric min and max values of the hits returned by the search query. + example: + price: + min: 1 + max: 4999.99 processingTimeMs: type: integer description: Processing time of the query. diff --git a/text/0118-search-api.md b/text/0118-search-api.md index 1da74ed0..7dab3448 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -410,7 +410,7 @@ Attributes used in `facets` must be added to the `filterableAttributes` list of The distribution of the different facets is returned in the `facetDistribution` response parameter. -Statistics are computed and returned within the `facetStats` object for distributed facets that contain only strictly numerical values. See [`facetStats`](#3210-facetstats) section. +Statistics are computed and returned within the `facetStats` object for distributed facets. See [`facetStats`](#3210-facetstats) section. #### 3.1.5. `limit` @@ -1162,7 +1162,7 @@ If a field distributed as a facet contains no value, it is returned as a `facetD - Type: Object - Required: False -When using the `facets` parameter at to distribute facets, the facets that stricly contain numeric values are displayed in a `facetStats` object that contains, per facet, the numeric `min` and `max` values of the hits returned by the search query. +When using the `facets` parameter, the distributed facets that stricly contain numeric values are displayed in a `facetStats` object that contains, per facet, the numeric `min` and `max` values of the hits returned by the search query. It ignores string values even if parseable. e.g `"21"` isn't considered by the engine when computing the `facetStats` `min` and `max`. From 5063de75e93f4cb0a68c56f9abba09d9fca952a3 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 23 Feb 2023 13:57:44 +0100 Subject: [PATCH 5/9] Add examples --- open-api.yaml | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/open-api.yaml b/open-api.yaml index e905db9f..c3a4e89e 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -1840,6 +1840,19 @@ paths: length: 5 - start: 155 length: 5 + facetDistributions: + genres: + action: 273 + animation: 118 + adventure: 132 + fantasy: 67 + comedy: 475 + mystery: 70 + thriller: 217 + facetStats: + price: + min: 1 + max: 4999.99 limit: 0 offset: 0 estimatedTotalHits: 0 @@ -1995,6 +2008,19 @@ paths: length: 5 - start: 155 length: 5 + facetDistributions: + genres: + action: 273 + animation: 118 + adventure: 132 + fantasy: 67 + comedy: 475 + mystery: 70 + thriller: 217 + facetStats: + price: + min: 1 + max: 4999.99 limit: 0 offset: 0 estimatedTotalHits: 0 From 28c34110c884c1320cf1e0854bfb4e1a7cb074eb Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 23 Feb 2023 14:00:18 +0100 Subject: [PATCH 6/9] fix --- open-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index c3a4e89e..c17e2015 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -1840,7 +1840,7 @@ paths: length: 5 - start: 155 length: 5 - facetDistributions: + facetDistribution: genres: action: 273 animation: 118 @@ -2008,7 +2008,7 @@ paths: length: 5 - start: 155 length: 5 - facetDistributions: + facetDistribution: genres: action: 273 animation: 118 From 0563fec70e1f24a87448a8cc94b4c2c3104b5c58 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 23 Feb 2023 18:35:02 +0100 Subject: [PATCH 7/9] Update text/0118-search-api.md Co-authored-by: Louis Dureuil --- text/0118-search-api.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/text/0118-search-api.md b/text/0118-search-api.md index 7dab3448..0cef584d 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -1162,7 +1162,9 @@ If a field distributed as a facet contains no value, it is returned as a `facetD - Type: Object - Required: False -When using the `facets` parameter, the distributed facets that stricly contain numeric values are displayed in a `facetStats` object that contains, per facet, the numeric `min` and `max` values of the hits returned by the search query. +When using the `facets` parameter, the distributed facets that contain some numeric values are displayed in a `facetStats` object that contains, per facet, the numeric `min` and `max` values of the hits returned by the search query. + +If none of the hits returned by the search query have a numeric value for a facet, this facet is not part of the `facetStats` object. It ignores string values even if parseable. e.g `"21"` isn't considered by the engine when computing the `facetStats` `min` and `max`. From f57388f76301d49af9060e439a523088e9a7c708 Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Thu, 23 Feb 2023 18:39:43 +0100 Subject: [PATCH 8/9] rephrase --- open-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/open-api.yaml b/open-api.yaml index c17e2015..70e43179 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -290,7 +290,7 @@ components: type: number description: The maximum value for the numerical facet being distributed. description: | - When using the facets parameter, the distributed facets that stricly contain numeric values are displayed in a facetStats object that contains, per facet, the numeric min and max values of the hits returned by the search query. + When using the facets parameter, the distributed facets that contain some numeric values are displayed in a facetStats object that contains, per facet, the numeric min and max values of the hits returned by the search query. If none of the hits returned by the search query have a numeric value for a facet, this facet is not part of the facetStats object. example: price: min: 1 From 44ee83e5447ab1aed244cedc279dbff4a08ce3ac Mon Sep 17 00:00:00 2001 From: Louis Dureuil Date: Tue, 14 Mar 2023 09:18:07 +0100 Subject: [PATCH 9/9] Clarify that facet stats are for all search results --- text/0118-search-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0118-search-api.md b/text/0118-search-api.md index 0cef584d..6cbe3991 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -1162,7 +1162,7 @@ If a field distributed as a facet contains no value, it is returned as a `facetD - Type: Object - Required: False -When using the `facets` parameter, the distributed facets that contain some numeric values are displayed in a `facetStats` object that contains, per facet, the numeric `min` and `max` values of the hits returned by the search query. +When using the `facets` parameter, the distributed facets that contain some numeric values are displayed in a `facetStats` object that contains, per facet, the numeric `min` and `max` values for that facet of all documents matching the search query. If none of the hits returned by the search query have a numeric value for a facet, this facet is not part of the `facetStats` object.