npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@asymmetrik/elastic-querybuilder

v0.9.12

Published

A query builder for Elasticsearch.

Downloads

170

Readme

elastic-querybuilder Build Status

A query builder for Elasticsearch.

Install

# Install with Yarn
yarn add @asymmetrik/elastic-querybuilder
# Install with npm
npm install --save @asymmetrik/elastic-querybuilder

API

For a more comprehensive set of examples, see the __tests__ directory

First you need to create an instance of the query builder class:

const QueryBuilder = require('@asymmetrik/elastic-querybuilder');
const builder = new QueryBuilder();

Builder Methods

from

Change the starting point for paging to a new number. Default value is 0.

builder.from(from: number): QueryBuilder
size

Change the number of results to a new number. Default value is 15.

builder.size(size: number): QueryBuilder
trackScores

Sets the track_scores option.

builder.trackScores(trackScores: boolean): QueryBuilder
raw

Allows to set a value on the query object at your path.

builder.raw(size: number): QueryBuilder
Examples
const query = new QueryBuilder()
  .raw('query.bool.boost', 1.2)
  .must('match', 'name', 'Kenny')
  .build();

//- Generates the following query
{
  from: 0,
  size: 15,
  query: {
    bool: {
      boost: 1.2, // was set by raw
      must: [ { match: { name: 'Kenny' }} ]
    }
  }
}
query

Build up a query object. If your last or only argument is a function, it will be passed a builder object that can be used to nest boolean queries or build nested queries. The must, should, filter, and must_not all have the same API and can be used in the same way.

builder.query(
  operation: string,
  field?: string|Object,
  value?: string,
  options?: Object,
  nester?: Function
): QueryBuilder
Examples

Simple Query

const query = new QueryBuilder()
  .query('match_all')
  .build();

//- Generates the following query
{
  from: 0,
  size: 15,
  query: {
    match_all: {}
  }
}

Simple Query with options

const query = new QueryBuilder()
  .query('match_all', { boost: 2.4, fuzziness: 'auto' })
  .build();

//- Generates the following query
{
  from: 0,
  size: 15,
  query: {
    match_all: {
      boost: 2.4,
      fuzziness: 'auto'
    }
  }
}

Simple Query with field and value

const query = new QueryBuilder()
  .query('match', 'location', 'South Park')
  .build();

//- Generates the following query  
{
  from: 0,
  size: 15,
  query: {
    match: {
      location: 'SouthPark'
    }
  }
}

Query with callback to build nested queries.

const query = new QueryBuilder()
  .should('match', 'firstname', 'Joe')
  .should('match', 'firstname', 'John')
  .should(builder => builder
    .should('match', 'lastname', 'Smith')
    .should('match', 'lastname', 'Davis')
  )
  .build();

//- Generates the following query  
{
  from: 0,
  size: 15,
  query: {
    bool: {
      should: [
        { match: { firstname: 'Joe' }},
        { match: { firstname: 'John' }},
        {
          bool: {
            should: [
              { match: { lastname: 'Smith' }},
              { match: { lastname: 'Davis' }}
            ]
          }
        }
      ]
    }
  }
}
must

Add a must boolean query to your ES query. See query above and __tests__ for examples.

builder.must(
  operation: string,
  field?: string|Object,
  value?: string,
  options?: Object,
  nester?: Function
): QueryBuilder
should

Add a should boolean query to your ES query. See query above and __tests__ for examples.

builder.should(
  operation: string,
  field?: string|Object,
  value?: string,
  options?: Object,
  nester?: Function
): QueryBuilder
filter

Add a filter boolean query to your ES query. See query above and __tests__ for examples.

builder.filter(
  operation: string,
  field?: string|Object,
  value?: string,
  options?: Object,
  nester?: Function
): QueryBuilder
must_not

Add a must_not boolean query to your ES query. See query above and __tests__ for examples.

builder.must_not(
  operation: string,
  field?: string|Object,
  value?: string,
  options?: Object,
  nester?: Function
): QueryBuilder
aggs

Generate aggregation type queries. This will build up the aggs property on an ES query.

builder.aggs(
  type: string
  field?: string|Object
  options?: Object,
  nester?: Function
): QueryBuilder
Examples

Simple Aggregation

const query = new QueryBuilder()
  .query('match_all')
  .raw('explain', true)
  .aggs('avg', 'count')
  .build();

//- Generates the following query
{
  from: 0,
  size: 15,
  explain: true,
  query: {
    match_all: {}
  },
  aggs: {
    count: {
      avg: {
        field: 'count'
      }
    }
  }
}

Multiple Aggregations

const query = new QueryBuilder()
  .query('match_all')
  .aggs('geo_distance', 'location', {
    origin: '52.3760, 4.894',
    unit: 'km',
    ranges: [
      { to: 100 },
      { from: 100, to: 300 },
      { from: 300 }
    ]
  })
  .aggs('max', 'price')
  .aggs('sum', 'sales')
  .build()

//- Generates the following query
{
  from: 0,
  size: 15,
  query: {
    match_all: {}
  },
  aggs: {
    location: {
      geo_distance: {
        field: 'location',
        origin: '52.3760, 4.894',
        unit: 'km',
        ranges: [
          { to: 100 },
          { from: 100, to: 300 },
          { from: 300 }
        ]
      }
    },
    price: {
      max: {
        field: 'price'
      }
    },
    sales: {
      sum: {
        field: 'sales'
      }
    }
  }
}

Nested Aggregations

const query = new QueryBuilder()
  .query('match_all')
  .aggs('nested', { path: 'locations' }, builder => builder
    .aggs('terms', 'locations.city')
  )
  .build()

//- Generates the following query
{
  from: 0,
  size: 15,
  query: {
    match_all: {}
  },
  aggs: {
    locations: {
      nested: {
        path: 'locations'
      },
      aggs: {
        'locations.city': {
          terms: {
            field: 'locations.city'
          }
        }
      }
    }
  }
}
sort

Add sorting options. This method essentially just takes a key and a value for an object.

builder.sort(
  field?: string, // or Type of sort, could be something like _geo_distance
  value?: string|Object
)
Examples

Simple sort

const query = new QueryBuilder()
  .query( ... )
  .sort('age', 'desc')
  .build();
  
//- Generates the following query
{
  from: 0,
  size: 15,
  query: { ... },
  sort: [
    { age: 'desc' }
  ]
}

Geo distance sort

const query = new QueryBuilder()
  .query( ... )
  .sort('_geo_distance', {
    coordinates: [ -70, 40 ],
    distance_type: 'arc',
    order: 'asc',
    unit: 'mi',
    mode: 'min'
  })
  .build();
  
//- Generates the following query
{
  from: 0,
  size: 15,
  query: { ... },
  sort: [
    {
      _geo_distance: {
        coordinates: [ -70, 40 ],
        distance_type: 'arc',
        order: 'asc',
        unit: 'mi',
        mode: 'min'
      }
    }
  ]
}
func

Add functions to be used in function_score queries. This method essentially just takes a key and a value for an object and is only used when calling buildFunctionScore.

builder.func(
  field?: string|Object, // or Type of function
  value?: string|Object
)
Examples

Field value factor function

const query = new QueryBuilder()
  .query( ... )
  .func('field_value_factor', {
    field: 'number_of_something',
    modifier: 'ln2p',
    factor: 1
  })
  .buildFunctionScore();
  
//- Generates the following query
{
  from: 0,
  size: 15,
  query: {
    function_score: {
      query: { ... },
      functions: [{
        field_value_factor: {
          field: 'number_of_something',
          modifier: 'ln2p',
          factor: 1
        }
      }]
    }
  }
}

Filter function

const query = new QueryBuilder()
  .query( ... )
  .func({
    weight: 100,
    filter: {
      match: {
        state: 'Colorado'
      }
    }
  })
  .buildFunctionScore();
  
//- Generates the following query
{
  from: 0,
  size: 15,
  query: {
    function_score: {
      query: { ... },
      functions: [{
        weight: 100,
        filter: {
          match: {
            state: 'Colorado'
          }
        }
      }]
    }
  }
}

Build Functions

build

Build your basic query. This includes parameters set using query, must, should, filter, must_not, aggs, from, size, and raw. See __tests__ for more examples.

builder.build(
  options?: {
    // Name for your filtered aggregations, default is 'all'
    name?: string,
    // Add filters to your aggregations, better for accurate facet counts
    filterAggs?: boolean
  }
): Object
buildDisMax

Build your basic query. This includes parameters set using from, size, and raw. See __tests__ for more examples.

builder.buildDisMax(
  options: {
    tie_breaker: number,
    boost: number,
    queries: Array<Object>,
    // You can add more parameters that belong on the
    // top level of a dis_max query. These are directly
    // passed in so if it is an invalid prop, your 
    // query will fail
  }
): Object
Examples

Building a dis_max query

const query = new QueryBuilder()
  .buildDisMax({
    queries: [
      { term: { age: 31 }},
      { term: { age: 32 }}
    ],
    tie_breaker: 1.2,
    boost: 2
  })
//- Generates the following query
{
  from: 0,
  size: 15,
  query: {
    dis_max: {
      queries: [
        { term: { age: 31 }},
        { term: { age: 32 }}
      ],
      tie_breaker: 1.2,
      boost: 2
    }
  }
}
buildMultiMatch

Build your basic query. This includes parameters set using from, size, and raw. See __tests__ for more examples.

builder.buildMultiMatch(
  options: {
    query: string,
    fields: Array<string>,
    type: string,
    tie_breaker: number,
    minimum_should_match: string
    // You can add more parameters that belong on the
    // top level of a dis_max query. These are directly
    // passed in so if it is an invalid prop, your 
    // query will fail
  }
): Object
Examples

Building a multi_match query

const query = new QueryBuilder()
  .buildMultiMatch({
    query: 'The Coon',
    fields: ['superhero', 'name', 'alias'],
    type: 'best_fields',
    tie_breaker: 0.3,
    minimum_should_match: '30%'
  });

//- Generates the following query
{
  from: 0,
  size: 15,
  query: {
    multi_match: {
      query: 'The Coon',
      fields: ['superhero', 'name', 'alias'],
      type: 'best_fields',
      tie_breaker: 0.3,
      minimum_should_match: '30%'
    }
  }
}
buildFunctionScore

Build your basic query. This includes parameters set using query, must, should, filter, must_not, aggs, func, from, size, and raw. See __tests__ for more examples.

builder.buildFunctionScore(
  options?: {
    // Name for your filtered aggregations, default is 'all'
    name?: string,
    // Add filters to your aggregations, better for accurate facet counts
    filterAggs?: boolean
  }
): Object

Contributing

See our contributors guide.