Add the searchForFacetValue method

Author: bidoubiwa

README.md

@@ -412,6 +412,14 @@ client.multiSearch(queries?: MultiSearchParams, config?: Partial<Request>): Prom
 
 `multiSearch` uses the `POST` method when performing its request to Meilisearch.
 
+### Search For Facet Value
+
+#### [Search for facet value](#)
+
+```ts
+client.index<T>('xxx').searchForFacetValue(params: SearchForFacetValuesParams, config?: Partial<Request>): Promise<SearchForFacetValuesResponse>
+```
+
 ### Documents <!-- omit in toc -->
 
 #### [Add or replace multiple documents](https://www.meilisearch.com/docs/reference/api/documents#add-or-replace-documents)

src/indexes.ts

@@ -45,6 +45,8 @@ import {
   ContentType,
   DocumentsIds,
   DocumentsDeletionQuery,
+  SearchForFacetValuesParams,
+  SearchForFacetValuesResponse,
 } from './types'
 import { removeUndefinedFromObject } from './utils'
 import { HttpRequests } from './http-requests'
@@ -146,6 +148,27 @@ class Index<T extends Record<string, any> = Record<string, any>> {
     )
   }
 
+  /**
+   * Search for facet values
+   *
+   * @param params - Parameters used to search on the facets
+   * @param config - Additional request configuration options
+   * @returns Promise containing the search response
+   */
+  async searchForFacetValue(
+    params: SearchForFacetValuesParams,
+    config?: Partial<Request>
+  ): Promise<SearchForFacetValuesResponse> {
+    const url = `indexes/${this.uid}/facet-search`
+
+    return await this.httpRequest.post(
+      url,
+      removeUndefinedFromObject(params),
+      undefined,
+      config
+    )
+  }
+
   ///
   /// INDEX
   ///

src/types/types.ts

@@ -189,6 +189,29 @@ export type FieldDistribution = {
   [field: string]: number
 }
 
+/*
+ * Facet search
+ */
+
+export type SearchForFacetValuesParams = SearchParams & {
+  facetName: string
+  facetQuery?: string
+  q?: string
+  filter?: Filter
+  matchingStrategy?: MatchingStrategies
+}
+
+export type FacetHit = {
+  value: string
+  count: number
+}
+
+export type SearchForFacetValuesResponse = {
+  hits: FacetHit[]
+  query: string | null
+  processingTimeMs: number
+}
+
 /*
  ** Documents
  */

tests/facet_search.test.ts

@@ -0,0 +1,108 @@
+import {
+  clearAllIndexes,
+  config,
+  getClient,
+} from './utils/meilisearch-test-utils'
+
+const index = {
+  uid: 'movies_test',
+}
+
+const dataset = [
+  {
+    id: 123,
+    title: 'Pride and Prejudice',
+    genres: ['romance', 'action'],
+  },
+  {
+    id: 456,
+    title: 'Le Petit Prince',
+    genres: ['adventure', 'comedy'],
+  },
+  {
+    id: 2,
+    title: 'Le Rouge et le Noir',
+    genres: 'romance',
+  },
+  {
+    id: 1,
+    title: 'Alice In Wonderland',
+    genres: ['adventure'],
+  },
+]
+
+describe.each([
+  { permission: 'Master' },
+  { permission: 'Admin' },
+  { permission: 'Search' },
+])('Test on POST search', ({ permission }) => {
+  beforeAll(async () => {
+    await clearAllIndexes(config)
+    const client = await getClient('Master')
+    const newFilterableAttributes = ['genres', 'title']
+
+    await client.createIndex(index.uid)
+    await client.index(index.uid).updateSettings({
+      filterableAttributes: newFilterableAttributes,
+    })
+    const { taskUid } = await client.index(index.uid).addDocuments(dataset)
+    await client.waitForTask(taskUid)
+  })
+
+  test(`${permission} key: basic facet value search`, async () => {
+    const client = await getClient(permission)
+
+    const params = {
+      facetQuery: 'a',
+      facetName: 'genres',
+    }
+    const response = await client.index(index.uid).searchForFacetValue(params)
+
+    expect(response.hits.length).toEqual(2)
+    expect(response.query).toEqual('a')
+  })
+
+  test(`${permission} key: facet value search with no facet query`, async () => {
+    const client = await getClient(permission)
+
+    const params = {
+      facetName: 'genres',
+    }
+    const response = await client.index(index.uid).searchForFacetValue(params)
+
+    expect(response.hits.length).toEqual(4)
+    expect(response.query).toEqual(null)
+  })
+
+  test(`${permission} key: facet value search with filter`, async () => {
+    const client = await getClient(permission)
+
+    const params = {
+      facetName: 'genres',
+      facetQuery: 'a',
+      filter: ['genres = action'],
+    }
+    const response = await client.index(index.uid).searchForFacetValue(params)
+
+    expect(response.hits.length).toEqual(1)
+  })
+
+  test(`${permission} key: facet value search with search query`, async () => {
+    const client = await getClient(permission)
+
+    const params = {
+      facetName: 'genres',
+      facetQuery: 'a',
+      q: 'Alice',
+    }
+    const response = await client.index(index.uid).searchForFacetValue(params)
+
+    expect(response.hits.length).toEqual(1)
+  })
+})
+
+jest.setTimeout(100 * 1000)
+
+afterAll(() => {
+  return clearAllIndexes(config)
+})