|
For the latest stable version, please use Spring Data Elasticsearch 5.4.0! |
Query methods
Query lookup strategies
The Elasticsearch module supports all basic query building feature as string queries, native search queries, criteria based queries or have it being derived from the method name.
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 use of the @Query annotation (see Using @Query Annotation ).
Query creation
Generally the query creation mechanism for Elasticsearch works as described in Defining Query Methods. Here’s a short example of what a Elasticsearch query method translates into:
interface BookRepository extends Repository<Book, String> {
List<Book> findByNameAndPrice(String name, Integer price);
}The method name above will be translated into the following Elasticsearch json query
{
"query": {
"bool" : {
"must" : [
{ "query_string" : { "query" : "?", "fields" : [ "name" ] } },
{ "query_string" : { "query" : "?", "fields" : [ "price" ] } }
]
}
}
}A list of supported keywords for Elasticsearch is shown below.
| Keyword | Sample | Elasticsearch Query String |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Methods names to build Geo-shape queries taking GeoJson parameters are not supported.
Use ElasticsearchOperations with CriteriaQuery in a custom repository implementation if you need to have such a function in a repository.
|
Method return types
Repository methods can be defined to have the following return types for returning multiple Elements:
-
List<T> -
Stream<T> -
SearchHits<T> -
List<SearchHit<T>> -
Stream<SearchHit<T>> -
SearchPage<T>
Using @Query Annotation
@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.
interface BookRepository extends ElasticsearchRepository<Book, String> {
@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:
{
"query": {
"match": {
"name": {
"query": "John"
}
}
}
}@Query annotation on a method taking a Collection argumentA repository method such as
@Query("{\"ids\": {\"values\": ?0 }}")
List<SampleEntity> getByIds(Collection<String> ids);would make an IDs query to return all the matching documents. So calling the method with a List of ["id1", "id2", "id3"] would produce the query body
{
"query": {
"ids": {
"values": ["id1", "id2", "id3"]
}
}
}Using SpEL Expressions
@Query annotation with SpEL expression.SpEL expression is also supported when defining query in @Query.
interface BookRepository extends ElasticsearchRepository<Book, String> {
@Query("""
{
"bool":{
"must":[
{
"term":{
"name": "#{#name}"
}
}
]
}
}
""")
Page<Book> findByName(String name, Pageable pageable);
}If for example the function is called with the parameter John, it would produce the following query body:
{
"bool":{
"must":[
{
"term":{
"name": "John"
}
}
]
}
}Supposing that we have the following class as query parameter type:
public record QueryParameter(String value) {
}It’s easy to access the parameter by # symbol, then reference the property value with a simple .:
interface BookRepository extends ElasticsearchRepository<Book, String> {
@Query("""
{
"bool":{
"must":[
{
"term":{
"name": "#{#parameter.value}"
}
}
]
}
}
""")
Page<Book> findByName(QueryParameter parameter, Pageable pageable);
}We can pass new QueryParameter("John") as the parameter now, and it will produce the same query string as above.
Bean property is also supported to access. Given that there is a bean named queryParameter of type QueryParameter, we can access the bean with symbol @ rather than #, and there is no need to declare a parameter of type QueryParameter in the query method:
interface BookRepository extends ElasticsearchRepository<Book, String> {
@Query("""
{
"bool":{
"must":[
{
"term":{
"name": "#{@queryParameter.value}"
}
}
]
}
}
""")
Page<Book> findByName(Pageable pageable);
}Collection param.Collection parameter is also supported and is as easy to use as normal String, such as the following terms query:
interface BookRepository extends ElasticsearchRepository<Book, String> {
@Query("""
{
"bool":{
"must":[
{
"terms":{
"name": #{#names}
}
}
]
}
}
""")
Page<Book> findByName(Collection<String> names, Pageable pageable);
}| collection values should not be quoted when declaring the elasticsearch json query. |
A collection of names like List.of("name1", "name2") will produce the following terms query:
{
"bool":{
"must":[
{
"terms":{
"name": ["name1", "name2"]
}
}
]
}
}Collection param.SpEL Collection Projection is convenient to use when values in the Collection parameter is not plain String:
interface BookRepository extends ElasticsearchRepository<Book, String> {
@Query("""
{
"bool":{
"must":[
{
"terms":{
"name": #{#parameters.![value]}
}
}
]
}
}
""")
Page<Book> findByName(Collection<QueryParameter> parameters, Pageable pageable);
}This will extract all the value property values as a new Collection from QueryParameter collection, thus takes the same effect as above.
@ParamWhen accessing the parameter by SpEL, it’s also useful to alter the parameter name to another one by @Param annotation in Sping Data:
interface BookRepository extends ElasticsearchRepository<Book, String> {
@Query("""
{
"bool":{
"must":[
{
"terms":{
"name": #{#another.![value]}
}
}
]
}
}
""")
Page<Book> findByName(@Param("another") Collection<QueryParameter> parameters, Pageable pageable);
}