http://bodybuilder.js.org

https://github.com/danpaz/bodybuilder

Bodybuilder is a small library that makes elasticsearch queries easier to write, read, and maintain 💪. The whole public api is documented here, but how about a simple example to get started:

bodybuilder()
  .query('match', 'message', 'this is a test')
  .build()

// results in:
{
  query: {
    match: {
      message: 'this is a test'
    }
  }
}

You can chain multiple methods together to build up a more complex query.

bodybuilder()
  .query('match', 'message', 'this is a test')
  .filter('term', 'user', 'kimchy')
  .notFilter('term', 'user', 'cassie')
  .aggregation('terms', 'user')
  .build()

For nested sub-queries or sub-aggregations, pass a function as the last argument and build the nested clause in the body of that function. Note that you must return the builder object in the nested function. For example:

bodybuilder()
  .query('nested', 'path', 'obj1', (q) => {
    return q.query('match', 'obj1.color', 'blue')
  })
  .build()

The entire elasticsearch query DSL is available using the bodybuilder api. There are many more examples in the docs as well as in the tests.

Set a sort direction on a given field.

bodybuilder()
  .sort('timestamp', 'desc')
  .build()

You can sort multiple fields at once

bodybuilder()
 .sort([
   {"categories": "desc"},
   {"content": "asc"}
 ])
  .build()

Geo Distance sorting is also supported & it's the only sort type that allows for duplicates

bodyBuilder().sort([
    {
      _geo_distance: {
        'a.pin.location': [-70, 40],
        order: 'asc',
        unit: 'km',
        mode: 'min',
        distance_type: 'sloppy_arc'
      }
    },
    {
      _geo_distance: {
        'b.pin.location': [-140, 80],
        order: 'asc',
        unit: 'km',
        mode: 'min',
        distance_type: 'sloppy_arc'
      }
    }
  ])
  .sort([
    { timestamp: 'desc' },
    { content: 'desc' },
    { content: 'asc' },
   {"price" : {"order" : "asc", "mode" : "avg"}}
  ])
.build()

Set a from offset value, for paginating a query.

Set a size value for maximum results to return.

Set any key-value on the elasticsearch body.

Collect all queries, filters, and aggregations and build the entire elasticsearch query.

Returns a cloned instance of bodybuilder

const bodyA = bodybuilder().size(3);
const bodyB = bodyA.clone().from(2); // Doesn't affect bodyA
// bodyA: { size: 3 }
// bodyB: { size: 3, from: 2 }

Add a query clause to the query body.

bodybuilder()
  .query('match_all')
  .build()

bodybuilder()
  .query('match_all', { boost: 1.2 })
  .build()

bodybuilder()
  .query('match', 'message', 'this is a test')
  .build()

bodybuilder()
  .query('terms', 'user', ['kimchy', 'elastic'])
  .build()

bodybuilder()
  .query('nested', { path: 'obj1', score_mode: 'avg' }, (q) => {
    return q
      .query('match', 'obj1.name', 'blue')
      .query('range', 'obj1.count', {gt: 5})
  })
  .build()

Alias for query.

Alias for query.

Add a "should" query to the query body.

Same arguments as query.

Add a "must_not" query to the query body.

Same arguments as query.

Set the minimum_should_match property on a bool query with more than one should clause.

Add a filter clause to the query body.

bodybuilder()
  .filter('term', 'user', 'kimchy')
  .build()

Alias for filter.

Alias for filter.

Add a "should" filter to the query body.

Same arguments as filter.

Add a "must_not" filter to the query body.

Same arguments as filter.

Set the minimum_should_match property on a bool filter with more than one should clause.

Add an aggregation clause to the query body.

bodybuilder()
  .aggregation('max', 'price')
  .build()

bodybuilder()
  .aggregation('percentiles', 'load_time', {
    percents: [95, 99, 99.9]
  })
  .build()

bodybuilder()
  .aggregation('date_range', 'date', {
    format: 'MM-yyy',
    ranges: [{ to: 'now-10M/M' }, { from: 'now-10M/M' }]
  })
  .build()

bodybuilder()
  .aggregation('diversified_sampler', 'user.id', { shard_size: 200 }, (a) => {
    return a.aggregation('significant_terms', 'text', 'keywords')
  })
  .build()

bodybuilder()
  .aggregation('terms', 'title', {
     _meta: { color: 'blue' }
   }, 'titles')
  .build()

Alias for aggregation.

Add a suggestion clause to the query body.

bodybuilder()
  .suggest('term', price', { text: 'test' })
  .build()

bodybuilder()
  .suggest('phrase', 'price', { text: 'test', name: 'custom name' })
  .build()