@asymmetrik/elastic-querybuilder
v0.9.12
Published
A query builder for Elasticsearch.
Downloads
170
Readme
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
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
, andmust_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
, andraw
. 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
, andraw
. 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
, andraw
. 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
, andraw
. 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.