Add the filter field in getDocuments for Meilisearch v1.2 (#1493)

* Add filter parameter on getDocuments for Meilisearch v1.2

Author: bidoubiwa

.eslintrc.js

@@ -5,6 +5,7 @@ module.exports = {
     es2020: true,
     'jest/globals': true,
     node: true,
+    jasmine: true,
   },
   extends: [
     'eslint:recommended',

src/errors/index.ts

@@ -3,3 +3,4 @@ export * from './meilisearch-api-error'
 export * from './meilisearch-communication-error'
 export * from './meilisearch-error'
 export * from './meilisearch-timeout-error'
+export * from './version-hint-message'

src/errors/version-hint-message.ts

@@ -0,0 +1,3 @@
+export function versionErrorHintMessage(message: string, method: string) {
+  return `${message}\nHint: It might not be working because maybe you're not up to date with the Meilisearch version that ${method} call requires.`
+}

src/indexes.ts

@@ -7,8 +7,12 @@
 
 'use strict'
 
-import { MeiliSearchError } from './errors'
-
+import {
+  MeiliSearchError,
+  MeiliSearchCommunicationError,
+  versionErrorHintMessage,
+  MeiliSearchApiError,
+} from './errors'
 import {
   Config,
   SearchResponse,
@@ -302,30 +306,49 @@ class Index<T extends Record<string, any> = Record<string, any>> {
   ///
 
   /**
-   * Get documents of an index
+   * Get documents of an index.
    *
-   * @param parameters - Parameters to browse the documents
-   * @returns Promise containing Document responses
+   * @param parameters - Parameters to browse the documents. Parameters can
+   *   contain the `filter` field only available in Meilisearch v1.2 and newer
+   * @returns Promise containing the returned documents
    */
   async getDocuments<D extends Record<string, any> = T>(
     parameters: DocumentsQuery<D> = {}
   ): Promise<ResourceResults<D[]>> {
-    const url = `indexes/${this.uid}/documents`
-
-    const fields = (() => {
-      if (Array.isArray(parameters?.fields)) {
-        return parameters?.fields?.join(',')
+    parameters = removeUndefinedFromObject(parameters)
+
+    // In case `filter` is provided, use `POST /documents/fetch`
+    if (parameters.filter !== undefined) {
+      try {
+        const url = `indexes/${this.uid}/documents/fetch`
+
+        return await this.httpRequest.post<
+          DocumentsQuery,
+          Promise<ResourceResults<D[]>>
+        >(url, parameters)
+      } catch (e) {
+        if (e instanceof MeiliSearchCommunicationError) {
+          e.message = versionErrorHintMessage(e.message, 'getDocuments')
+        } else if (e instanceof MeiliSearchApiError) {
+          e.message = versionErrorHintMessage(e.message, 'getDocuments')
+        }
+
+        throw e
       }
-      return undefined
-    })()
+      // Else use `GET /documents` method
+    } else {
+      const url = `indexes/${this.uid}/documents`
 
-    return await this.httpRequest.get<Promise<ResourceResults<D[]>>>(
-      url,
-      removeUndefinedFromObject({
+      // Transform fields to query parameter string format
+      const fields = Array.isArray(parameters?.fields)
+        ? { fields: parameters?.fields?.join(',') }
+        : {}
+
+      return await this.httpRequest.get<Promise<ResourceResults<D[]>>>(url, {
         ...parameters,
-        fields,
+        ...fields,
       })
-    )
+    }
   }
 
   /**

src/types/types.ts

@@ -218,6 +218,7 @@ export type RawDocumentAdditionOptions = DocumentOptions & {
 
 export type DocumentsQuery<T = Record<string, any>> = ResourceQuery & {
   fields?: Fields<T>
+  filter?: Filter
 }
 
 export type DocumentQuery<T = Record<string, any>> = {
@@ -549,6 +550,12 @@ export const enum ErrorStatusCode {
   /** @see https://docs.meilisearch.com/errors/#invalid_document_offset */
   INVALID_DOCUMENT_OFFSET = 'invalid_document_offset',
 
+  /** @see https://docs.meilisearch.com/errors/#invalid_document_offset */
+  INVALID_DOCUMENT_FILTER = 'invalid_document_filter',
+
+  /** @see https://docs.meilisearch.com/errors/#invalid_document_offset */
+  MISSING_DOCUMENT_FILTER = 'missing_document_filter',
+
   /** @see https://docs.meilisearch.com/errors/#payload_too_large */
   PAYLOAD_TOO_LARGE = 'payload_too_large',
 

tests/documents.test.ts

@@ -7,6 +7,8 @@ import {
   getClient,
   dataset,
   Book,
+  getKey,
+  HOST,
 } from './utils/meilisearch-test-utils'
 
 const indexNoPk = {
@@ -140,6 +142,57 @@ describe('Documents tests', () => {
         expect(documents.offset).toEqual(2)
       })
 
+      test(`${permission} key: Get documents with filters`, async () => {
+        const client = await getClient(permission)
+        await client.index(indexPk.uid).updateFilterableAttributes(['id'])
+        const { taskUid } = await client
+          .index(indexPk.uid)
+          .addDocuments(dataset)
+        await client.waitForTask(taskUid)
+
+        const documents = await client.index(indexPk.uid).getDocuments<Book>({
+          filter: [['id = 1', 'id = 2']],
+        })
+
+        expect(documents.results.length).toEqual(2)
+      })
+
+      test(`${permission} key: Get documents should trigger error with a MeilisearchCommunicationError`, async () => {
+        const apiKey = await getKey(permission)
+        const client = new MeiliSearch({ host: `${HOST}/indexes`, apiKey })
+
+        try {
+          await client.index(indexPk.uid).getDocuments({ filter: '' })
+
+          fail(
+            'getDocuments should have raised an error when the route does not exist'
+          )
+        } catch (e: any) {
+          expect(e.message).toEqual(
+            "Not Found\nHint: It might not be working because maybe you're not up to date with the Meilisearch version that getDocuments call requires."
+          )
+        }
+      })
+
+      test(`${permission} key: Get documents should trigger error with a hint on a MeilisearchApiError`, async () => {
+        const apiKey = await getKey(permission)
+        const client = new MeiliSearch({ host: `${HOST}`, apiKey })
+
+        try {
+          await client.index(indexPk.uid).getDocuments({ filter: 'id = 1' })
+
+          fail(
+            'getDocuments should have raised an error when the filter is badly formatted'
+          )
+        } catch (e: any) {
+          expect(e.message).toEqual(
+            `Attribute \`id\` is not filterable. This index does not have configured filterable attributes.
+1:3 id = 1
+Hint: It might not be working because maybe you're not up to date with the Meilisearch version that getDocuments call requires.`
+          )
+        }
+      })
+
       test(`${permission} key: Get documents from index that has NO primary key`, async () => {
         const client = await getClient(permission)
         const { taskUid } = await client