Add support for sorting on the documents API

[tibisabau]

Pull Request

Related issue

Fixes #884.

What does this PR do?

• Adds support for sorting on the documents API by introducing a sort parameter to DocumentsQuery
• Updates the Documents class to use POST /fetch endpoint when sort parameter is present
• Adds integration tests to verify sorting functionality for both getDocuments() and getRawDocuments() methods

The code in this pull request was generated by GitHub Copilot with the Claude Sonnet 4.5 model.

PR checklist

Please check if your PR fulfills the following requirements:

• Did you use any AI tool while implementing this PR (code, tests, docs, etc.)? If yes, disclose it in the PR description and describe what it was used for. AI usage is allowed when it is disclosed.
• Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
• Have you read the contributing guidelines?
• Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!

Summary by CodeRabbit

• New Features
  • Added document sorting for both standard and raw retrieval—sort by attributes in ascending or descending order and respect result limits.
• Tests
  • Added integration tests validating sorting behavior, ordering, and result limits for document fetches.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds sorting support to Documents: DocumentsQuery gains a sort field and is included in query/payload builders; Documents.getDocuments and getRawDocuments route requests via POST when sort is present; integration tests for sorted retrieval were added.

Changes

Cohort / File(s)	Summary
Documents API Control Flow src/main/java/com/meilisearch/sdk/Documents.java	getDocuments(...) and getRawDocuments(...) now treat a non-null param.getSort() like a non-null filter: they send a POST to the fetch endpoint instead of falling back to GET.
Query Model Expansion src/main/java/com/meilisearch/sdk/model/DocumentsQuery.java	Added private String[] sort field; toQuery() includes sort as a URL parameter; toString() includes sort in the JSON payload when present.
Sort Functionality Tests src/test/java/com/meilisearch/integration/DocumentsTest.java	Added testGetDocumentsWithSort() and testGetRawDocumentsWithSort() to validate ascending/descending sort behavior and raw response structure after marking title as sortable.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant DocumentsSDK as Documents
  participant HTTP as HTTPClient
  participant Meili as MeiliSearch

  Client->>DocumentsSDK: getDocuments(uid, param, targetClass)
  alt param.getSort() != null OR param.getFilter() != null
    DocumentsSDK->>HTTP: POST /indexes/{uid}/documents/fetch (body: param.toString())
  else
    DocumentsSDK->>HTTP: GET /indexes/{uid}/documents? + param.toQuery()
  end
  HTTP->>Meili: HTTP request
  Meili-->>HTTP: HTTP response
  HTTP-->>DocumentsSDK: parsed response
  DocumentsSDK-->>Client: return documents (mapped to targetClass or raw)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hopped through code with a joyful sort,
Titles aligned in tidy report,
POST when needed, GET when free,
Documents march in order — whee! 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 72.73% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title 'Add support for sorting on the documents API' directly and clearly summarizes the main change in the changeset.
Linked Issues check	✅ Passed	The pull request successfully implements both requirements from issue #884: adds a sort parameter to DocumentsQuery and includes comprehensive integration tests for sorting functionality.
Out of Scope Changes check	✅ Passed	All changes are directly related to adding sorting support to the documents API, with no extraneous modifications detected outside the linked issue scope.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/test/java/com/meilisearch/integration/DocumentsTest.java`:
- Around line 544-549: The current assertion checks that compareTo(...) is not
equal to 1 which is incorrect; replace the equality check with an assertion that
the result of movies[i].getTitle().compareTo(movies[i + 1].getTitle()) is less
than or equal to 0 to verify ascending order. Locate the loop in DocumentsTest
(the for loop iterating over the movies array) and change the compareTo
assertion to use a lessThanOrEqualTo(0) matcher (or equivalent <= 0) so the test
verifies proper ascending order; ensure any required Hamcrest matcher imports
are present.

🧹 Nitpick comments (2)

src/main/java/com/meilisearch/sdk/model/DocumentsQuery.java (1)

28-36: Inconsistent with filter handling.

Adding sort to toQuery() is inconsistent with how filter is handled—filter is not included in toQuery() because it also triggers the POST path in Documents.java. When sort is non-null, the POST endpoint is used with toString() for the body, so this sort parameter in toQuery() will never actually be used with a non-null value.

Consider removing sort from toQuery() to match the filter pattern, or document why it's intentionally included.

Suggested fix to align with filter handling

     public String toQuery() {
         URLBuilder urlb =
                 new URLBuilder()
                         .addParameter("limit", this.getLimit())
                         .addParameter("offset", this.getOffset())
-                        .addParameter("fields", this.getFields())
-                        .addParameter("sort", this.getSort());
+                        .addParameter("fields", this.getFields());
         return urlb.getURL();
     }

src/test/java/com/meilisearch/integration/DocumentsTest.java (1)

645-667: Test coverage is minimal but acceptable.

This test verifies the sort parameter doesn't cause errors and that the response structure is correct, but doesn't verify the actual descending sort order. Since this is raw JSON output, parsing to verify order would add complexity.

Consider adding a basic order verification by checking that known titles appear in expected positions, or parsing the JSON to validate order—though this is optional given the typed test (testGetDocumentsWithSort) already covers sort ordering.