feat: add sort parameter support to documents API

Author: Ritinpaul

.code-samples.meilisearch.yaml

@@ -31,8 +31,6 @@ create_an_index_1: |-
   client.createIndex('movies', { primaryKey: 'id' })
 update_an_index_1: |-
   client.updateIndex('movies', { primaryKey: 'id' })
-rename_an_index_1: |-
-  client.updateIndex('INDEX_A', { indexUid: 'INDEX_B' })
 delete_an_index_1: |-
   client.deleteIndex('movies')
 swap_indexes_1: |-
@@ -55,6 +53,14 @@ get_documents_post_1: |-
     fields: ['title', 'genres', 'rating', 'language'],
     limit: 3
   })
+get_documents_sort_1: |-
+  client.index('movies').getDocuments({
+    sort: ['release_date:desc']
+  })
+get_documents_sort_multiple_1: |-
+  client.index('movies').getDocuments({
+    sort: ['rating:desc', 'release_date:asc']
+  })
 add_or_replace_documents_1: |-
   client.index('movies').addDocuments([{
       id: 287947,

src/indexes.ts

@@ -298,24 +298,35 @@ export class Index<T extends RecordAny = RecordAny> {
    * Get documents of an index.
    *
    * @param params - Parameters to browse the documents. Parameters can contain
-   *   the `filter` field only available in Meilisearch v1.2 and newer
+   *   the `filter` field only available in Meilisearch v1.2 and newer, and the
+   *   `sort` field available in Meilisearch v1.16 and newer
    * @returns Promise containing the returned documents
    */
   async getDocuments<D extends RecordAny = T>(
     params?: DocumentsQuery<D>,
   ): Promise<ResourceResults<D[]>> {
     const relativeBaseURL = `indexes/${this.uid}/documents`;
+    // Create a shallow copy so we can safely normalize parameters
+    const normalizedParams = params ? { ...params } : undefined;
+    // Omit empty sort arrays to avoid server-side validation errors
+    if (
+      normalizedParams &&
+      Array.isArray(normalizedParams.sort) &&
+      normalizedParams.sort.length === 0
+    ) {
+      delete (normalizedParams as { sort?: string[] }).sort;
+    }
 
-    return params?.filter !== undefined
+    return normalizedParams?.filter !== undefined
       ? // In case `filter` is provided, use `POST /documents/fetch`
         await this.httpRequest.post<ResourceResults<D[]>>({
           path: `${relativeBaseURL}/fetch`,
-          body: params,
+          body: normalizedParams,
         })
       : // Else use `GET /documents` method
         await this.httpRequest.get<ResourceResults<D[]>>({
           path: relativeBaseURL,
-          params,
+          params: normalizedParams,
         });
   }
 

src/types/types.ts

@@ -141,7 +141,7 @@ export type ResultsWrapper<T> = {
 
 export type IndexOptions = {
   primaryKey?: string;
-  indexUid?: string;
+  uid?: string;
 };
 
 export type IndexObject = {
@@ -510,6 +510,12 @@ export type DocumentsQuery<T = RecordAny> = ResourceQuery & {
   limit?: number;
   offset?: number;
   retrieveVectors?: boolean;
+  /**
+   * Array of strings containing the attributes to sort on. Each string should
+   * be in the format "attribute:direction" where direction is either "asc" or
+   * "desc". Example: ["price:asc", "rating:desc"]
+   */
+  sort?: string[];
 };
 
 export type DocumentQuery<T = RecordAny> = {

tests/documents.test.ts

@@ -258,6 +258,78 @@ describe("Documents tests", () => {
         expect(documentsGet.results[0]).not.toHaveProperty("_vectors");
       });
 
+      test(`${permission} key: Get documents with sorting by single field`, async () => {
+        const client = await getClient(permission);
+
+        await client
+          .index(indexPk.uid)
+          .updateSortableAttributes(["id"])
+          .waitTask();
+
+        await client.index(indexPk.uid).addDocuments(dataset).waitTask();
+
+        const documents = await client.index(indexPk.uid).getDocuments<Book>({
+          sort: ["id:asc"],
+        });
+
+        expect(documents.results.length).toEqual(dataset.length);
+        // Verify documents are sorted by id in ascending order
+        const ids = documents.results.map((doc) => doc.id);
+        const sortedIds = [...ids].sort((a, b) => a - b);
+        expect(ids).toEqual(sortedIds);
+      });
+
+      test(`${permission} key: Get documents with sorting by multiple fields`, async () => {
+        const client = await getClient(permission);
+
+        await client
+          .index(indexPk.uid)
+          .updateSortableAttributes(["id", "title"])
+          .waitTask();
+
+        await client.index(indexPk.uid).addDocuments(dataset).waitTask();
+
+        const documents = await client.index(indexPk.uid).getDocuments<Book>({
+          sort: ["id:desc", "title:asc"],
+        });
+
+        expect(documents.results.length).toEqual(dataset.length);
+        // Verify documents are sorted by id in descending order, then by title ascending
+        const ids = documents.results.map((doc) => doc.id);
+        const sortedIds = [...ids].sort((a, b) => b - a);
+        expect(ids).toEqual(sortedIds);
+      });
+
+      test(`${permission} key: Get documents with empty sort array`, async () => {
+        const client = await getClient(permission);
+
+        await client
+          .index(indexPk.uid)
+          .updateSortableAttributes(["id"])
+          .waitTask();
+
+        await client.index(indexPk.uid).addDocuments(dataset).waitTask();
+
+        const documents = await client.index(indexPk.uid).getDocuments<Book>({
+          sort: [],
+        });
+
+        expect(documents.results.length).toEqual(dataset.length);
+        // Should return documents in default order (no specific sorting)
+      });
+
+      test(`${permission} key: Get documents with sorting should trigger error for non-sortable attribute`, async () => {
+        const client = await getClient(permission);
+
+        await client.index(indexPk.uid).addDocuments(dataset).waitTask();
+
+        await assert.rejects(
+          client.index(indexPk.uid).getDocuments({ sort: ["title:asc"] }),
+          Error,
+          /Attribute `title` is not sortable/,
+        );
+      });
+
       test(`${permission} key: Replace documents from index that has NO primary key`, async () => {
         const client = await getClient(permission);
         await client.index(indexNoPk.uid).addDocuments(dataset).waitTask();