Merge #724

724: Add support to get documents by filter r=curquiza a=bhupixb

# Pull Request

## Related issue
Fixes #613

## What does this PR do?
- Add support to get documents by filter.
- Updatex code samples.

## PR checklist
Please check if your PR fulfills the following requirements:
- [x] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [x] Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!


Co-authored-by: Bhupendra Yadav <[email protected]>
Co-authored-by: Clémentine <[email protected]>

Author: 3 people

.code-samples.meilisearch.yaml

@@ -25,8 +25,14 @@ get_one_document_1: |-
   DocumentQuery query = new DocumentQuery().setFields(new String[] {"id", "title", "poster", "release_date"});
   client.index("movies").getDocument("25684", query);
 get_documents_1: |-
-  DocumentsQuery query = new DocumentsQuery().setLimit(2);
-  client.index("movies").getDocuments(query);
+  DocumentsQuery query = new DocumentsQuery().setLimit(2).setFilter(new String[] {"genres = action"});
+  client.index("movies").getDocuments(query, TargetClassName.class);
+get_documents_post_1: |-
+  DocumentsQuery query = new DocumentsQuery()
+    .setFilter(new String[] {"(rating > 3 AND (genres = Adventure OR genres = Fiction)) AND language = English"})
+    .setFields(new String[] {"title", "genres", "rating", "language"})
+    .setLimit(3);
+  client.index("books").getDocuments(query, TargetClassName.class);
 add_or_replace_documents_1: |-
   client.index("movies").addDocuments("[{"
     + "\"id\": 287947,"

src/main/java/com/meilisearch/sdk/Documents.java

@@ -109,6 +109,13 @@ <T> Results<T> getDocuments(String uid, Class<T> targetClass) throws Meilisearch
      */
     <T> Results<T> getDocuments(String uid, DocumentsQuery param, Class<T> targetClass)
             throws MeilisearchException {
+        if (param.getFilter() != null) {
+            return httpClient.post(
+                    documentPathWithFetch(uid).getURL(),
+                    param.toString(),
+                    Results.class,
+                    targetClass);
+        }
         return httpClient.<Results>get(
                 documentPath(uid).addQuery(param.toQuery()).getURL(), Results.class, targetClass);
     }
@@ -133,6 +140,10 @@ String getRawDocuments(String uid) throws MeilisearchException {
      * @throws MeilisearchException if an error occurs
      */
     String getRawDocuments(String uid, DocumentsQuery param) throws MeilisearchException {
+        if (param.getFilter() != null) {
+            return httpClient.post(
+                    documentPathWithFetch(uid).getURL(), param.toString(), String.class);
+        }
         return httpClient.<String>get(
                 documentPath(uid).addQuery(param.toQuery()).getURL(), String.class);
     }
@@ -214,6 +225,10 @@ private URLBuilder documentPath(String uid) {
         return new URLBuilder().addSubroute("indexes").addSubroute(uid).addSubroute("documents");
     }
 
+    private URLBuilder documentPathWithFetch(String uid) {
+        return documentPath(uid).addSubroute("fetch");
+    }
+
     /** Creates an URLBuilder for the constant route documents */
     private URLBuilder documentPath(String uid, String identifier) {
         return new URLBuilder()

src/main/java/com/meilisearch/sdk/model/DocumentsQuery.java

@@ -4,9 +4,11 @@
 import lombok.Getter;
 import lombok.Setter;
 import lombok.experimental.Accessors;
+import org.json.JSONObject;
 
 /**
- * Data structure of the query parameters of the documents route when retrieving multiple documents
+ * Data structure of the query parameters or request body params of the documents route when
+ * retrieving multiple documents
  *
  * @see <a href="https://www.meilisearch.com/docs/reference/api/documents#query-parameters">API
  *     specification</a>
@@ -18,6 +20,7 @@ public class DocumentsQuery {
     private int offset = -1;
     private int limit = -1;
     private String[] fields;
+    private String[] filter;
 
     public DocumentsQuery() {}
 
@@ -29,4 +32,22 @@ public String toQuery() {
                         .addParameter("fields", this.getFields());
         return urlb.getURL();
     }
+
+    @Override
+    public String toString() {
+        JSONObject jsonObject = new JSONObject();
+        if (offset > -1) {
+            jsonObject.put("offset", offset);
+        }
+        if (limit > -1) {
+            jsonObject.put("limit", limit);
+        }
+        if (fields != null) {
+            jsonObject.put("fields", fields);
+        }
+        if (filter != null) {
+            jsonObject.put("filter", filter);
+        }
+        return jsonObject.toString();
+    }
 }

src/test/java/com/meilisearch/integration/DocumentsTest.java

@@ -3,6 +3,7 @@
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.arrayWithSize;
 import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.hasItemInArray;
 import static org.hamcrest.Matchers.instanceOf;
 import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.not;
@@ -22,6 +23,7 @@
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
+import org.hamcrest.Matchers;
 import org.jetbrains.annotations.NotNull;
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.BeforeEach;
@@ -30,17 +32,18 @@
 
 @Tag("integration")
 public class DocumentsTest extends AbstractIT {
-    @BeforeEach
-    public void initialize() {
-        this.setUp();
-        this.setUpJacksonClient();
-    }
 
     @AfterAll
     static void cleanMeilisearch() {
         cleanup();
     }
 
+    @BeforeEach
+    public void initialize() {
+        this.setUp();
+        this.setUpJacksonClient();
+    }
+
     /** Test Add single document */
     @Test
     public void testAddDocumentsSingle() throws Exception {
@@ -475,6 +478,46 @@ public void testGetDocumentsLimitAndOffsetAndSpecifiedFields() throws Exception
         assertThat(movies[0].getRelease_date(), is(nullValue()));
     }
 
+    /** Test GetDocuments with limit, offset, specified fields and specified filter */
+    @Test
+    void testGetDocumentsLimitAndOffsetAndSpecifiedFieldsAndSpecifiedFilter() throws Exception {
+        String indexUid = "GetDocumentsLimitAndOffsetAndSpecifiedFieldsAndSpecifiedFilter";
+        int limit = 2;
+        int offset = 0;
+        List<String> fields = Arrays.asList("id", "title", "genres");
+        List<String> filters = Arrays.asList("(genres = Horror OR genres = Action)");
+
+        DocumentsQuery query =
+                new DocumentsQuery()
+                        .setLimit(limit)
+                        .setOffset(offset)
+                        .setFields(fields.toArray(new String[0]))
+                        .setFilter(filters.toArray(new String[0]));
+        Index index = client.index(indexUid);
+
+        String[] filterAttributes = {"genres"};
+        index.waitForTask(index.updateFilterableAttributesSettings(filterAttributes).getTaskUid());
+
+        TestData<Movie> testData = this.getTestData(MOVIES_INDEX, Movie.class);
+        TaskInfo task = index.addDocuments(testData.getRaw());
+
+        index.waitForTask(task.getTaskUid());
+        Results<Movie> result = index.getDocuments(query, Movie.class);
+        Movie[] movies = result.getResults();
+
+        assertThat(movies, is(arrayWithSize(limit)));
+        assertThat(movies[0].getId(), is(notNullValue()));
+        assertThat(movies[0].getTitle(), is(notNullValue()));
+        assertThat(movies[0].getGenres(), is(notNullValue()));
+        assertThat(
+                movies[0].getGenres(),
+                hasItemInArray(Matchers.anyOf(equalTo("Horror"), equalTo("Action"))));
+        assertThat(movies[0].getLanguage(), is(nullValue()));
+        assertThat(movies[0].getOverview(), is(nullValue()));
+        assertThat(movies[0].getPoster(), is(nullValue()));
+        assertThat(movies[0].getRelease_date(), is(nullValue()));
+    }
+
     /** Test default GetRawDocuments */
     @Test
     public void testGetRawDocuments() throws Exception {