Add example and test for @query with Collection (#2066)

Original Pull Request: #2066

Author: jamesmudd

src/main/asciidoc/reference/elasticsearch-repository-queries.adoc

@@ -312,8 +312,9 @@ Repository methods can be defined to have the following return types for returni
 [[elasticsearch.query-methods.at-query]]
 == Using @Query Annotation
 
-.Declare query at the method using the `@Query` annotation.
+.Declare query on the method using the `@Query` annotation.
 ====
+The arguments passed to the method can be inserted into placeholders in the query string. the placeholders are of the form `?0`, `?1`, `?2` etc. for the first, second, third parameter and so on.
 [source,java]
 ----
 interface BookRepository extends ElasticsearchRepository<Book, String> {
@@ -338,3 +339,24 @@ It will be sent to Easticsearch as value of the query element; if for example th
 }
 ----
 ====
+.`@Query` annotation on a method taking a Collection argument
+====
+A repository method such as
+[source,java]
+----
+@Query("{\"ids\": {\"values\": ?0 }}")
+List<SampleEntity> getByIds(Collection<String> ids);
+----
+would make an https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-ids-query.html[IDs query] to return all the matching documents. So calling the method with a `List` of `["id1", "id2", "id3"]` would produce the query body
+[source,json]
+----
+{
+  "query": {
+    "ids": {
+      "values": ["id1", "id2", "id3"]
+    }
+  }
+}
+----
+====
+

src/test/java/org/springframework/data/elasticsearch/repositories/custommethod/CustomMethodRepositoryIntegrationTests.java

@@ -22,6 +22,7 @@
 import java.lang.Long;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.List;
 import java.util.UUID;
@@ -71,6 +72,7 @@
  * @author Don Wellington
  * @author Peter-Josef Meisch
  * @author Rasmus Faber-Espensen
+ * @author James Mudd
  */
 @SpringIntegrationTest
 public abstract class CustomMethodRepositoryIntegrationTests {
@@ -1648,6 +1650,24 @@ void shouldStreamSearchHitsWithQueryAnnotatedMethod() {
 		assertThat(count).isEqualTo(20);
 	}
 
+	@Test
+	void shouldBeAbleToUseCollectionInQueryAnnotatedMethod() {
+		List<SampleEntity> entities = createSampleEntities("abc", 20);
+		repository.saveAll(entities);
+		List<String> ids = entities.stream()
+				.map(SampleEntity::getId)
+				.limit(7) // Just get subset
+				.collect(Collectors.toList());
+
+		List<SampleEntity> sampleEntities = repository.getByIds(ids);
+
+		assertThat(sampleEntities).hasSize(7);
+
+		List<String> returnedIds = sampleEntities.stream().map(SampleEntity::getId).collect(Collectors.toList());
+		assertThat(returnedIds).containsAll(ids);
+	}
+
+
 	private List<SampleEntity> createSampleEntities(String type, int numberOfEntities) {
 
 		List<SampleEntity> entities = new ArrayList<>();
@@ -1881,6 +1901,9 @@ public interface SampleCustomMethodRepository extends ElasticsearchRepository<Sa
 
 		@CountQuery("{\"bool\" : {\"must\" : {\"term\" : {\"type\" : \"?0\"}}}}")
 		long countWithQueryByType(String type);
+
+		@Query("{\"ids\" : {\"values\" : ?0 }}")
+		List<SampleEntity> getByIds(Collection<String> ids);
 	}
 
 	/**