Bird’s Eye View of the ElasticSearch Query DSL

i’ve copied the whole post into a gist so that you can simply clone, copy and paste the important stuff and even could contribute easily.

several times per month there are questions regarding the query structure on the elasticsearch user group .

although there are good docs explaining this in depth, i think a bird's eye view of the query dsl is necessary to understand what is written there. there is even some good external documentation available. and there were attempts to define a schema but nevertheless i’ll add my 2 cents here. i assume you set up your elasticsearch instance correctly and on the local machine filled with exactly those 3 articles .

now we can query elasticsearch as it is done there. keep in mind to use the keyword analyzer for tags!

curl -x post “http://localhost:9200/articles/_search?pretty=true” -d ‘
{“query” : { “query_string” : {“query” : “t*”} },
“facets” : {
“tags” : { “terms” : {“field” : “tags”} }
}}’

but when you now look into the query dsl docs you’ll only find the query part

{“query_string” : {
“default_field” : “content”,
“query” : “this and that or thus”
}}

and this query part can be replaced by your favourite query. be it a filtered , term , a boolean or whatever query.

so what is the main structure of a query? roughly it is:

curl -x post “http://localhost:9200/articles/_search?pretty=true” -d ‘
{“from”: 0,
“size”: 10,
“query” : query_json,
filter_json,
facet_json,
sort_json
}’

keep in mind that the filter_json only applies to the query not to the facets. read on for learning how to do this. and now a short example of how this nicely maps to the java api:

searchrequestbuilder srb = client.preparesearch(“your_index”);
srb.setquery(querybuilders.querystring(“title:test”));
srb.addsort(“tags”, sortorder.asc);
srb.addfacet(facetbuilders.termsfacet(“tags”));

// etc -> use your ide autocompletion function

if you install my hack for elasticsearch head you can formulate the above query separation directly in your browser/in javascript. e.g.:

q ={ match_all:{} };
req = { query:q }

a more detailed query structure is as follows – you could easily obtain it via java api, from the navigational elements from the official docs or directly from the source :

curl -x post “http://localhost:9200/articles/_search?pretty=true” -d ‘
{“query” : query_json,
“filter” : filter_json,
“from”: 0,
“size”: 10,
“sort” : sort_array,
“highlight” : highlight_json,
“fields” : ["tags", "title"],
“script_fields”: script_fields_json,
“preference”: “_local”,
“facets” : facet_json,
“search_type”: “query_then_fetch”,
“timeout”: -1,
“version”: true,
“explain”: true,
“min_score”: 0.5,
“partial_fields”: partial_fields_json,
“stats” : ["group1", "group2"]
}’

let us dig into a simple query with some filters and facets:

curl -xget ‘http://localhost:9200/articles/_search?pretty=true’ -d ‘
{“query”: {
“filtered” : {
“query” : { “match_all” : {} },
“filter” : {“term” : { “tags” : “bar” }}
}},
“facets” : {
“tags” : { “terms” : {“field” : “tags”} }
}}’

you should get 2 out of the 3 articles and the filter directly applies on the facets as well. if you don’t want that then put the filter part under the query:

curl -xget ‘http://localhost:9200/articles/_search?pretty=true’ -d ‘
{“query” : { “match_all” : {} },
“filter” : {“term” : { “tags” : “bar” }},
“facets” : {
“tags” : { “terms” : {“field” : “tags”} }
}}’

and how can i only filter on the facets? you’ll need facet_filter:

curl -xget ‘http://localhost:9200/articles/_search?pretty=true’ -d ‘
{“query” : { “match_all” : {} },
“facets” : {
“mytags” : {
“terms” : {“field” : “tags”},
“facet_filter” : {“term” : { “tags” : “bar”}}
}
}}’

you’ll get 3 documents with filtered facets.

hope this posts clarifies things a bit and reduces your trouble. i’ll update the post according to your comments/suggestions. let me know if you want something explained which is query-dsl specific for all the other questions there is the user group .