A simple, safe, ElasticSearch Query compiler
npm install filtresFiltrES (Filtrex for ElasticSearch)
=======
Pronounced like Fortress
A simple, safe, ElasticSearch query engine, allowing you or your end-users to enter arbitrary expressions without p0wning you or learning the ElasticSearch Query language.
```python``
(height <= 73 or (favorites.color == "green" and height != 73)) and firstname ~= "o.+"
Why?
----
There are many cases where you want a user to be able enter an arbitrary expression through a user interface or simply want to avoid ElasticSearch's powerful, but complicated query language.
Sure, you could do that with ElasticSearch's "script" filter, but I'm sure I don't have to tell you how stupid that would be. It opens up many potential security issues.
FiltrES defines a really simple expression language that should be familiar to anyone who's ever used a spreadsheet and compile it into an ElasticSearch query at runtime.
Features
--------
* Simple! End user expression language looks like this transactions <= 5 and profit > 20.5
* Fast! Expressions get compiled into native ElasticSearch queries, offering the same performance as if it had been hand coded. e.g.
* Safe! Expressions cannot escape the sandbox client-side or inside of ElasticSearch.
* Predictable! Because users can't define loops or recursive functions, you know you won't be left hanging.
Get it
------
* DOWNLOAD filtres.js or filtres.min.js
10 second tutorial (using ElasticSearchClient)
------------------
``javascript
// A search filter
var expression = 'transactions <= 5 and profit > 20.5';
// Compile expression to executable function
var myQuery = filtres.compile(expression);
// Execute query
esc.search("filtres", "accounts", myQuery, function (err, accounts) {
...
});
``
Expressions
-----------
There are only 2 types: numbers and strings. Numbers may be floating point or integers. Boolean logic is applied on the truthy value of values (e.g. any non-zero number is true, any non-empty string is true, otherwise false).
Values | Description
--- | ---
43, -1.234 | Numbers
"hello" | String
foo, a.b.c | External data variable defined by application (may be numbers or strings)
Comparisons | Description
--- | ---
x == y | Equals
x != y | Not equals
x ~= "y" | Matched to y evaluated as a RegExp
x ~!= "y" | Not matched to y evaluated as a RegExp
x < y | Less than
x <= y | Less than or equal to
x > y | Greater than
x >= y | Greater than or equal to
Boolean logic | Description
--- | ---
x or y | Boolean or
x and y | Boolean and
not x | Boolean not
( x ) | Explicit operator precedence
Operator precedence follows that of any sane language.
FAQ
---
Why the name?
Because it was originally built for FILTeR EXpressions then ported to ElasticSearch (i.e. ES).
What's Jison?
Jison is bundled with FiltrES - it's a JavaScript parser generator that does the underlying hard work of understanding the expression. It's based on Flex and Bison.
License?
Tests?
What happens if the expression is malformed?
Calling filters.compile()` with a malformed expression will throw an exception. You can catch that and display feedback to the user. A good UI pattern is to attempt to compile on each keystroke and continuously indicate whether the expression is valid.
And follow @abeisgreat (FiltrES) and follow @joewalnes (Filtrex)!