Elastibuild

Elastibuild, a fluent builder for creating ElasticSearch compatible query JSON.

Compatibility

Targets Node 6.x and above.
All constructed queries are compatible with Elasticsearch 5.x and above.

Installing

To utilize elastibuild for node.js install the the npm module:

$ npm install elastibuild

After installing the npm package you can now building queries like so:

const ElastiBuild = require('elastibuild');

Building Queries

You're probably wondering how using Elastbuild makes creating Elasticsearch queries easier. Well, it simply provides a fluent way of constructing Elasticsearch queries.

Let's start with a basic working example:

'use strict';

const ElastiBuild = require('../');

const builder = ElastiBuild.buildQuery();

builder.withMatch('my_field', 'field value');
builder.withSize(100);
builder.withFrom(0);

const query = builder.build();

console.log(query);

This example would produce the following console output:

{
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "my_field": "field value"
          }
        }
      ]
    }
  },
  "size": 100,
  "from": 0
}

API Documentation

ElastiBuild.buildQuery();

Returns a builder object to allow you to fluently build a query.

const builder = ElastiBuild.buildQuery();

ElastiBuild.build();

Build the actual JSON query using the provided parameters. This method returns Elasticsearch compatible JSON.

const builder = ElastiBuild.buildQuery();

// Some building...

// Dump out the Elasticsearch query to console.
console.log(builder.build());

ElastiBuild.withFrom(fromValue);

The from parameter defines the offset from the first result you want to fetch.

Pagination of results can be done by using the withFrom and withSize functionality:

fromValue (Number)

builder.withFrom(1);

ElastiBuild.withSize(sizeValue);

The size parameter allows you to configure the maximum amount of hits to be returned:

Pagination of results can be done by using the withFrom and withSize functionality:

sizeValue (Number)

builder.withSize(10);

ElastiBuild.withMinScore(minScore);

Exclude documents which have a _score less than the minimum specified in min_score:

minScore (Number)

builder.withMinScore(0.5);

ElastiBuild.withMatch(field, values);

Return documents where the field value matches the provided values:

field (String)
values (Array || String)

A single value example:

builder.withMatch('my_field', 'my_value');

An array of values example:

builder.withMatch('my_field_2', ['my_value_1', 'my_value_2']);

An example using options to overide the query type:

builder.withMatch('my_field', { gte: '2021-01-11' }, { subQueryType: 'range' });

ElastiBuild.withMatchAll(value);

Constructs a simple match all query. Matches all documents that match the value provided:

value (Object)

Match all documents example:

builder.withMatchAll({});

Boost parameter example:

builder.withMatchAll({ "boost" : 1.2 });

ElastiBuild.withMustMatch(field, values);

Return documents where the field values must match the provided values:

field (String)
values (Array || String)

A single value example:

builder.withMustMatch('my_field', 'my_value');

An array of values example:

builder.withMustMatch('my_field_2', ['my_value_1', 'my_value_2']);

An example using options to overide the query type:

builder.withMustMatch('my_field', { gte: '2021-01-11' }, { subQueryType: 'range' });

ElastiBuild.withShouldMatch(field, values);

Return documents where the field value should match the provided values:

field (String)
values (Array || String)

A single value example:

builder.withShouldMatch('my_field', 'my_value');

An array of values example:

builder.withShouldMatch('my_field_2', ['my_value_1', 'my_value_2']);

An example using options to overide the query type:

builder.withShouldMatch('my_field', { gte: '2021-01-11' }, { subQueryType: 'range' });

ElastiBuild.withNotMatch(field, values);

Return documents where the field value does not match the provided values:

field (String)
values (Array || String)

A single value example:

builder.withNotMatch('my_field', 'my_value');

An array of values example:

builder.withNotMatch('my_field_2', ['my_value_1', 'my_value_2']);

An example using options to overide the query type:

builder.withNotMatch('my_field', { gte: '2021-01-11' }, { subQueryType: 'range' });

ElastiBuild.withGeoDistance(fields, lat, long, distance);

Return documents where the geo distance matches the provided values, based on a geo_point circle query:

fields (Array)
lat (Number)
long (Number)
distance (String)

ElastiBuild.withGeoCircle(fields, lat, long, radius, relation);

Return documents where the shape or location fields matche a geo_shape circle query, where the default relation is intersects. This default relation matches all documents whose geo_shape indexed location or shape intersects with the submitted circle.

fields (Array)
lat (Number)
long (Number)
radius (String)
relation (String)

The radius value defaults to metres so a unit can be omitted, but other units are supported by ES such as "100km".

The relation value defaults to "intersects", but can also be:

intersects - Matches documents whose location or shape intersects with the circle
within - Matches documents whose location or shape is within the circle
contains - Matches documents whose location or shape contains the circle
disjoint - Matches document whose location or shape has nothing in common with the circle e.g. outside or does not contain

A geo circle example:

builder.withGeoCircle(['my_field1', 'my_field2'], 12.45, 45.65, '1000');

A geo circle example with alternative radius units:

builder.withGeoCircle(['my_field1', 'my_field2'], 12.45, 45.65, '1000km');

A geo circle example with a within relation:

builder.withGeoCircle(['my_field1', 'my_field2'], 12.45, 45.65, '1000', 'within');

ElastiBuild.withGeoLocation(fields, lat, long);

Return documents where the indexed geo_shape fields contain the provided location.

fields (Array)
lat (Number)
long (Number)

A simple geo location example:

builder.withGeoLocation(['my_field1', 'my_field2'], 12.45, 45.65);

ElastiBuild.withTerms(field, values);

Return documents where the field value matches the provided values:

field (String)
values (Array || String)

A single value example:

builder.withTerms('my_field', 'my_value');

ElastiBuild.withQueryString(fields, queryString, options);

Returns documents matching the provided query_string.

fields (Array)
queryString (String)
options (Object)

An example usage is as follows:

builder.withQueryString(['my_field_1', 'my_field_2'], 'foo AND bar', { boost: 100, use_dis_max: true });

ElastiBuild.withMustQueryString(fields, queryString, options);

Returns documents which must match the provided query_string.

fields (Array)
queryString (String)
options (Object)

An example usage is as follows:

builder.withMustQueryString(['my_field_1', 'my_field_2'], 'foo AND bar', { boost: 100, use_dis_max: true });

ElastiBuild.withShouldQueryString(fields, queryString, options);

Returns documents which should match the provided query_string.

fields (Array)
queryString (String)
options (Object)

An example usage is as follows:

builder.withShouldQueryString(['my_field_1', 'my_field_2'], 'foo AND bar', { boost: 100, use_dis_max: true });

ElastiBuild.withMustFilter(field, values);

Applies a must filter to the query.

field (String)
values (Array || String)
options (Object)

A single value example:

builder.withMustFilter('my_field', 'my_value');

An array of values example:

builder.withMustFilter('my_field', ['my_value_1', 'my_value_2']);

An example using options to overide the query type:

builder.withMustFilter('my_field', { gte: '2021-01-11' }, { subQueryType: 'range' });

ElastiBuild.withMustFilterObject(partialQueryObject);

Applies a complex must filter to the query.

partialQueryObject (Object)

A complex nested sub-query example:

builder.withMustFilterObject({
  bool: {
    should: [
      {
        terms: {
          fooProp: [ "barValue" ]
        }
      },
      {
        bool: {
          must_not: {
            match: {
              bazProp: [ "barValue" ]
            }
          }
        }
      }
    ]
  }
});

ElastiBuild.withShouldFilter(field, values);

Applies a should filter to the query.

field (String)
values (Array || String)
options (Object)

A single value example:

builder.withShouldFilter('my_field', 'my_value');

An array of values example:

builder.withShouldFilter('my_field', ['my_value_1', 'my_value_2']);

An example using options to overide the query type:

builder.withShouldFilter('my_field', { gte: '2021-01-11' }, { subQueryType: 'range' });

ElastiBuild.withMustNotFilter(field, values);

Applies a must_not filter to the query.

field (String)
values (Array || String)
options (Object)

A single value example:

builder.withMustNotFilter('my_field', 'my_value');

An array of values example:

builder.withMustNotFilter('my_field', ['my_value_1', 'my_value_2']);

An example using options to overide the query type:

builder.withMustNotFilter('my_field', { gte: '2021-01-11' }, { subQueryType: 'range' });

ElastiBuild.withRange(field, values);

Returns documents within the provided range.

field (String)
range (Object)

A single value example:

builder.withRange("timestamp", { gte: "1970-01-01", lte: "1970-01-01" });

ElastiBuild.withSearchAfter(values);

Sets the search after values for scrolling pages.

values (Array)

builder.withSearchAfter(["first_value", 12345]);

ElastiBuild.withSort(field, order);

Sorts the returned documents using the provided field and direction.

field (String)
order (Object)

builder.withSort("my_field", "desc");

ElastiBuild.withSortUri(uris);

Sorts the returned documents using the provided sort uri.

uris (Array)

Example with a field and order:

builder.withSortUri("my_field:desc");

Example with a field, order and mode:

builder.withSortUri("my_field:desc:min");

ElastiBuild.withSortObject(sortObject);

Sorts the returned documents using the provided sort object (for complex queries).

sortObject (Array/Object)

Example with an array:

builder.withSortObject([{ post_date : {order : "asc"}}]);

Example with an object:

let inputObject = {
      "_script": {
        "type": "number",
        "order": "desc",
        "script": {
          "lang": "eng",
          "inline": "if (doc['version'].value > 0) { doc['version'].value } else { doc['firstcreated'].value }"
        }
      }
    };

builder.withSortObject(inputObject);

This example would produce the following console output:

{
  "query": {
    "bool": {
      "must": {
        "match_all": {}
      }
    }
  },
  "sort": {
    "my_type": {
      "_source": {
        "includes": [
          "path1.*",
          "path2.*"
        ],
        "excludes": [
          "path3.*"
        ]
      }
    }
  }
}

ElastiBuild.withFieldExist(field);

Returns documents containing the provided field.

field (String)

builder.withFieldExist("my_field");

ElastiBuild.withField(field, value);

Allowing further customisation, appends additional field to the query. Returns documents containing the provided field.

field (String)
options (Any)

builder.withField("my_field", {value: 'some_value'});

ElastiBuild.withMoreLikeThis(fields, id, options);

Returns documents that are "like" the provided document id.

fields (Array)
id (String)
options (Object)

builder.withMoreLikeThis(["my_field_1", "my-field-2"], "my-id", { min_term_freq: 4, minimum_should_match: "90%" });

elastibuild

Elastibuild

Compatibility

Installing

Building Queries

API Documentation

ElastiBuild.buildQuery();

ElastiBuild.build();

ElastiBuild.withFrom(fromValue);

ElastiBuild.withSize(sizeValue);

ElastiBuild.withMinScore(minScore);

ElastiBuild.withMatch(field, values);

ElastiBuild.withMatchAll(value);

ElastiBuild.withMustMatch(field, values);

ElastiBuild.withShouldMatch(field, values);

ElastiBuild.withNotMatch(field, values);

ElastiBuild.withGeoDistance(fields, lat, long, distance);

ElastiBuild.withGeoCircle(fields, lat, long, radius, relation);

ElastiBuild.withGeoLocation(fields, lat, long);

ElastiBuild.withTerms(field, values);

ElastiBuild.withQueryString(fields, queryString, options);

ElastiBuild.withMustQueryString(fields, queryString, options);

ElastiBuild.withShouldQueryString(fields, queryString, options);

ElastiBuild.withMustFilter(field, values);

ElastiBuild.withMustFilterObject(partialQueryObject);

ElastiBuild.withShouldFilter(field, values);

ElastiBuild.withMustNotFilter(field, values);

ElastiBuild.withRange(field, values);

ElastiBuild.withSearchAfter(values);

ElastiBuild.withSort(field, order);

ElastiBuild.withSortUri(uris);

ElastiBuild.withSortObject(sortObject);

ElastiBuild.withFieldExist(field);

ElastiBuild.withField(field, value);

ElastiBuild.withMoreLikeThis(fields, id, options);

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads