# @coedl/elastic-query-builder > A library to help construct elastic search queries Latest version **0.3.0** (published 2021-06-30) · GPLV3 license · 0 weekly downloads ## Install ```sh npm install @coedl/elastic-query-builder pnpm add @coedl/elastic-query-builder yarn add @coedl/elastic-query-builder bun add @coedl/elastic-query-builder ``` ## Health **Score 20/100 (F)** — status: abandoned. Positive: esm support; no vulnerabilities. Warnings: low downloads; no types; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.3.0 | | Published | 2021-06-30 | | First published | 2021-06-28 | | Weekly downloads | 0 | | License | GPLV3 | | TypeScript types | none | | Module format | ESM + CommonJS | | Node | >=14 | | Dependencies | 8 | | Unpacked size | 2.2 MB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | Marco La Rosa | | Maintainers | marcolarosa | ## Links - npm: https://www.npmjs.com/package/@coedl/elastic-query-builder - npm.io page: https://npm.io/package/@coedl/elastic-query-builder ## Dependencies (8) - [lodash](https://npm.io/package/lodash.md) ^4.17.21 - [node-fetch](https://npm.io/package/node-fetch.md) ^2.6.1 - [@types/jest](https://npm.io/package/@types/jest.md) ^26.0.23 - [@types/node](https://npm.io/package/@types/node.md) ^15.12.4 - [@types/lodash](https://npm.io/package/@types/lodash.md) ^4.14.170 - [headers-utils](https://npm.io/package/headers-utils.md) ^3.0.2 - [elastic-builder](https://npm.io/package/elastic-builder.md) ^2.16.0 - [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) ^7.13.0 ## Recent versions - 0.3.0 (latest) — 2021-06-30 - 0.2.0 — 2021-06-28 - 0.1.0 — 2021-06-28 ## README # Elastic Query Builder - [Elastic Query Builder](#elastic-query-builder) - [Developing the library](#developing-the-library) - [Folder setup](#folder-setup) - [Adding a query or aggregation](#adding-a-query-or-aggregation) - [Publishing a new version](#publishing-a-new-version) - [Usage - tutorial](#usage---tutorial) Inspired by [https://elastic-builder.js.org/docs/](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/](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](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](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 }); ``` --- _Source: https://npm.io/package/@coedl/elastic-query-builder · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._