Search API — Add facetStats description (#224)

* update search-api.md * rephrase * update open-api.yml * rephrase, add example on open-api.yml * Add examples * fix * Update text/0118-search-api.md Co-authored-by: Louis Dureuil <louis.dureuil@gmail.com> * rephrase * Clarify that facet stats are for all search results --------- Co-authored-by: Louis Dureuil <louis.dureuil@gmail.com>
meilisearch · Apr 3, 2023 · 9cf52be · 9cf52be
1 parent 3d792cc
commit 9cf52be
Show file tree

Hide file tree

Showing 2 changed files with 63 additions and 5 deletions.
diff --git a/open-api.yaml b/open-api.yaml
@@ -279,6 +279,22 @@ 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, 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
+              max: 4999.99
         processingTimeMs:
           type: integer
           description: Processing time of the query.
@@ -1836,6 +1852,19 @@ paths:
                               length: 5
                             - start: 155
                               length: 5
+                    facetDistribution:
+                      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
@@ -1991,6 +2020,19 @@ paths:
                               length: 5
                             - start: 155
                               length: 5
+                    facetDistribution:
+                      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

diff --git a/text/0118-search-api.md b/text/0118-search-api.md
@@ -412,6 +412,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. See [`facetStats`](#3210-facetstats) section.
+
 #### 3.1.5. `limit`
 
 - Type: Integer
@@ -841,8 +843,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`
 
@@ -1154,16 +1157,29 @@ 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, 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.
+
+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