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/

Developing the library

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.

Folder setup

- dist: the built code - built by typescript - you should never be working in this folder
- docs: the API docs - built by jsdoc - you should never be working in this folder
- src/queries/*: the query fragment generators. Folder structure follows the categorisation @
https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
- src/aggregations/*: the aggregation fragment generators. Folder structure follows the
categorisation @
https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html

Adding a query or aggregation

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 fragment
- Add a test for it in src/queries/full-text-queries/interval-query.spec.js (note the JS
suffix - see note above re: jest and es modules)
- Register the query in src/queries/index.ts

Publishing a new version

- Build the distributables (dist): > npm run build
- Check it in: > git add dist docs && git commit
- Bump the version: npm version [major | minor | patch ] as required
- Publish: npm publish

Usage - tutorial

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 });
``