elastic-querybuilder
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
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();
{
from: 0,
size: 15,
query: {
bool: {
boost: 1.2,
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();
{
from: 0,
size: 15,
query: {
match_all: {}
}
}
Simple Query with options
const query = new QueryBuilder()
.query('match_all', { boost: 2.4, fuzziness: 'auto' })
.build();
{
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();
{
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();
{
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();
{
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()
{
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()
{
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,
value?: string|Object
)
Examples
Simple sort
const query = new QueryBuilder()
.query( ... )
.sort('age', 'desc')
.build();
{
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();
{
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,
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();
{
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();
{
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?: string,
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>,
}
): 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
})
{
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
}
): 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%'
});
{
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?: string,
filterAggs?: boolean
}
): Object
Contributing
See our contributors guide.