Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including filtres with all npm packages installed. Try it out:

var filtres = require("filtres")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

filtres v0.1.4

A simple, safe, ElasticSearch Query compiler

FiltrES (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.

(height <= 73 or (favorites.color == "green" and height != 73)) and firstname ~= "o.+"


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.


  • 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. {"filtered" : {"filter" : {"bool" : {"must" : {"term" : { "tag" : "wow" }}, "must_not" : {"range" : {"age" : { "from" : 10, "to" : 20 }}}
  • 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

10 second tutorial (using ElasticSearchClient)

// A search filter
var expression = 'transactions <= 5 and profit > 20.5';

// Compile expression to executable function
var myQuery = filtres.compile(expression);

// Execute query"filtres", "accounts", myQuery, function (err, accounts) {


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).

43, -1.234Numbers
foo, a.b.cExternal data variable defined by application (may be numbers or strings)
x == yEquals
x != yNot equals
x ~= "y"Matched to y evaluated as a RegExp
x ~!= "y"Not matched to y evaluated as a RegExp
x < yLess than
x <= yLess than or equal to
x > yGreater than
x >= yGreater than or equal to
Boolean logicDescription
x or yBoolean or
x and yBoolean and
not xBoolean not
( x )Explicit operator precedence

Operator precedence follows that of any sane language.


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.





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)!


RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free