elastic-builder

library4.1.0jsnpmunverified

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.

database serialization

npm install elastic-builder

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ELASTIC-BUILDER

elastic-builder

databasejavascriptv4.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

esb

✓ import * as esb from 'elastic-builder';

✗ import 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

✓ import { requestBodySearch } from 'elastic-builder';

✗ import { requestBodySearch } from 'elastic-builder/lib/requestBodySearch';

Accesses a specific top-level builder function directly. Can also be accessed via `esb.requestBodySearch()` after importing `esb`.

MatchQuery

✓ import { MatchQuery } from 'elastic-builder';

✗ import MatchQuery from 'elastic-builder/lib/queries/MatchQuery';

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()`.

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

Debug

Known issues

breakingVersion 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.

affects: >=4.0.0

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.

affects: >=2.0.0

gotchaWhen 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.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: esb is not a function

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'

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.

Upgrade

Version history

4.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/sudo-suhas/elastic-builder ↗

packagehttps://www.npmjs.com/package/elastic-builder ↗

homepagehttps://elastic-builder.js.org ↗