ESQL (Elasticsearch Query Language)
Elasticsearch is powerful, so is its Query DSL. But Elasticsearch Query DSL's power comes at a cost: complexity. Even the simplest queries can be verbose and difficult to write. ESQL simplifies the construction of Query DSL by compiling queries written in an SQL-like language to Elasticsearch DSL. By only supporting essential features of the Query DSL, ESQL queries can be kept very simple.
The output of ESQL can be used directly as the search argument of elasticsearch-js. However, you may pick different portions should you use another mechanism to connect to Elasticsearch. You can also augment the output however you like. Therefore, you are not locked in to only the features supported by ESQL.
ESQL can be used in both Node and browser environments.
- Scope: specify indices, types and options
- Filter/query group:
- Data types:
- Options can be specified at each level of granularity
- Query parameterization and precompilation
- More to come...
Note: this is an early release of ESQL, expect the language itself and possibly the API to change. Oh yes, and bugs too. Bug reports and pull requests are very welcome.
Install ESQL from NPM or Bower
npm install --save esql
bower install --save esql
esql object in Node
var esql =
esql object in browser (after referencing
var esql = windowesql
Build DSL query
var query = 'ESQL QUERY HERE'var dsl =
var dsl =
var fn = esqlvar dsl =
Consume DSL query with elasticsearch-js
var client = ...client
var dsl =
dsl object is:
dsl object can be fed directly to elasticsearch-js. Or you can just use its
body property as POST data for your own Elasticsearch query mechanism.
ESQL is case insensitive. Spaces and newlines are skipped so you can have as many of them. All clauses are optional although if specified, they must follow this order:
Filter/query groups are made possible with these mappings:
=is mapped to
==is mapped to
!=is mapped to
Range filters and queries are supported with range syntax:
- from..to => from
- from...to => from
tocan be optional
Options can be specified for each filter, match, sort condition or the entire group. Option names and values are not type-checked or validated in anyway whatsoever. This makes the language simple and flexible but requires you to learn about the available options.
from clause to specify indices, types and general query options.
Example 1: index only
Example 2: index and type
from index1 / type1
Example 3: multiple indices and types (including wildcard match)
from [index1, index2] / [type1, type2, moretype*]
Example 4: query options, note that
from option needs escaping
from index / type with ('from': 10, size: 100)
filter clause to create filters.
Example 1: term search
filter tags = 'foo'
Example 2: terms search
filter tags = ['foo', 'bar']
Example 3: multiple filters
filter tags = 'foo', expired = false
match clause to create queries.
Example 1: single match
match name = 'foo' // => match
Example 2: multi-match
match [name, description] = 'foo' // => multi_match
Example 3: multiple matches with options
match name = 'foo' (boost: 2), description = 'foo bar' (minimum_should_match: 1)
sort clause to specify sort fields and directions
sort name asc, age desc