esql-js

ES|QL (Elasticsearch Query Language) tooling for JavaScript and TypeScript: parsing, AST manipulation, pretty-printing, query building, editor integrations, and syntax highlighting. This is a monorepo with multiple packages; see the Packages section below.

Packages

Syntax highlighting grammars:

Package	npm	Description
@elastic/monaco-esql		Monaco Editor language support for ES|QL (syntax highlighting via Monarch)
@elastic/prismjs-esql		Prism.js / refractor grammar for ES|QL syntax highlighting
@elastic/textmate-esql		TextMate grammar for ES|QL syntax highlighting

ES|QL language tooling:

Package	npm	Description
@elastic/esql		Core package — ES|QL parser, AST builder, traversal, mutation, pretty-printing, and the esql composer tag
@elastic/esql-types		Pure TypeScript type definitions for ES|QL and PromQL ASTs; zero runtime code
@elastic/esql-definitions		Language definitions synced from elastic/elasticsearch: commands, functions, operators, settings, and docs
@elastic/elasticsearch-esql-dsl		Fluent, type-safe ES|QL query builder — builds query strings from method chains
@elastic/elasticsearch-query-builder		Shared query-building primitives: operator symbols, escaping helpers, base expression type
@elastic/pretty-printer		Standalone Wadler-Lindig document algebra and layout engine; no ES|QL knowledge
@elastic/esql-grammar		Auto-generated ANTLR4 TypeScript artifacts for the ES|QL grammar
@elastic/esql-promql-grammar		Auto-generated ANTLR4 TypeScript artifacts for the embedded PromQL grammar

Quick start

The main package for working with ES|QL language is @elastic/esql. See packages/esql/ for the full @elastic/esql API reference.

npm install @elastic/esql

Parse a query:

import { Parser } from '@elastic/esql';

const { root, errors } = Parser.parse('FROM index | WHERE col > 100');

Build a parameterized query with the esql composer:

import { esql } from '@elastic/esql';

const query = esql`FROM index | WHERE @timestamp >= ${{ start }} | LIMIT ${{ limit }}`;
console.log(query.toRequest());
// { query: 'FROM index | WHERE @timestamp >= ?start | LIMIT ?limit', params: [...] }

Build a query programmatically with importing ES|QL parser:

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

const query = ESQL.from('employees')
  .where(E('still_hired').eq(true))
  .stats({ avg_salary: f.avg('salary') })
  .by('department')
  .limit(10);

console.log(query.render());

Licences

This repository contains multiple packages with different licences. See each package's package.json for the full licence text.