DATAES-758 - Fix documentation for @Query annotation.

Original PR: #402

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

@@ -8,7 +8,7 @@ The Elasticsearch module supports all basic query building feature as string que
 
 === Declared queries
 
-Deriving the query from the method name is not always sufficient and/or may result in unreadable method names. In this case one might make either use of `@Query` annotation (see <<elasticsearch.query-methods.at-query>> ).
+Deriving the query from the method name is not always sufficient and/or may result in unreadable method names. In this case one might make use of the `@Query` annotation (see <<elasticsearch.query-methods.at-query>> ).
 
 [[elasticsearch.query-methods.criterions]]
 == Query creation
@@ -29,13 +29,15 @@ The method name above will be translated into the following Elasticsearch json q
 
 [source]
 ----
-{ "bool" :
+{
-    { "must" :
+    "query": {
-        [
+        "bool" : {
-            { "field" : {"name" : "?"} },
+            "must" : [
-            { "field" : {"price" : "?"} }
+                { "query_string" : { "query" : "?", "fields" : [ "name" ] } },
+                { "query_string" : { "query" : "?", "fields" : [ "price" ] } }
             ]
         }
+    }
 }
 ----
 
@@ -48,80 +50,184 @@ A list of supported keywords for Elasticsearch is shown below.
 | Sample
 | Elasticsearch Query String| `And`
 | `findByNameAndPrice`
-| `{"bool" : {"must" : [ {"field" : {"name" : "?"}},
+| `{ "query" : {
-                                        {"field" : {"price" : "?"}} ]}}`
+"bool" : {
+"must" : [
+      { "query_string" : { "query" : "?", "fields" : [ "name" ] } },
+      { "query_string" : { "query" : "?", "fields" : [ "price" ] } }
+    ]
+  }
+}}`
 
 | `Or`
 | `findByNameOrPrice`
-| `{"bool" : {"should" : [ {"field" : {"name" : "?"}},
+| `{ "query" : {
-                                        {"field" : {"price" : "?"}} ]}}`
+"bool" : {
+"should" : [
+      { "query_string" : { "query" : "?", "fields" : [ "name" ] } },
+      { "query_string" : { "query" : "?", "fields" : [ "price" ] } }
+    ]
+  }
+}}`
 
 | `Is`
 | `findByName`
-| `{"bool" : {"must" : {"field" : {"name" : "?"}}}}`
+| `{ "query" : {
+"bool" : {
+"must" : [
+      { "query_string" : { "query" : "?", "fields" : [ "name" ] } }
+    ]
+  }
+}}`
 
 | `Not`
 | `findByNameNot`
-| `{"bool" : {"must_not" : {"field" : {"name" : "?"}}}}`
+| `{ "query" : {
+"bool" : {
+"must_not" : [
+      { "query_string" : { "query" : "?", "fields" : [ "name" ] } }
+    ]
+  }
+}}`
 
 | `Between`
 | `findByPriceBetween`
-| `{"bool" : {"must" : {"range" : {"price" : {"from" :
+| `{ "query" : {
-                                        ?,"to" : ?,"include_lower" : true,"include_upper" : true}}}}}`
+"bool" : {
+"must" : [
+    {"range" : {"price" : {"from" : ?, "to" : ?, "include_lower" : true, "include_upper" : true } } }
+    ]
+  }
+}}`
+
+| `LessThan`
+| `findByPriceLessThan`
+| `{ "query" : {
+"bool" : {
+"must" : [
+    {"range" : {"price" : {"from" : null, "to" : ?, "include_lower" : true, "include_upper" : false } } }
+    ]
+  }
+}}`
 
 | `LessThanEqual`
-| `findByPriceLessThan`
+| `findByPriceLessThanEqual`
-| `{"bool" : {"must" : {"range" : {"price" : {"from" :
+| `{ "query" : {
-                                        null,"to" : ?,"include_lower" : true,"include_upper" :
+"bool" : {
-                                        true}}}}}`
+"must" : [
+    {"range" : {"price" : {"from" : null, "to" : ?, "include_lower" : true, "include_upper" : true } } }
+    ]
+  }
+}}`
+
+| `GreaterThan`
+| `findByPriceGreaterThan`
+| `{ "query" : {
+"bool" : {
+"must" : [
+    {"range" : {"price" : {"from" : ?, "to" : null, "include_lower" : false, "include_upper" : true } } }
+    ]
+  }
+}}`
+
 
 | `GreaterThanEqual`
 | `findByPriceGreaterThan`
-| `{"bool" : {"must" : {"range" : {"price" : {"from" :
+| `{ "query" : {
-                                        ?,"to" : null,"include_lower" : true,"include_upper" :
+"bool" : {
-                                        true}}}}}`
+"must" : [
+    {"range" : {"price" : {"from" : ?, "to" : null, "include_lower" : true, "include_upper" : true } } }
+    ]
+  }
+}}`
 
 | `Before`
 | `findByPriceBefore`
-| `{"bool" : {"must" : {"range" : {"price" : {"from" :
+| `{ "query" : {
-                                        null,"to" : ?,"include_lower" : true,"include_upper" :
+"bool" : {
-                                        true}}}}}`
+"must" : [
+    {"range" : {"price" : {"from" : null, "to" : ?, "include_lower" : true, "include_upper" : true } } }
+    ]
+  }
+}}`
 
 | `After`
 | `findByPriceAfter`
-| `{"bool" : {"must" : {"range" : {"price" : {"from" :
+| `{ "query" : {
-                                        ?,"to" : null,"include_lower" : true,"include_upper" :
+"bool" : {
-                                        true}}}}}`
+"must" : [
+    {"range" : {"price" : {"from" : ?, "to" : null, "include_lower" : true, "include_upper" : true } } }
+    ]
+  }
+}}`
 
 | `Like`
 | `findByNameLike`
-| `{"bool" : {"must" : {"field" : {"name" : {"query" :
+| `{ "query" : {
-                                        "?*","analyze_wildcard" : true}}}}}`
+"bool" : {
+"must" : [
+      { "query_string" : { "query" : "?*", "fields" : [ "name" ] }, "analyze_wildcard": true }
+    ]
+  }
+}}`
 
 | `StartingWith`
 | `findByNameStartingWith`
-| `{"bool" : {"must" : {"field" : {"name" : {"query" :
+| `{ "query" : {
-                                        "?*","analyze_wildcard" : true}}}}}`
+"bool" : {
+"must" : [
+      { "query_string" : { "query" : "?*", "fields" : [ "name" ] }, "analyze_wildcard": true }
+    ]
+  }
+}}`
 
 | `EndingWith`
 | `findByNameEndingWith`
-| `{"bool" : {"must" : {"field" : {"name" : {"query" :
+| `{ "query" : {
-                                        "*?","analyze_wildcard" : true}}}}}`
+"bool" : {
+"must" : [
+      { "query_string" : { "query" : "*?", "fields" : [ "name" ] }, "analyze_wildcard": true }
+    ]
+  }
+}}`
 
 | `Contains/Containing`
 | `findByNameContaining`
-| `{"bool" : {"must" : {"field" : {"name" : {"query" :
+| `{ "query" : {
-                                        "*?*","analyze_wildcard" : true}}}}}`
+"bool" : {
+"must" : [
+      { "query_string" : { "query" : "\*?*", "fields" : [ "name" ] }, "analyze_wildcard": true }
+    ]
+  }
+}}`
 
 | `In`
 | `findByNameIn(Collection<String>names)`
-| `{"bool" : {"must" : {"bool" : {"should" : [ {"field" :
+| `{ "query" : {
-                                        {"name" : "?"}}, {"field" : {"name" : "?"}} ]}}}}`
+"bool" : {
+"must" : [
+      {"bool" : {"must" : [
+            {"terms" : {"name" : ["?","?"]}}
+          ]
+        }
+      }
+    ]
+  }
+}}`
 
 | `NotIn`
 | `findByNameNotIn(Collection<String>names)`
-| `{"bool" : {"must_not" : {"bool" : {"should" : {"field" :
+| `{ "query" : {
-                                        {"name" : "?"}}}}}}`
+"bool" : {
+"must" : [
+      {"bool" : {"must_not" : [
+            {"terms" : {"name" : ["?","?"]}}
+          ]
+        }
+      }
+    ]
+  }
+}}`
 
 | `Near`
 | `findByStoreNear`
@@ -129,18 +235,45 @@ A list of supported keywords for Elasticsearch is shown below.
 
 | `True`
 | `findByAvailableTrue`
-| `{"bool" : {"must" : {"field" : {"available" : true}}}}`
+| `{ "query" : {
+"bool" : {
+"must" : [
+      { "query_string" : { "query" : "true", "fields" : [ "available" ] } }
+    ]
+  }
+}}`
 
 | `False`
 | `findByAvailableFalse`
-| `{"bool" : {"must" : {"field" : {"available" : false}}}}`
+| `{ "query" : {
+"bool" : {
+"must" : [
+      { "query_string" : { "query" : "false", "fields" : [ "available" ] } }
+    ]
+  }
+}}`
 
 | `OrderBy`
 | `findByAvailableTrueOrderByNameDesc`
-| `{"sort" : [{ "name" : {"order" : "desc"} }],"bool" :
+| `{ "query" : {
-                                        {"must" : {"field" : {"available" : true}}}}`
+"bool" : {
+"must" : [
+      { "query_string" : { "query" : "true", "fields" : [ "available" ] } }
+    ]
+  }
+}, "sort":[{"name":{"order":"desc"}}]
+}`
+
 |===
 
+== Method return types
+
+Repository methods can be defined to have the following return types for returning multiple Elements:
+
+* `List<T>`
+* `Stream<T>`
+* `AggregatedPage<T>`
+
 [[elasticsearch.query-methods.at-query]]
 == Using @Query Annotation
 
@@ -149,8 +282,21 @@ A list of supported keywords for Elasticsearch is shown below.
 [source,java]
 ----
 interface BookRepository extends ElasticsearchRepository<Book, String> {
-    @Query("{\"bool\" : {\"must\" : {\"field\" : {\"name\" : \"?0\"}}}}")
+    @Query("{\"match\": {\"name\": {\"query\": \"?0\"}}}")
     Page<Book> findByName(String name,Pageable pageable);
 }
 ----
+The String that is set as the annotation argument must be a valid Elasticsearch JSON query. It will be sent to Easticsearch as value of the query element; if for example the function is called with the parameter _John_, it would produce the following query body:
+[source,json]
+----
+{
+  "query": {
+    "match": {
+      "name": {
+        "query": "John"
+      }
+    }
+  }
+}
+----
 ====