Elasticsearch Studio

在 VS Code 里连 Elasticsearch / OpenSearch：侧边栏浏览集群（索引、字段、别名、数据流、模板、管道、快照、节点、任务），在命令窗口或 .edql 文件里用 EDQL 写请求和脚本，结果看 JSON、表格、图表，查看和修改文档，导入导出、复制索引。

EDQL 的语法和功能复刻 JetBrains 插件 Elasticsearch Query - EDQL（详细的对照见源码仓库里的 docs/功能规格.md），界面沿用 PostgreSQL Studio 的风格。

侧边栏顶部两个页签：

所有配置保存在 ~/.x1/es-studio/conf.yaml（见「配置文件」）。

数据源

添加 / 编辑数据源

「添加数据源」弹窗填写：

• 地址：集群的 HTTP 地址，可以带路径前缀（经网关转发时）；勾选「这是 Kibana 地址」时请求经 Kibana 的 /api/console/proxy 转发（跟 Dev Tools 一样，OpenSearch Dashboards 也行）；
• 认证：无、用户名 / 密码（Basic）、API Key（填编码好的值或 id:api_key）、Authorization（原样作为请求头）、Bearer Token、Cookie、AWS 签名（SigV4，服务 es 或 aoss；可以填密钥，也可以用系统默认凭证：环境变量或 ~/.aws/credentials 的 profile）；
• 连接：CA 证书文件、是否校验 HTTPS 证书（自签证书可以关掉）、超时（秒）、只读、额外的请求头；
• 代理 / SSH 隧道：HTTP 代理（http://user:pass@host:port），或者经 SSH 跳板机转发（密码、私钥文件、ssh-agent；跳板机可以写 ~/.ssh/config 里的 Host 名）；
• 索引过滤：数据源树里排除 / 只显示哪些索引（正则）。

「测试连接」报出集群名和版本。名称留空时取地址。

只读的数据源在命令窗口、文件、数据页、表格编辑里只放行查询：GET、HEAD 以及 _search、_count、_msearch、_mget、_sql、_query、_analyze、_validate/query、_explain、_field_caps 这些只读接口。

数据源树

树的每一层都是展开时才查询。数据源 → 十组：

索引的右键菜单：

• 查看数据（双击也是）、在命令窗口中查询；
• 查看映射 / 设置，「查看更多」里有统计、段、分片、恢复、磁盘占用、字段使用统计、生命周期、健康；
• 构建语句：查询、聚合、计数、新增 / 更新 / 删除文档、批量写入、按查询更新 / 删除、重建索引、添加字段、修改设置——按映射挑字段生成一段请求，追加到这个数据源的命令窗口末尾并选中；
• 复制名称、添加别名；导入数据（CSV / TSV / JSON / NDJSON）、复制到其他数据源（映射、设置、数据）、克隆索引；
• 索引维护：刷新、刷盘、清除缓存、强制合并；打开 / 关闭索引；
• 清空数据（_delete_by_query 全部文档）、删除索引：都要输入索引名确认。

字段：object、nested、多字段可以展开；图标按类型着色（keyword 蓝、text 紫、数字橙、日期黄）。右键：复制完整路径、按此字段查询、字段统计（数值 extended_stats、keyword terms、text significant_text、日期按天分桶，生成到命令窗口）。

数据源的右键菜单：打开 / 新建命令窗口、新建 .edql / .esql 文件、建立 / 断开连接、编辑、复制、测试连接、删除（只删本地保存的连接信息）、集群概览、集群信息（健康、统计、设置、分片、未分配分片原因、任务、插件、当前用户）、新建索引、上移 / 下移。

工具栏：搜索框（筛选已加载的节点）、全部刷新、全部折叠、精简折叠（只收起索引和字段），「更多」里是配置文件、显示系统索引（. 开头）、日志。

连接状态

仿 DBeaver：对数据源发成功过请求就算已连接，图标右下角带绿点。「断开连接」停止它正在执行的请求、关掉 SSH 隧道、丢掉元数据缓存，树上收起。

EDQL

语法速查

# 连接（可选，写在开头）：不写就用命令窗口 / 文件绑定的数据源，写了覆盖它
HOST http://127.0.0.1:9200
Username "elastic"
Password "changeme"
Timeout 5000

# 请求：跟 Kibana Dev Tools 一样
GET _cat/indices?v&s=index

POST my-index/_search
{
  "query": { "match": { "title": "hello" } },
  "size": 10,          # 允许尾逗号和 # 注释
}

# 变量：路径里用 $名字，JSON、参数里直接写名字
var index = "my-index"
var size = 10 * 2
POST $index/_search
{ "size": size }

# 请求的响应赋给变量，用点号或 jq（JsonPath）取值
var health = GET _cluster/health
println(health.status)
var keys = jq(health, "$.status")

# 函数：按参数个数重载，不带引号的键取同名变量的值
function term2(field, value) {
  return { "term": { field: value } }
}
function search(index, q = "*") {
  POST $index/_search
  { "query": { "query_string": { "query": q } } }
}
search("logs")

# 循环、条件、map
for (i in ["a", "b"]) {
  GET $i/_count
}
var ids = [1, 2, 3].map{ it -> { return it * 10 } }
if (length(ids) > 2) { println("many") } else { println("few") }

# 多个请求体拼成 NDJSON
POST _bulk
{"index": {"_index": "a", "_id": "1"}}
{"title": "x"}

# 三引号字符串（painless 脚本）
POST my-index/_update_by_query
{ "script": { "source": """ctx._source.n += 1""" } }

# 画图：带 $schema 的对象用 Vega-Lite 画
var data = POST logs/_search
{ "size": 0, "aggs": { "d": { "date_histogram": { "field": "@timestamp", "calendar_interval": "1d" } } } }
plotline(data, "aggregations.d.buckets", "key", "doc_count")

要点（跟 EDQL 一致）：

• 方法只认大写：GET POST PUT DELETE HEAD（另外认 PATCH）；路径可以省略开头的 /，里面的中文、空格自动编码；方法后面紧跟的 { } / [ ]（可以换行）是请求体，多个时拼成 NDJSON（_bulk / _msearch 只给一个数组时每项一行），GET / DELETE / HEAD 只取第一个（_msearch 除外）；POST / PUT 自动去掉空的 "query": {}；
• 文件头关键字大小写敏感：HOST KIBANA_HOST Authorization Username Password ApiKeyId ApiKeySecret ApiSessionToken AWSRegion AWSProfile Timeout（毫秒）；文件头按位置先后生效，只执行一条语句时用的是它前面的文件头；
• HOST / KIBANA_HOST 跟绑定的数据源地址相同时还是这个数据源（只读、账号、SSH 照旧）；指向别的地址时连接只用文件头和地址里给的认证，数据源的账号、请求头、SSH、代理都不带过去；指到某个只读数据源的地址时同样只读；
• return 后面换行就是不带值（跟 JS 一样）；
• 注释只有 #；+ 对数字相加、对字符串拼接、对对象合并、对数组连接；
• 4xx / 5xx 的响应照常显示，不中断后面的语句；脚本出错（找不到变量、语法错误……）停在出错的地方，编辑器里标出位置。

比 EDQL 多的：比较和逻辑运算（== != < > <= >= && || !）、if / else、点号取值和下标（res.hits.hits[0]._source）、参数默认值、路径里的 ${名字}、三引号里可以有 "。

全局变量按需求值：只执行一条请求时，它用到的变量（包括 var x = GET …）才去求值；同名变量取引用位置之前最近的那个声明。

内置函数和标准库

标准库自动导入，函数名和参数跟 EDQL 自带的库一样：

• 集群：clusterInfo() clusterHealth() clusterStats() clusterSettings() nodeStats() indexStats() currentStats() analyze(analyzer, text)；
• 查询片段：term terms exists gt gte lt lte range wildcard match match_bool_prefix match_phrase match_phrase_prefix multi_match query_string nested order；
• 聚合片段：termsAggs(f) termsAggs(f, size) termAggs termsAgg cardinality sum max avg min dhs(field, interval[, tz]) mfn；
• 图表（Vega-Lite）：vschema yvschema encoding encodingWithData lineencoding barencoding areaencoding textencoding textlayer ruleencoding plotline plotbar plotarea plotmetric plotpercentiles concatlayers vegaop mark filter aggrField。

脚本里定义同名同参数个数的函数会覆盖标准库的。import "lib.edql" 导入别的文件里的函数和变量（相对路径、绝对路径、file://、http(s):// 都行）。

命令窗口

数据源右键「打开命令窗口」（或行尾按钮），在编辑区打开，标签名是 数据源 · 名字。每个数据源可以有多个命令窗口（「新建命令窗口」），内容每隔几秒写回 conf.yaml，下次打开原样恢复。还可以新建 SQL 窗口：写 Elasticsearch SQL（OpenSearch 自动换成 _plugins/_sql），SELECT 没写 LIMIT 时补上（设置 esStudio.sql.defaultLimit）。

编辑器：

• 高亮（方法分色、路径、$变量、函数调用、键名）、彩色括号、括号匹配、自动补括号引号、折叠、查找替换、多光标；
• 行号旁的 ▶：执行那一条顶层语句（请求、函数调用、for、if）；
• 联想：方法后面是接口路径（内置 ES 接口目录），{index} 处是集群里的索引、别名、数据流，? 后面是常用参数；请求体里按 JSON 位置给 DSL 键（query、bool、must、aggs、terms……），键是字段名的地方（match、term、range、sort……）和 "field": 后面给映射里的字段；"type"、"order"、"operator" 等给可选值；语句开头是关键字、方法、文件头、代码模板（search、bool、term、aggs、createIndex……，跟 EDQL 的 live templates 同名）；处处给变量和函数；
• 悬停看接口说明、函数签名、DSL 关键字说明；语法错误标红波浪线；Ctrl / ⌘+点击名字跳到定义；
• 快捷键：Ctrl / ⌘+Enter 执行光标所在的语句（选中了执行选中的，光标不在任何语句上时执行全部），Ctrl / ⌘+Shift+Enter 执行全部，Shift+Alt+F 格式化，Ctrl / ⌘+/ 注释，Ctrl+Space 联想，Ctrl / ⌘+S 立即保存。

工具栏：执行全部、执行当前、停止、格式化、复制为 curl（光标所在的请求，变量求值后的）、语法速查（?）。

函数：直接执行、收藏

行号旁的 ▶ 也出现在函数定义上：点了一个参数一个输入框问参数（数字、true / false、"字符串"、{…}、[…] 按 JSON 理解，其余当字符串，留空为 null），然后执行这个函数（跟 EDQL 1.10 的「运行函数弹参数框」一样）。

收藏函数（EDQL 的 Favorite functions）：命令窗口里把光标放在函数定义上，编辑区右键「收藏 / 取消收藏光标所在的函数」；.edql 文件里函数定义上方的 CodeLens「☆ 收藏」。收藏的函数列在数据源树「收藏的函数」里（文件里的归到文件绑定的数据源下），双击问参数后执行。

结果

结果区第一个页签是日志：每个请求一行（时间、方法 路径、耗时、状态码和小结：took、分片、命中数……），print 的内容、出错、汇总也记一行；点一行在编辑器里选中那条语句并跳到它的结果。输出页签是 print / println 打出来的文字。

后面是这次执行的结果页签：每个请求一个（函数、循环里发的也是），print 的对象数组、图表另开页签；下一次执行换成新的。一个结果有这些看法：

• JSON：格式化、行号、折叠（右边按钮全部折叠 / 展开）、Ctrl / ⌘+F 查找；大整数不丢精度；
• 表格：搜索命中（_index _id _score + _source 展平）、聚合桶、映射（字段、类型、分析器……）、SQL / ES|QL、_cat（?v 的文本也认）、对象数组。点选 / 拖选 / Shift 点选格子，点行号选整行、点表头选整列，Ctrl / ⌘+C 复制成制表符分隔的文本；选中多个格子时底部显示个数、和、平均、最小、最大、中位数；上面可以按文字查找、在「列」里选显示哪些列（复制、保存表格也只要这些列）；
• 图表（print 的 Vega-Lite）、原始响应、请求（求值后的方法、路径、请求体）、响应头；
• 性能（请求体带 "profile": true 时）：各分片的查询树、Collector、聚合的耗时，底色条是占比（50% 以上红、20% 以上橙），悬停看耗时分解；
• 评分解释（请求体带 "explain": true 时）：每条命中的评分计算树。

搜索结果的表格：

• 翻页：首页 / 上一页 / 下一页、每页条数——改请求体的 from / size 重发（不能超过第 10000 条）；
• 修改：双击格子（或 Enter / F2）改值（能解析成 JSON 的按 JSON，否则是字符串），「新增」「复制行」「删除」，「提交」用 _bulk?refresh=true 写回（update / create / delete），「撤销」放弃；只读数据源不能改。

SQL 结果有 cursor 时底部有「下一页」。

右上角：复制、在编辑器中打开（完整的响应，太大时结果区只显示开头）、导出：保存响应（JSON）、保存表格（CSV / TSV），搜索结果还可以导出全部（用 scroll 取满足条件的全部文档，CSV / NDJSON / JSON，显示进度、可以取消）。

.edql / .esql 文件

在任何地方新建 .edql 文件（或数据源右键「新建 .edql 文件」，放在 ~/.x1/es-studio/scripts/<数据源>/ 下），在 VS Code 自己的编辑器里写：

• 用哪个数据源：状态栏右下角、编辑器标题栏的数据库按钮、文件开头的 CodeLens 上选（记住每个文件的选择）；文件开头写了 HOST 时以它为准；
• 文件开头「▶ 执行全部 · 数据源」，每条可执行的顶层语句上「▶ 执行」，搜索请求上「复制 curl」，函数定义上「▶ 调用（问参数）」「☆ 收藏」；
• Ctrl / ⌘+Enter、Ctrl / ⌘+Shift+Enter 跟命令窗口一样；结果在旁边的「结果」页（跟命令窗口的结果区一样），执行出错的位置标红；
• 联想、悬停、语法检查、格式化（Shift+Alt+F，也可以只格式化选中的）、大纲、跳到定义（F12，重载的函数按参数个数跳）、查找引用（Shift+F12）、重命名（F2；$x 和 x 算同一个；函数参数、函数和 if / for 块里的 var 只在那一层；内置函数、请求体里不对应变量的键、关键字不能改名）。

.esql 文件写 SQL，语句用分号隔开，Ctrl / ⌘+Enter 执行光标所在的语句。

查看数据

双击索引（别名、数据流也行）打开数据页：

• 查询：Lucene 语法（status:active AND age:[18 TO 30]），以 { 开头时是查询 DSL（{"term": {"status": "active"}}）；排序：字段:desc, 字段2；回车或「查询」执行；条件、排序、显示的字段记在 conf.yaml 里；
• 字段：勾选要显示的列（缺省为映射里的全部字段），点表头按这个字段排序（升序 → 降序 → 不排）；可以切成 JSON 视图；
• 双击一行在右边看这条文档的 JSON，改了「保存」覆盖（带 if_seq_no，别人先改过会报冲突；拿不到版本号时先确认）；「新增」填 JSON 写入（_id 留空自动生成；填了 _id 用 _create，同 _id 已存在时报错、不覆盖）；点行号选中行（Ctrl / ⌘ 点多选）后「删除」；超过 2^53 的长整数在显示、编辑、保存、导出时都保留原样；
• 底部：总条数、耗时、翻页、每页条数、导出满足条件的全部文档（CSV / NDJSON，NDJSON 带 _routing，可以直接导回）。

集群概览

数据源右键「集群概览」：健康状态、节点数、索引数、文档数、存储、JVM 堆、活动 / 未分配分片、等待中的任务；节点表（堆、内存、CPU、负载、磁盘，超过 50% 橙、80% 红）；索引表（可以筛选、排序，点名字查看数据）。默认每 5 秒刷新，可以改间隔或暂停；页面不可见时不刷新。

导入、复制

• 导入数据（索引右键）：选文件，CSV / TSV 第一行是字段名（_id、_index、_routing 列当元数据；规整的数字按数字写、保留原文（1.10 还是 1.10），true / false、JSON 对象 / 数组按类型，007、1e5、null 这类当字符串，由 ES 按映射转换）；JSON 可以是对象数组、搜索响应（取 hits）或单个对象；NDJSON 一行一个对象（导出的 _index / _id / _routing / _source 格式也认），本身就是 _bulk 格式（动作行 + 文档行）的原样发。选「写入（index）」「新建（create）」或「按文件里的 _index」，每批 1000 条用 _bulk 写入，显示进度、可以取消，完了报成功 / 失败条数；
• 复制到其他数据源（索引右键）：选目标数据源和索引名，复制映射和设置（去掉 uuid、创建时间这些带不过去的）和 / 或数据（scroll 读、_bulk 写）；目标已存在时可以追加或删除重建。

设置项与命令

设置（esStudio.*）：

命令面板（分类「ES Studio」「EDQL」）：添加数据源、打开命令窗口、新建 .edql / .esql 文件、请求历史、打开配置文件、重新加载配置、显示日志；在 .edql 文件里：执行当前语句、执行全部、停止、选择数据源、复制为 curl。

配置文件

~/.x1/es-studio/conf.yaml（目录 0700、文件 0600，密码、密钥为明文）：

version: 1
datasources:
  - id: 3f2a9c1b7e04
    name: 本地
    url: http://127.0.0.1:9200
    auth: basic                  # none | basic | apiKey | token | bearer | cookie | aws
    username: elastic
    password: changeme
  - id: 7c1d2e3f4a5b
    name: 生产（只读）
    url: https://es.example.com:9243
    auth: apiKey
    apiKey: VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==
    readonly: true
    verifyTls: false             # 自签证书
    excludeIndices: ^\.kibana.*|^\.apm.*
  - id: 9d8e7f6a5b4c
    name: AWS
    url: https://search-xxx.us-east-1.es.amazonaws.com
    auth: aws
    awsRegion: us-east-1
    awsUseDefault: true          # 用环境变量或 ~/.aws/credentials
    awsProfile: prod
    sshHost: bastion             # 可选：经 SSH 跳板机
    sshAuth: agent
consoles:                        # 命令窗口的内容
  - datasourceId: 3f2a9c1b7e04
    name: console
    text: |
      GET _cat/indices?v
  - datasourceId: 3f2a9c1b7e04
    name: sql
    kind: sql
    text: SELECT * FROM "logs" LIMIT 10;
favorites:                       # 收藏的函数：命令窗口里的（datasourceId + console）或 .edql 文件里的（file）
  - name: search
    datasourceId: 3f2a9c1b7e04
    console: console
  - name: dailyStats
    file: /Users/me/scripts/stats.edql
    datasourceId: 3f2a9c1b7e04
indexPrefs:                      # 数据页：每个索引上次的查询条件、排序、显示字段
  - datasourceId: 3f2a9c1b7e04
    index: logs
    query: level:error
    sort: "@timestamp:desc"
    fields: [message, level, "@timestamp"]

跟缺省值一样的字段不写。可以手工编辑，保存后插件自动重新读取（等 300 毫秒没有新改动再读）。写回时先写临时文件再改名；不认识的顶层键原样保留；缺 id、url 的数据源忽略并记进日志；无法解析的文件改名为 conf.yaml.broken-<时间>，不会被覆盖。

请求历史在 ~/.x1/es-studio/history.jsonl，.edql 文件绑定的数据源记在 VS Code 的全局状态里。

限制

• 不做 EDQL 的 AI 功能（自然语言生成 DSL、解释、翻译成代码），「复制为 curl」保留；不做拖拽式的 Visual Editor（用「查看数据」页）；导入导出不支持 Excel；
• AWS 凭证只认密钥、环境变量和 ~/.aws/credentials / config 里的 profile，不支持 SSO、assume role、实例元数据；
• SSH 隧道认 ~/.ssh/config 里的 HostName、Port、User、IdentityFile，不支持 ProxyCommand / ProxyJump；
• 翻页最多到第 10000 条（index.max_result_window），更多的用 search_after 或「导出全部」。

开发

npm install
npm run compile          # 开发构建（扩展 + 编辑器 + Vega 图表）
npm run watch            # 监听构建（F5 调试用）
npm run check-types      # 类型检查（扩展 + webview）
npm test                 # 构建后跑全部：基础模块、HTTP 客户端（假 ES）、EDQL 语言（词法 / 语法 / 解释器 / 联想 / 格式化）、
                         # JsonPath、符号（定义 / 引用 / 重命名）、结果处理（翻页 / 提交 / curl）、SSH 隧道、HTTPS 与代理、
                         # webview 页面、审查问题的回归、扩展激活
npm run package          # 类型检查 + 生产构建
./build.sh               # 打包 VSIX（也可以 npm run vsix）
npm run dev:link         # 把本仓库软链到 ~/.vscode/extensions，重载窗口即生效（dev:unlink / dev:status / dev:check）
python3 scripts/render-icon.py   # 改了 media/icon.svg 后重新生成 media/icon.png（仅 macOS，借用无头 Google Chrome 渲染）
ES_URL=http://127.0.0.1:9200 node .test-out/real.js   # 对着真的集群跑一遍（会建删 es_studio_test_a、edql_demo 索引；ES_REPO=目录 时测快照）

源码结构：