es-query-pro

Simple and powerful ElasticSearch query builder

Installation

npm install es-query-pro

Function reference

Basic

| Function | Match Type | Example | | -------------------------------------------- | ----------------- | ----------------------------------------------- | | term(fieldOrFields, valueOrValues, anyOrAll) | Exact field value | term('created_by', 123) | | matchBoostedPhrase(fields, terms, options) | Full-text | matchBoostedPhrase(['title'], 'AT&T Wireless') | | match(field, valueOrValues) | Full-text | match('title', 'Market research') | | exists(fieldOrFields) | Exact field | exists('deleted_at') | | range(field, op, value) | Exact field value | range('age', 'between', [18, 35]) |

Advanced

| Function | Match Type | Example | | ---------------------------------------------------- | ----------------- | ------------------------------------------------------------ | | multiTerm(fields, value, anyOrAll) | Exact field value | multiTerm(['created_by','modified_by'], 123) | | matchPhrase(field, phraseOrPhrases) | Full-text | matchPhrase('title', 'Little Red Riding Hood') | | matchPhrasePrefix(fieldOrFields, phraseOrPhrases) | Full-text | matchPhrasePrefix('title', 'Little Red R') | | multiMatch(fields, valueOrValues, anyOrAll) | Full-text | multiMatch(['title','body'], ['phone','mobile'], 'ALL') | | multiMatchWithPhrase(fields, valueOrValues, options) | Full-text | multiMatchWithPhrase(['title','body'], ['phone','mobile']) | | queryString(fieldOrFields, query) | Lucene expression | queryString('body', '(tech AND support) OR (service desk)') |

boostedPhrase??

Negative conditions

| Function | Match Type | Example | | ------------------------------------ | ----------------- | -------------------------------------------- | | notTerm(field, valueOrValues) | Exact field value | notTerm('status', [2,3,4]) | | notMultiTerm(fields, value) | Exact field value | notMultiTerm(['border','outline'], 'blue') | | notExists(fieldOrFields) | Exact field | notExists('category') | | notMatch(field, valueOrValues) | Full-text | notMatch('title', 'Market research') | | notMultiMatch(fields, valueOrValues) | Full-text | notMultiMatch(['title','body'], 'Research') | | notRange(field, op, value) | Exact field value | notRange('age', 'between', [36, 44]) |

Sorting and pagination

| Function | Example | | ------------------------- | ------------------- | | limit(limitTo) | limit(10) | | page(pageNo) | page(2) | | sort(field) | sort('-created_at') | | sortByRandom(trueOrFalse) | sortByRandom(true) |

Subqueries

| Function | Purpose | | --------------------- | ----------------------------- | | should(subquery) | Where subquery matches | | shouldNot(subquery) | Where subquery does not match | | shouldAny(subqueries) | Where any subquery matches |

Special functions

| Function | Purpose | | ------------------------------------------------ | ----------------------------------------------------------------------------- | | fields(fieldNames) | Set which fields to return. Default is ['*'] which returns all fields | | useHighlighter(definition) | Ask for excerpts of text near the matching terms | | includeFacets(forFields, limit) | Include counts for each field | | decayFunctionScore(definition) | Give match weight based on a bell-curve | | aggregateTerm(field, limit, exclusions) | A count of field values (like GROUP BY in SQL) | | dateHistogram(dateField, intervalName, timezone) | Aggregate matches by time periods | | clear(field) | Clear page, limit, must, mustNot, aggs, fields, highlighter, or functionScore |

Inspection

| Function | Purpose | | ------------ | -------------------------------------------- | | toKibana() | Get a string suitable for running in Kibana | | getFields() | Get the list of fields that will be returned | | getBody() | Get the structure of the query body | | getOptions() | Get the size, from, sort | | getQuery() | Return the fields, body and options to query |

Examples

const EsQueryBuilder = require('es-query-pro');

const query = new EsQueryBuilder();
query.term('author', 15);
query.matchBoostedPhrase(['fulltext_*'], 'Cold pressed juice');
query.range('created_at', '>=', '2021-01-01');
query.sort('created_at', 'desc');
query.limit(25);
query.page(2);

const textProcessor = new TextProcessor();
textProcessor.setArrayJoiner('ψ');
textProcessor.registerPattern(
	{ find: /([a-z])&([a-z0-9])/gi, replace: '$1ε$2' },
	{ find: /([a-z])ε([a-z0-9])/gi, replace: '$1&$2' }
);
textProcessor.registerField(/^fulltext_/);
QueryBuilder.registerProcessor(textProcessor);

Unit Tests and Code Coverage

Powered by jest

npm test
npm run coverage

Contributing

Contributions are welcome. Please open a GitHub ticket for bugs or feature requests. Please make a pull request for any fixes or new code you'd like to be incorporated.

License

Open Source under the ISC License.