fast-elasticsearch-query-builder

A fast way to build ElasticSearch query dsl string, even without writing implement code.

Read this in other languages: English, 简体中文

Brief

You can integrate it in your project with these steps:

Complete the search criteria DTO MySearchCirteria（add correct @annotation on the field）

public class MySearchCirteria {
    @Must
    @Match
    private String name;
}

Complete the query builder class MyQueryBuilder extending the BaseQueryBuilder, with specifing MySearchCirteria as the generics class
```
public class MyQueryBuilder extends BaseQueryBuilder<MySearchCriteria> {
}
```

Invoke MyQueryBuilder#build to build the query string

public class TestQueryBuilder {
    public static void main(String[] args) {
        // instance MyQueryBuilder
        MyQueryBuilder myQueryBuilder = new MyQueryBuilder();
        // instance MySearchCriteria
        MySearchCriteria mySearchCriteria = new MySearchCriteria();
        mySearchCriteria.setName("jack");
        // invoke build method
        String dsl = myQueryBuilder.build(mySearchCriteria);
        // enjoy it!
        System.out.println(dsl);
    }
}

result

{
  "from": 0,
  "size": 20,
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "name": {
              "query": "jack",
              "operator": "OR",
              "prefix_length": 0,
              "max_expansions": 50,
              "fuzzy_transpositions": true,
              "lenient": false,
              "zero_terms_query": "NONE",
              "auto_generate_synonyms_phrase_query": true,
              "boost": 1
            }
          }
        }
      ],
      "adjust_pure_negative": true,
      "boost": 1
    }
  }
}

fast-elasticsearch-query-builder generates dsl based on org.elasticsearch-elasticsearch-6.3.0

Instruction

Annotation Instruction

fast-elasticsearch-query-builder privides two kinds of annotation to build query string: Function Annotation and Query Annotation.

Function Annotation

To set query properties.

Annotation	Field Type	Function	Parameters
@Higilighters	Collection<String>	set highlight	type: the highlight type, default to "fvh"
@PageNo	Integer	set from	-
@PageSize	Integer	set size	-
@Sort	List<Sortable>	set sort, you should implement Sortable interface	-
@Source	Collection<String>	set _source.includes	-
@TermsAggregation	Integer	set terms aggregation	name: aggregation name field: aggregation field maxSize: max value of the field order: buckets' order executionHint: mechanisms of aggregations execution

from + size <= max_result_window

Query Annotation

To build query clause. It includes Query Context Annotation and Query Type Annotation, and they must be used together.

Query Context Annotation

Decides how Query Type Annotation affect the hits (just filter the hits or affect the score).

Annotation	Function
@Must	set must query
@MustNot	set must_not query
@Should	set should query
@Filter	set filter query
@Or	will be converted to should clause in filter query , like or in sql
@OrNot	will be converted to should.mustNot clause in filter query 中的 should.mustNot, like or not in sql

@Or and @OrNot are not standard query context in Elasticsearch

Query Type Annotation

Decides the behavior of search.

Annotation	Field Type	Function	Parameters
@Match	String	set match query	operator: control boolean clause (or / and)
@Term	-	set term query	-
@Terms	Collection<?>	set terms query	-
@Range	Number	set range query	type: boundary type (from / to) includedBoundary: whether includes boundary
@Exists	Boolean	set exists query	-
@Wildcard	String	set wildcard query	-

The annotations above contaion fieldName parameter, implicate the index field name using in building query, default to the field name that the annotation works on.

Method Instruction

AbstractQueryBuilder#build flow chart like this:

You can custom your query in the abstract method.

For example，you can custon filter query like this:

@Override
protected void customFilterQueries(List<QueryBuilder> filterQueries, 
                                   StuSearchCriteria stuSearchCriteria) {
    // custom query that generated not through annotation
    Optional.ofNullable(stuSearchCriteria.getCustomField())
        .ifPresent(t -> filterQueries.add(termQuery("customFilterField", t)));
}

You can see more detail usage in the demo under the test/ directory.

reckcn / fast-elasticsearch-query-builder