Elasticsearch DSL Libraries for JavaScript/TypeScript

Fluent, type-safe DSL libraries for building Elasticsearch queries in JavaScript and TypeScript. Build queries using method chaining with automatic value escaping, full IDE support, and injection prevention.

Packages

Package	Description	npm
@elastic/elasticsearch-esql-dsl	Build ES|QL queries with a chainable API. Supports all source commands, processing commands, 150+ functions, and expression building.
@elastic/elasticsearch-query-builder	Shared utilities: operator symbols (Op), value/identifier escaping, and the base expression type used across packages.

Quick start

ES|QL query builder

Install the package:

npm install @elastic/elasticsearch-esql-dsl

Build and render a query:

import { ESQL, E, f } from '@elastic/elasticsearch-esql-dsl'

const query = ESQL.from('employees')
  .where(E('still_hired').eq(true))
  .eval({ annual_bonus: E('salary').mul(0.1) })
  .stats({ avg_bonus: f.avg('annual_bonus') })
  .by('department')
  .sort('avg_bonus DESC')
  .limit(10)

console.log(query.render())
// FROM employees
// | WHERE still_hired == true
// | EVAL annual_bonus = salary * 0.1
// | STATS avg_bonus = AVG(annual_bonus) BY department
// | SORT avg_bonus DESC
// | LIMIT 10

Execute with the Elasticsearch JavaScript client:

import { Client } from '@elastic/elasticsearch'

const client = new Client({ node: 'http://localhost:9200' })
const response = await client.esql.query({ query: query.render() })

All queries are immutable -- each method returns a new query object, so you can safely branch from a base query without side effects.

For full documentation, see the ES|QL DSL README.

Development

Prerequisites

• Node.js 20 or later
• pnpm 9 or later

Getting Started

# Clone the repository
git clone https://github.com/elastic/elasticsearch-dsl-js.git
cd elasticsearch-dsl-js

# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Run tests
pnpm run test

# Run linting
pnpm run lint

Available Scripts

Command	Description
pnpm run build	Build all packages
pnpm run test	Run tests for all packages
pnpm run test:watch	Run tests in watch mode
pnpm run test:coverage	Run tests with coverage
pnpm run lint	Lint all packages
pnpm run lint:fix	Fix linting errors
pnpm run typecheck	TypeScript type checking
pnpm run ci	Run full CI pipeline
pnpm run clean	Clean all build artifacts

Working with Individual Packages

# Build a specific package
pnpm --filter @elastic/elasticsearch-query-builder build

# Test a specific package
pnpm --filter @elastic/elasticsearch-esql-dsl test

# Run tests in watch mode for a package
pnpm --filter @elastic/elasticsearch-esql-dsl test:watch

Node.js Version Support

Node.js Version	Supported
20.x	✅
22.x	✅
24.x	✅
25.x	✅

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

Apache 2.0 © Elasticsearch B.V.