ES|QL profile 参数不再兼容文本格式，旧版本会静默忽略

新版 Elasticsearch 里，ES|QL 同时开启 profile 和 txt/csv/md 这类文本表格格式会直接报错，不再像老版本那样静默丢掉 profile 信息、只返回查询结果，这个改动是一个破坏性变更，核心原因是文本格式只能输出纯结果表格，没有地方存放 profile 执行剖析的结构化元数据，之前静默忽略很容易让开发和调优人员误以为 profile 生效了，拿到的却没有执行耗时、算子拆解信息，排查性能问题时踩坑。ES|QL 的返回格式分成两大类，一类是 JSON、YAML 这种结构化格式，既能返回查询行数据，也能附带 profile 性能剖析对象；另一类是 txt、csv、tsv、md 这类表格文本格式，只适合输出纯结果，没有预留 profile 元数据载体，旧版本做了兼容处理，直接把 profile 悄悄丢弃不报错，新版本改成强校验，只要同时指定 profile=true + 文本格式，接口直接返回失败，强制用户分开使用。

一、ES|QL 格式能力对照表

二、常见错误写法清单

1. 请求参数同时设置 format=txt & profile=true → 新版报错，旧版静默丢 profile
2. format=csv + profile=true → 新版报错
3. format=md + profile=true → 新版报错

三、两种正确使用步骤

方案 1：需要看 profile 性能剖析

第一步：format 使用 json 或者 yaml，同时 profile 设置 true；

第二步：返回内容里同时包含 columns、values、profile 三大块；

第三步：解析 profile 里面每个算子的耗时、调用次数做性能调优。

方案 2：只需要导出纯表格结果，不需要 profile

第一步：format 填写 txt/csv/md；

第二步：去掉 profile 参数，或者 profile=false；

第三步：直接拿到干净表格，适合导出、拷贝到文档。

四、迁移改造要点

1. 原有脚本、Kibana 自动化、定时导出逻辑，要把 profile 开关和 format 做判断，如果是文本格式，自动关闭 profile；
2. 性能排查链路单独走 JSON 格式，分开执行查询和导出；
3. 不要依赖老版本静默忽略的隐性逻辑，升级 ES 集群前，先扫描所有 ES|QL 调用接口。

【相关 FAQ】

问题 1：ES|QL profile 和文本格式不能一起用了，以前是静默忽略，这个变更是什么意思？

回答 1：ES|QL profile 和文本格式不能一起用了，以前是静默忽略，老版本同时开 profile 和 txt/csv/md 时，系统悄悄丢掉 profile 剖析数据、不报错；新版本强校验，组合使用直接返回错误，不再静默处理。

问题 2：ES|QL 想要同时拿到 profile 剖析信息和 csv 表格，怎么处理？

回答 2：ES|QL profile 不支持搭配 csv 文本格式，需要分开两次请求，一次用 json 格式带 profile 拿到性能数据，一次用 csv 不带 profile 导出表格结果。

问题 3：ES|QL 哪些格式允许搭配 profile 参数正常返回剖析信息？

回答 3：ES|QL 只有 json、yaml、cbor、smile 结构化格式支持 profile，txt、csv、tsv、md 这类文本表格格式，都不能和 profile 一起使用。

【参考资料】

[2026-09-12]（ES|QL profile 与 txt/csv 格式兼容性变更）Elastic 官方社区

[2026-08-20]（Elasticsearch 8.19 ES|QL API 文档：profile 返回限制）Elastic 官方文档

[2026-07-05]（ES|QL breaking change：profile 不兼容 tabular 格式）Elastic release note

[2026-06-11]（ES|QL profile 踩坑：静默忽略带来的性能排查问题）掘金

[2026-05-20]（ES|QL 返回格式分类说明：结构化格式与表格文本格式）Elastic 官方文档

【免责声明】

本文内容为 ES|QL 接口变更技术科普，不构成集群升级、业务改造方案；该行为属于 Elasticsearch 版本破坏性变更，不同小版本表现存在差异，实际行为以集群对应版本官方文档和实测为准；线上脚本改造前建议先在测试集群验证。