{"id":16346,"library":"elastic-builder","title":"Elasticsearch Query DSL Builder","description":"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.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/sudo-suhas/elastic-builder","tags":["javascript","elasticsearch","elastic-builder","querying","queries","query","elastic","search","elasticjs","typescript"],"install":[{"cmd":"npm install elastic-builder","lang":"bash","label":"npm"},{"cmd":"yarn add elastic-builder","lang":"bash","label":"yarn"},{"cmd":"pnpm add elastic-builder","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For CommonJS, use `const esb = require('elastic-builder');`. For ESM, `import * as esb from 'elastic-builder';` is recommended to bundle all exports under `esb`.","wrong":"import esb from 'elastic-builder';","symbol":"esb","correct":"import * as esb from 'elastic-builder';"},{"note":"Accesses a specific top-level builder function directly. Can also be accessed via `esb.requestBodySearch()` after importing `esb`.","wrong":"import { requestBodySearch } from 'elastic-builder/lib/requestBodySearch';","symbol":"requestBodySearch","correct":"import { requestBodySearch } from 'elastic-builder';"},{"note":"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()`.","wrong":"import MatchQuery from 'elastic-builder/lib/queries/MatchQuery';","symbol":"MatchQuery","correct":"import { MatchQuery } from 'elastic-builder';"}],"quickstart":{"code":"import * as esb from 'elastic-builder';\n\n// Build a complex search request with a query, aggregation, and sorting.\nconst requestBody = esb.requestBodySearch()\n  .query(\n    esb.boolQuery()\n      .must(esb.matchQuery('message', 'this is a test'))\n      .filter(esb.rangeQuery('timestamp').gte('now-1d/d'))\n  )\n  .agg(\n    esb.termsAggregation('top_tags', 'tags.keyword')\n      .size(10)\n      .order('_count', 'desc')\n  )\n  .sort(esb.sort('timestamp', 'desc'));\n\n// Convert the builder object to its JSON representation\nconst queryJson = requestBody.toJSON();\n\nconsole.log('Generated Elasticsearch Query Body:');\nconsole.log(JSON.stringify(queryJson, null, 2));","lang":"typescript","description":"Demonstrates building a complex Elasticsearch query body using a boolean query, range filter, terms aggregation, and sorting, then outputs the JSON representation."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20.x, 22.x, or 24.x LTS to ensure compatibility and correct execution.","message":"Version 4.0.0 and above of `elastic-builder` requires Node.js 20.0.0 or higher.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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()`.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change your import statement from `import esb from 'elastic-builder';` to `import * as esb from 'elastic-builder';` in ESM files.","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.","error":"TypeError: esb is not a function"},{"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.","cause":"The `elastic-builder` package is either not installed or your Node.js version is below the minimum requirement of 20.0.0.","error":"Error: Cannot find module 'elastic-builder'"}],"ecosystem":"npm"}