elastic-muto

0.1.3
Need help reading this?

elastic-muto

https://github.com/booleanapp/elastic-muto

elastic-muto is a library for easliy building elasticsearch queries with simple expressive expressions. It also allows full control over query generation if you want different behavior.

The complete library documentation is present here.

// Import the library
const muto = require('elastic-muto');

const qry = muto.parse('["elasticsearch"] == "awesome" and ["unicorn"] exists');
qry.toJSON();
{
  "bool": {
    "must": [
      {
        "term": { "elasticsearch.keyword": "awesome" }
      },
      {
        "exists": { "field": "unicorn" }
      }
    ]
  }
}

Demo - https://muto.js.org/

The parser was originally developed for parsing filter conditions for the GET score endpoint of Boolean.

parse

src/parse.js

Parses given expression and generates an elastic-builder query object.

parse(expr: (string | Where | Condition), notAnalysedFields: Array?): Object
Parameters
expr ((string | Where | Condition))
notAnalysedFields (Array?)
Returns
Object: elastic-builder BoolQuery object generated by parsing the expression
Example
// Pass expression as string
const qry = muto.parse(
    '["discount"] is false or (["psngr_cnt"] > 81 and ["booking_mode"] contains "Airport")'
)

// OR
// Pass conditions using helper classes
const qry = muto.parse(
    muto.where()
        .or(muto.cn('discount').is(false))
        .or(
            muto.where()
                .and(muto.cn('psngr_cnt', 'gt', 81))
                .and('["booking_mode"] contains "Airport"')
        )
);

qry.toJSON()
{
  "bool": {
    "should": [
      { "term": { "discount": false } },
      {
        "bool": {
          "must": [
            {
              "range": { "psngr_cnt": { "gt": 81 } }
            },
            {
              "match": { "booking_mode": "Airport" }
            }
          ]
        }
      }
    ]
  }
}

Configuration

Custom configuration

The queries generated by elastic-muto can be completely customised. cosmiconfig is used to load the config. A js file, with the file name muto.config.js, will be loaded and used if present.

The file should export a plain object with a function which returns an elastic-builder BoolQuery object. You can define(and override) any of the functions defined in src/query-builder-def.js

Example:

'use strict';

module.exports = {
    // Condition builder for property exists
    exists(key) {
        return bob.existsQuery(`shiny_${key}`);
    },
};

You can also customise the construction of Property Keys. Check out this example which defines a custom config.

Expr Builders

These classes are purely optional helpers for building Where expressions. muto.parse can handle strings just fine.

There are two ways to use the classes for constructing queries:

// Import the library
const muto = require('elastic-muto');

// Use `new` keyword for constructor instances of class
const cn = new muto.Condition('elasticsearch').eq('awesome');
const expr = new muto.Where(cn).and('["unicorn"] exists');

// Or use helper methods which construct the object without need for the `new` keyword
const cn = muto.cn('elasticsearch').eq('awesome'); // or muto.condition
const expr = muto.where(cn).and('["unicorn"] exists')

const qry = muto.parse(expr);
qry.toJSON();
{
  "bool": {
    "must": [
      {
        "term": { "elasticsearch.keyword": "awesome" }
      },
      {
        "exists": { "field": "unicorn" }
      }
    ]
  }
}

Where

src/where.js

Class for building Where expressions

new Where(condition: (Condition | Where | string)?)
Parameters
condition ((Condition | Where | string)?)
Example
const where = muto.where()
    .or(muto.cn('discount').is(false))
    .or(
        muto.where()
            // Pass conditions using helper classes
            .and(muto.cn('psngr_cnt', 'gt', 81))
            // Or a simple string will do
            .and('["booking_mode"] contains "Airport"')
    )
    .build();
'["discount"] is false or (["psngr_cnt"] > 81 and ["booking_mode"] contains "Airport")'
Instance Members
▸ and(condition)
▸ or(condition)
▸ build()
▸ toString()
▸ toJSON()

Condition

src/condition.js

Class for building Property Condition to be used with Where.

new Condition(prop: string?, operator: string?, value: any?)
Parameters
prop (string?) Name of the property key to crate condition against
operator (string?) Operator for the condition. One of is , eq , ne , lt , lte , gt , gte , exists , missing , contain , notcontain
value (any?) Value for the property condition
Example
const condition = muto.cn('psngr_cnt', 'gt', 81);

condition.build()
'["psngr_cnt"]" > 81'
Instance Members
▸ prop(prop)
▸ is(trueOrFalse)
▸ eq(value)
▸ ne(value)
▸ lt(value)
▸ lte(value)
▸ gt(value)
▸ gte(value)
▸ exists()
▸ missing()
▸ contains(value)
▸ notContains(value)
▸ build()
▸ toString()
▸ toJSON()

SyntaxError

src/index.js

Syntax error thrown by PEG.js on trying to parse an invalid expression

SyntaxError

Extends Error