mikalv / pes

A pluggable impressive elastic query DSL builder for Elasticsearch (es)

An elastic query DSL builder for Elasticsearch

Pes, formally being part of the Elasticsearch Community, is a pluggable impressive elastic query DSL builder for elasticsearch (es). It aims to be a part of new monitoring/sense tools or existing ones. Thus, in the absence of constructing inline queries in es, the complexity of writing a query DSL can be minimized in the light of this extension. Pes basically helps in building time-saving queries with regards to the available bunch of aliases, so that even you need to make complex and complicated queries, Pes gives you fully controllable query language to boost your queries.

As mentioned, Pes supports several abbreviations. When these handy expressions are in action with a few punctuations, Pes builds the corresponding structured query blocks along with pairs that elasticsearch provides. Additionally, Pes contains two functions to handle output as string or array.

How it works

This extension is eligible to be integrated into any web-based editor which enables us to contruct queries. To do so, you can get it by either cloning:

$ git clone https://github.com/kodcu/pes

or using bower:

$ bower install pes

Either way comes with twofold: first you get the source code, secondly you can easily test all the available expressions after installing the test dependency called QUnit framework via bower install.

After linking the library (pes.js or pes.pack.js) on a web page, you can use the existing two functions namely queriesToArray and queriesToString to manipulate the output:

<script src="/path/to/pes.pack.js"></script>
or
<script src="/path/to/pes.js"></script>
..
<script>

var outputStr = pes.queriesToString('q[m]');

var outputArray = pes.queriesToArray('q[mpp]'));

console.log(outputStr);

console.log(outputArray);
</script>

Two console logs return as follows:

"query": {
  "match": {
    "FIELD": "TEXT"
  }
}

["\"query\": {",
 "  \"match_phrase_prefix\": {",
 "    \"FIELD\": \"TEXT\"",
 "  }",
 "}"]

Examples

Pes includes query (abbr. q), match (m), match_phrase (mp), match_phrase_prefix (mpp), match_all (ma) ,multi_match (mm), dis_max (dm), bool (b, bool), and range (range) queries for now. For more details, please look at the test cases located in the test folder. This is indeed useful to digest all the existing expressions Pes provides.

Nested query blocks along with key:value pairs can be easily created in one line. What is important to note is that, you can override the default values of members such as size, explain, _source, zero_terms_query, operator and suchlike, using key{new_value} syntax. the new_value can be string, number, array, true, false, or null. You will see this behavior in the 3rd and 4th examples.

Next to this, if you want to use more than one types into to match (m alias) and match_phrase_prefix (mpp alias) queries rather than using their default behaviour, :p comes into play to provide nested types like m:p[qy], mpp:p[qy,op,me]. They will be generated as follows:

"match": {
  "FIELD": {
    "query": "TEXT"
  }
}


"match_phrase_prefix": {
  "FIELD": {
    "query": "TEXT",
    "operator": "and",
    "max_expansions": 10
  }
}

// rather the default characteristics of the two queries ([m | mpp]):

"match": {
  "FIELD": "TEXT"
}

"match_phrase_prefix": {
  "FIELD": "TEXT"
}

Note that, [o] and [a] can be used to create an empty object and array respectively. The 2nd and 3rd examples illustrate how to use [o] while writing a pes query.

1. Example

{
    q[mpp:p[query]]
}

{
    "query": {
      "match_phrase_prefix": {
        "FIELD": {
          "query": "TEXT"
        }
      }
    }
}

2. Example

{
   q[b[shouldN[o[m],o[m]]]]
}

{
  "query": {
    "bool": {
      "should": [
        {
          "match": {
            "FIELD": "TEXT"
          }
        },
        {
          "match": {
            "FIELD": "TEXT"
          }
        }
      ]
    }
  }
}

3. Example

{
    q[bool[mustN[o[range[gte{1}]]],shouldN[o[range[gt{1955}]]]]]
}

{
  "query": {
    "bool": {
      "must": [
        {
          "range": {
            "FIELD": {
              "gte": 1
            }
          }
        }
      ],
      "should": [
        {
          "range": {
            "FIELD": {
              "gt": 1955
            }
          }
        }
      ]
    }
  }
}

4. Example

{
    q[m:p[qy{"hi elastic query"},op{"or"},ztq]],sz,bst,src{["_id","surname"]},exp{true}
}

{
  "query": {
    "match": {
      "FIELD": {
        "query": "hi elastic query",
        "operator": "or",
        "zero_terms_query": "none"
      }
    }
  },
  "size": 10,
  "boost": 1,
  "_source": [
    "_id",
    "surname"
  ],
  "explain": true
}

Contributing

This extension just published, so all ideas are always welcome and valuable. Feel free to open an issue and make a PR.

License

Pes is released under the MIT License. See LICENSE file for details.