feat: add searchFacetValues endpoint

Author: e-krebs

specs/composition/common/schemas/SearchForFacetValuesResponse.yml

@@ -0,0 +1,50 @@
+searchForFacetValuesResponse:
+  type: object
+  additionalProperties: false
+  properties:
+    results:
+      type: array
+      description: Search for facet values results.
+      items:
+        $ref: '#/searchForFacetValuesResults'
+
+searchForFacetValuesResults:
+  type: object
+  additionalProperties: false
+  required:
+    - facetHits
+    - exhaustiveFacetsCount
+    - indexName
+  x-discriminator-fields:
+    - facetHits
+  properties:
+    indexName:
+      type: string
+    facetHits:
+      type: array
+      description: Matching facet values.
+      items:
+        title: facetHits
+        type: object
+        additionalProperties: false
+        required:
+          - value
+          - highlighted
+          - count
+        properties:
+          value:
+            description: Facet value.
+            example: 'Mobile phone'
+            type: string
+          highlighted:
+            $ref: '../../../common/schemas/HighlightResult.yml#/highlightedValue'
+          count:
+            description: Number of records with this facet value. [The count may be approximated](https://support.algolia.com/hc/en-us/articles/4406975248145-Why-are-my-facet-and-hit-counts-not-accurate-).
+            type: integer
+    exhaustiveFacetsCount:
+      type: boolean
+      description: |
+        Whether the facet count is exhaustive (true) or approximate (false).
+        For more information, see [Why are my facet and hit counts not accurate](https://support.algolia.com/hc/en-us/articles/4406975248145-Why-are-my-facet-and-hit-counts-not-accurate-).
+    processingTimeMS:
+      $ref: '../../../common/schemas/SearchResponse.yml#/processingTimeMS'

specs/composition/paths/search/searchForFacetValues.yml

@@ -0,0 +1,59 @@
+post:
+  tags:
+    - Search
+  operationId: searchForFacetValues
+  x-use-read-transporter: true
+  x-cacheable: true
+  x-acl:
+    - search
+  summary: Search for facet values
+  description: |
+    Searches for values of a specified facet attribute on the composition's main source's index.
+
+    - By default, facet values are sorted by decreasing count.
+      You can adjust this with the `sortFacetValueBy` parameter.
+    - Searching for facet values doesn't work if you have **more than 65 searchable facets and searchable attributes combined**.
+  parameters:
+    - $ref: '../../common/parameters.yml#/compositionID'
+    - name: facetName
+      description: |
+        Facet attribute in which to search for values.
+
+        This attribute must be included in the `attributesForFaceting` index setting with the `searchable()` modifier.
+      in: path
+      required: true
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          title: searchForFacetValuesRequest
+          type: object
+          additionalProperties: false
+          properties:
+            params:
+              title: searchForFacetValuesParams
+              type: object
+              properties:
+                query:
+                  $ref: '../../../common/schemas/SearchParams.yml#/query'
+                maxFacetHits:
+                  $ref: '../../../common/schemas/IndexSettings.yml#/maxFacetHits'
+                searchQuery:
+                  $ref: '../../common/schemas/SearchParams.yml#/searchParams'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '../../common/schemas/SearchForFacetValuesResponse.yml#/searchForFacetValuesResponse'
+    '400':
+      $ref: '../../../common/responses/BadRequest.yml'
+    '402':
+      $ref: '../../../common/responses/FeatureNotEnabled.yml'
+    '403':
+      $ref: '../../../common/responses/MethodNotAllowed.yml'
+    '404':
+      $ref: '../../../common/responses/IndexNotFound.yml'

specs/composition/spec.yml

@@ -58,6 +58,8 @@ paths:
   # ########################
   /1/compositions/{compositionID}/run:
     $ref: 'paths/search/run.yml'
+  /1/compositions/{compositionID}/facets/{facetName}/query:
+    $ref: 'paths/search/searchForFacetValues.yml'
 
   # #########################
   # ### Objects Endpoints ###