@ 弹性/ esql

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

安装

npm install @elastic/esql

yarn add @elastic/esql

pnpm add @elastic/esql

子模块参考

创建 ESQQL AST

分析查询

这个 Parser 将查询字符串同步转换为 AST .

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

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

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

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

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

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

构建查询

这个 esql 作曲家 是一个带有标签的模板 API,用于安全参数注入的构建查询 :

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 并同时附加多个管状命令:

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

见 synth API用于从模板字符串合成单个 AST 节点.

手动构建 AST 节点

这个 Builder 是一个低等API,用于在程序上构建 AST 节点:

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

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

驾驶ESQL AST

华克

这个 Walker 访问 AST 中的每个节点, 调用每个节点类型的回调 :

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 支持 在行尸文档.

访客

这个 Visitor 提供更强大的转盘模型,在其中您可以控制要访问的孩子们,回调可以通过树上下打入的值:

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 API为常见的结构编辑提供了命名方法:

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 模块格式化 AST 返回查询字符串.

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

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 } 解析器 :

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() 在作曲中:

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 读取 页:1 pql, (中文(简体) ), pqlSel, (中文(简体) ), pqlFunc,以及其他 PromQL 节点构建器.

许可证

许可证根据 弹性许可证2.0。 。 。 .