Elasticsearch Query DSL Builder

4.1.0 · active · verified Wed Apr 22

Elastic-builder is a JavaScript library designed to construct Elasticsearch Query DSL (Domain Specific Language) bodies using a fluent builder pattern, making complex queries easier to write and maintain. Currently in stable version 4.1.0, the package sees a consistent release cadence, with updates typically occurring every 1-2 months to introduce new features and maintain compatibility with modern Node.js versions. Its key differentiators include comprehensive TypeScript definitions for an enhanced development experience, compatibility with the official Elasticsearch JavaScript client, and a focus on replicating Elasticsearch 5.x DSL (while largely usable with newer versions). It provides both class-based and functional builder utilities (e.g., `new esb.MatchQuery()` vs. `esb.matchQuery()`) and recently removed `lodash` as a dependency in v4.1.0, reducing its footprint.

Common errors

```
TypeError: esb is not a function
```
cause Attempting to use a default import for `elastic-builder` in an ESM context when the module primarily exposes named exports or is a CommonJS module that doesn't resolve cleanly as a default ESM import.

fix Change your import statement from `import esb from 'elastic-builder';` to `import * as esb from 'elastic-builder';` in ESM files.
```
Error: Cannot find module 'elastic-builder'
```
cause The `elastic-builder` package is either not installed or your Node.js version is below the minimum requirement of 20.0.0.

fix Ensure `elastic-builder` is installed in your project (`npm install elastic-builder`) and verify that your Node.js runtime is version 20.x, 22.x, or 24.x LTS. Upgrade Node.js if necessary.

Warnings

breaking Version 4.0.0 and above of `elastic-builder` requires Node.js 20.0.0 or higher.
Fix: Upgrade your Node.js environment to version 20.x, 22.x, or 24.x LTS to ensure compatibility and correct execution.
gotcha `elastic-builder` was primarily built against Elasticsearch 5.x Query DSL. While it's largely compatible with newer Elasticsearch versions (e.g., 6.x, 7.x, 8.x), certain new features, deprecated syntax, or breaking changes in the Elasticsearch DSL itself might not be fully supported or may require manual adjustments.
Fix: Consult the official Elasticsearch documentation for your specific target version and cross-reference with `elastic-builder`'s API reference. For advanced or highly version-specific features, you might need to construct parts of the query JSON manually.
gotcha When using `elastic-builder` in an ESM context, a direct default import like `import esb from 'elastic-builder';` may result in `esb` being undefined or not having the expected builder methods. The package's primary examples typically use CommonJS `require()`.
Fix: For ESM, use `import * as esb from 'elastic-builder';` to import all named exports as a single object. For CommonJS environments, `const esb = require('elastic-builder');` remains the correct pattern.

Install

npm install elastic-builder npm
yarn add elastic-builder yarn
pnpm add elastic-builder pnpm

Imports

esb
wrong:
```
import esb from 'elastic-builder';
```
correct:
```
import * as esb from 'elastic-builder';
```
For CommonJS, use `const esb = require('elastic-builder');`. For ESM, `import * as esb from 'elastic-builder';` is recommended to bundle all exports under `esb`.
requestBodySearch
wrong:
```
import { requestBodySearch } from 'elastic-builder/lib/requestBodySearch';
```
correct:
```
import { requestBodySearch } from 'elastic-builder';
```
Accesses a specific top-level builder function directly. Can also be accessed via `esb.requestBodySearch()` after importing `esb`.
MatchQuery
wrong:
```
import MatchQuery from 'elastic-builder/lib/queries/MatchQuery';
```
correct:
```
import { MatchQuery } from 'elastic-builder';
```
Imports the class for direct instantiation (e.g., `new MatchQuery('field', 'value')`). Can also be accessed via `esb.MatchQuery` or its functional equivalent `esb.matchQuery()`.

Quickstart

Demonstrates building a complex Elasticsearch query body using a boolean query, range filter, terms aggregation, and sorting, then outputs the JSON representation.

import * as esb from 'elastic-builder';

// Build a complex search request with a query, aggregation, and sorting.
const requestBody = esb.requestBodySearch()
  .query(
    esb.boolQuery()
      .must(esb.matchQuery('message', 'this is a test'))
      .filter(esb.rangeQuery('timestamp').gte('now-1d/d'))
  )
  .agg(
    esb.termsAggregation('top_tags', 'tags.keyword')
      .size(10)
      .order('_count', 'desc')
  )
  .sort(esb.sort('timestamp', 'desc'));

// Convert the builder object to its JSON representation
const queryJson = requestBody.toJSON();

console.log('Generated Elasticsearch Query Body:');
console.log(JSON.stringify(queryJson, null, 2));

view raw JSON →