# @elastic/esql 中文文档

规范地址：https://npmcn.com/package/%40elastic/esql/

版本：4\.39\.0
npm 元数据更新时间：2026-11-11T13:00:04.403Z
中文译文更新时间：2026-11-13T10:34:57.149Z
软件包许可：Elastic-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40elastic/esql
原文对照：https://npmcn.com/package/%40elastic/esql/?lang=original
源码仓库：https://github.com/elastic/esql-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.2 MB，132 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：11 个
- 首次发布：2026-02-24T10:48:17.029Z
- 最新版本发布：2026-11-11T13:00:03.791Z
- 近 30 天下载量：695576（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：68（近 12 个月 68 个）

## 中文简介

一套 ts 工具,用于在程序上解析,构建和改造ESQQL查询.

## 安装

```sh
npm install @elastic/esql
```

也可以使用：`pnpm add @elastic/esql`、`yarn add @elastic/esql`、`bun add @elastic/esql`

## README

# @ 弹性/ esql

 [![Grammar Sync](https://badge.buildkite.com/455a3e37b4061fc25a448cba264e622b6c71be8101cd7b74f3.svg?branch=main)](https://buildkite.com/elastic/esql-js-grammar-sync)[![NPM version](https://img.shields.io/npm/v/@elastic/esql.svg)](https://www.npmjs.com/package/@elastic/esql)

ESQQL和PromQL parser, AST 构建器, traversal, 突变,以及JavaScript和TypeScript的漂亮打印. 被用在了Kibana和其他弹性工具.

## 安装

| 无 | 线条 | 小时 |
| --- | --- | --- |
| 
```bash
npm install @elastic/esql
```

 | 

```bash
yarn add @elastic/esql
```

 | 

```bash
pnpm add @elastic/esql
```

 |

## 子模块参考

| 模块 | 说明 |
| --- | --- |
| [`src/parser/`](https://npmcn.com/package/%40elastic/esql/src/parser/README.md) | `Parser` 类 - 解析查询字符串到 AST |
| [`src/composer/`](https://npmcn.com/package/%40elastic/esql/src/composer/README.md) | `esql` 有标记的模板查询构建器 |
| [`src/composer/synth/`](https://npmcn.com/package/%40elastic/esql/src/composer/synth/README.md) | `synth` ——从模板字符串合成 AST 节点; PromQL 节点构建器 |
| [`src/ast/builder/`](https://npmcn.com/package/%40elastic/esql/src/ast/builder/README.md) | `Builder` ——低水平AST节点建设 |
| [`src/ast/walker/`](https://npmcn.com/package/%40elastic/esql/src/ast/walker/README.md) | `Walker` 简单的全树倒行道 |
| [`src/ast/visitor/`](https://npmcn.com/package/%40elastic/esql/src/ast/visitor/README.md) | `Visitor` - 输入/输出经过的有控制的打字道转 |
| [`src/ast/mutate/`](https://npmcn.com/package/%40elastic/esql/src/ast/mutate/README.md) | `mutate` ——用于结构 AST 编辑的指定助手 |
| [`src/pretty_print/`](https://npmcn.com/package/%40elastic/esql/src/pretty_print/README.md) | `BasicPrettyPrinter`, (中文(简体) ), `WrappingPrettyPrinter` |

## 创建 ESQQL AST

### 分析查询

这个 [`Parser`](https://npmcn.com/package/%40elastic/esql/src/parser/README.md) 将查询字符串同步转换为 AST .

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

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

过 `{ withFormatting: true }` 在 AST 节点上附加注释和空白( 回合格式化需要) :

```ts
const { root } = Parser.parse('FROM /* comment */ index', { withFormatting: true });
```

在没有完整查询字符串的情况下分析单个命令或表达式 :

```ts
const { root: expr } = Parser.parseExpression('count(*) + 1');
const { root: cmd } = Parser.parseCommand('WHERE col > 10');
```

### 构建查询

这个 [`esql` 作曲家](https://npmcn.com/package/%40elastic/esql/src/composer/README.md) 是一个带有标签的模板 API,用于安全参数注入的构建查询 :

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

const start = '2024-01-01';
const limit = 100;

const query = esql`
  FROM index
    | WHERE @timestamp >= ${{ start }}
    | SORT @timestamp DESC
    | KEEP service.name, log.level`;

query.pipe`LIMIT ${{ limit }}`;

// Get the Elasticsearch request payload:
query.toRequest();
// { query: 'FROM index | WHERE @timestamp >= ?start | ...', params: [{ start: '2024-01-01' }, ...] }
```

使用 `.query` 并同时附加多个管状命令:

```ts
query.query`WHERE status == ${{ status }} | STATS count = COUNT(*) | LIMIT ${{ limit }}`;
```

见 [`synth`](https://npmcn.com/package/%40elastic/esql/src/composer/synth/README.md) API用于从模板字符串合成单个 AST 节点.

### 手动构建 AST 节点

这个 [`Builder`](https://npmcn.com/package/%40elastic/esql/src/ast/builder/README.md) 是一个低等API,用于在程序上构建 AST 节点:

```ts
import { Builder } from '@elastic/esql';

const node = Builder.command({
  name: 'limit',
  args: [Builder.expression.literal.integer(10)],
});
```

## 驾驶ESQL AST

### 华克

这个 [`Walker`](https://npmcn.com/package/%40elastic/esql/src/ast/walker/README.md) 访问 AST 中的每个节点, 调用每个节点类型的回调 :

```ts
import { Walker } from '@elastic/esql';
import type { ESQLCommand, ESQLFunction } from '@elastic/esql-types';

const walker = new Walker({
  visitCommand: (node: ESQLCommand) => {
    console.log('command:', node.name);
  },
  visitFunction: (fn: ESQLFunction) => {
    console.log('function:', fn.name);
  },
});

walker.walk(root);
```

静态助手喜欢 `Walker.findAll()`, (中文(简体) ), `Walker.params()`,以及 `Walker.replace()` 覆盖最常见的搜索和修改模式,不需要即时攻击行走者.

行走者还穿行嵌入了 PromQL 表达式——见 [PromQL 支持](https://npmcn.com/package/%40elastic/esql/src/ast/walker/README.md#promql-support) 在行尸文档.

### 访客

这个 [`Visitor`](https://npmcn.com/package/%40elastic/esql/src/ast/visitor/README.md) 提供更强大的转盘模型,在其中您可以控制要访问的孩子们,回调可以通过树上下打入的值:

```ts
import { Visitor } from '@elastic/esql';

const columnNames = new Visitor()
  .on('visitColumnExpression', (ctx) => ctx.node.name)
  .on('visitExpression', () => null)
  .on('visitCommand', (ctx) => [...ctx.visitArguments()])
  .on('visitQuery', (ctx) => [...ctx.visitCommands()])
  .visitQuery(root);
```

## 正在修改 ESQL AST

这个 [`mutate`](https://npmcn.com/package/%40elastic/esql/src/ast/mutate/README.md) API为常见的结构编辑提供了命名方法:

```ts
import { Parser, mutate, BasicPrettyPrinter } from '@elastic/esql';

const { root } = Parser.parse('FROM index METADATA _lang');

console.log([...mutate.commands.from.metadata.list(root)]);
// [ '_lang' ]

mutate.commands.from.metadata.upsert(root, '_id');

console.log([...mutate.commands.from.metadata.list(root)]);
// [ '_lang', '_id' ]

console.log(BasicPrettyPrinter.print(root));
// FROM index METADATA _lang, _id
```

## 相当的印刷

这个 [`pretty_print`](https://npmcn.com/package/%40elastic/esql/src/pretty_print/README.md) 模块格式化 AST 返回查询字符串.

**`BasicPrettyPrinter`** ——单线或管相分离多线输出:

```ts
import { Parser, BasicPrettyPrinter } from '@elastic/esql';

const { root } = Parser.parse('FROM index | WHERE x > 100 | LIMIT 100');

BasicPrettyPrinter.print(root);
// FROM index | WHERE x > 100 | LIMIT 100

BasicPrettyPrinter.multiline(root, { pipeTab: '  ' });
// FROM index
//   | WHERE x > 100
//   | LIMIT 100
```

**`WrappingPrettyPrinter`** ——宽度认识,保留注释(需要) `{ withFormatting: true }` 解析器 :

```ts
import { Parser, WrappingPrettyPrinter } from '@elastic/esql';

const { root } = Parser.parse(
  'FROM index /* source */ | WHERE x > 100 | LIMIT 100',
  { withFormatting: true },
);

console.log(WrappingPrettyPrinter.print(root, { multiline: true }));
// FROM index /* source */
// | WHERE x > 100
// | LIMIT 100
```

## PromQL 支持

ESQQL通过 `PROMQL` 源头命令. 使用 `esql.promql()` 在作曲中:

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

esql.promql(esql.pql`sum(rate(metric[5m])) by (job)`)
  .where`value > 0`
  .limit(100)
  .print();
// PROMQL (sum(rate(metric[5m])) by (job)) | WHERE value > 0 | LIMIT 100
```

见 [`synth` 读取](https://npmcn.com/package/%40elastic/esql/src/composer/synth/README.md) 页:1 `pql`, (中文(简体) ), `pqlSel`, (中文(简体) ), `pqlFunc`,以及其他 PromQL 节点构建器.

## 许可证

许可证根据 [弹性许可证2.0](https://npmcn.com/package/%40elastic/esql/LICENSE.txt)。 。 。 .

## 常见问题

### @elastic/esql 是什么？

一套 ts 工具,用于在程序上解析,构建和改造ESQQL查询\.

### 如何安装 @elastic/esql？

在项目目录运行 npm install @elastic/esql，或使用 pnpm add / yarn add / bun add。

### @elastic/esql 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @elastic/esql 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @elastic/esql 可以商用吗？

@elastic/esql 使用 Elastic-2\.0 许可。声明的许可为 Elastic-2\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @elastic/esql 的下载量有多少？

根据 npm 官方下载统计，@elastic/esql 在 2026/10/14 – 2026/11/12 这 30 天内被下载 695,576 次，日均约 23,186 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @elastic/esql 还在维护吗？

最新版本 4\.39\.0 发布于 2026/11/11（2 天前）；至今共发布 68 个版本，其中过去 12 个月发布了 68 个；首次发布于 2026/02/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。