A library to help construct elastic search queries
npm install @coedl/elastic-query-builder- Elastic Query Builder
- Developing the library
- Folder setup
- Adding a query or aggregation
- Publishing a new version
- Usage - tutorial
Inspired by https://elastic-builder.js.org/docs/. I couldn't
get it to work in the browser but the ideas are very cool so I thought I'd use this opportunity to
setup up a typescript library that supports both CommonJS (cjs) and ES (mjs) modules.
API documentation is available at
https://coedl.github.io/elastic-query-builder/
In a terminal:
```
> npm run develop
This sets up typescript in watch mode to compile the code.
In another terminal:
``
> npm run tests:watch
This gets Jest going in watch mode to run the tests. With regard to Jest - support for ES modules
support is experimental
({https://jestjs.io/docs/ecmascript-modules(https://jestjs.io/docs/ecmascript-modules)}) so note
that the tests use cjs imports from the cjs bundles in dist.
- dist: the built code - built by typescript - you should never be working in this folderdocs
- : the API docs - built by jsdoc - you should never be working in this foldersrc/queries/*
- : the query fragment generators. Folder structure follows the categorisation @src/aggregations/*
https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
- : the aggregation fragment generators. Folder structure follows the
categorisation @
https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html
Say you needed an interval query as defined in QueryDSL: Full Text Queries:
- Add src/queries/full-text-queries/interval-query.ts with code to return the query fragmentsrc/queries/full-text-queries/interval-query.spec.js
- Add a test for it in (note the JSsrc/queries/index.ts
suffix - see note above re: jest and es modules)
- Register the query in
- Build the distributables (dist): > npm run build> git add dist docs && git commit
- Check it in: npm version [major | minor | patch ]
- Bump the version: as requirednpm publish
- Publish:
The base building block is the Query class. Instantiate this to start building a query:
`
import { Query } from '@coedl/elastic-query-builder'
let query = new Query({})
`
Once you have a query object you can append a query clause to it:
`
import { termQuery } from '@coedl/elastic-query-builder/queries'
query = query.append(termQuery({}))
`
Or if you have a complex set of queries append a BoolQuery:
`
import { BoolQuery } from '@coedl/elastic-query-builder'
import { termQuery, matchQuery, rangeQuery } from '@coedl/elastic-query-builder/queries'
query = query.append(
new BoolQuery()
.must( [termQuery()] )
.should( [matchQuery(), rangeQuery({}) ])
`
Multi level compound queries are supported:
``
query = query.append(
new BoolQuery()
.must( [
termQuery(),
new BoolQuery()
.should( [termQuery, rangeQuery] )
] )
.should( [matchQuery(), rangeQuery({}) ])
Notice we're always storing the return query.
When you're ready to search get the JSON representation of the query and search away:
`
query = query.toJSON()
// this is however you execute a query against elastic: see helpers.ts for the method let result =
await execute({ index, query });
`
Aggregations are added in the same way:
`
import { termsAggregation } from '@coed/elastic-query-builder/aggregations'
query = query.aggregation(termsAggregation({}))
`
Or many aggregations:
`
import { termsAggregation, cardinalityAggregation } from '@coed/elastic-query-builder/aggregations'
query = query.aggregation([ termsAggregation({}), cardinalityAggregation({}) ])
`
And then execute:
`
query = query.toJSON()
// this is however you execute a query against elastic: see helpers.ts for the method let result
await execute({ index, query });
``