日志服务兼容 Elasticsearch 接口

一、操作场景

日志服务的兼容接口基于 Elasticsearch 7.10版本。

二、前提条件

日志需开启索引才能使用对应的 DSL，详情请参见索引配置。

三、访问方式

·外网地址：https://${region}.cls.tencentcs.com/elasticsearch/

·内网地址：https://${region}.cls.tencentyun.com/elasticsearch/

其中${region}为地域简称，请使用日志主题所在的地域。

接口采用 Basic Auth 进行鉴权，将 API 密钥中的 SecretId 及 SecretKey 分别作为 username 及 password。

注意：说明：

注意：建议你单独创建一个子账号，使用该账号的 SecretId 及 SecretKey。该账号仅授予如下接口权限即可，配置方式请参见子账号授权。

注意：{ "version": "2.0", "statement": [ { "effect": "allow", "action": [ "cls:SearchLog" ], "resource": [ "*" ] } ]}

四、兼容接口

GET /${topic_id}/_searchPOST /${topic_id}/_searchGET /${searchview_id}/_searchPOST /${searchview_id}/_searchPOST /${topic_id}/_msearchPOST /${searchview_id}/_msearchPOST /_msearchGET /${topic_id}/_mappingGET /${searchview_id}/_mappingPOST /${topic_id}/_field_capsPOST /${searchview_id}/_field_caps

其中：

·${topic_id}：日志主题 ID，相当于 Elasticsearch 中的 index，可在日志主题列表页面中获取，仅可填写一个主题 ID。如需同时查询多个主题，请使用${searchview_id}。

·${searchview_id}：查询视图 ID，一个查询视图中可包含多个主题，需通过 API 提前创建好查询视图。

注意：所有请求中，请添加 Header X-CLS-ES-Protocol-Version: v1。

五、通用参数

DSL 语法	说明
from	分页起始偏移量，指定从第几条数据开始返回，配合 size 使用，使用 from + size 总计最大可查询1万条数据。
size	分页返回的文档数量，控制当前页面显示多少条记录。
sort	指定字段进行排序，用作排序的字段需开启索引，且需在索引配置中开启统计。
track_total_hits	是否准确统计匹配的总文档数，默认最多精确统计到10000。

六、查询 DSL

以下 DSL 语法所涉及字段需在索引配置中开启索引。

DSL 语法	说明
bool	组合多个查询条件。
filter	必须满足的过滤条件。
should	可选匹配条件，作用类似 OR。可配合 minimum_should_match 指定至少需要满足多少个 should 条件。
minimum_should_match	指定 bool.should 中至少需要满足的条件数量。例如设置为 1，表示至少满足一个 should 条件。
must	必须满足的条件。
must_not	必须不满足的条件。
match	全文检索。
term	匹配单个值。
terms	匹配多个值（类似 SQL 的 IN）。
range	范围查询（数值等）。
match_all	查询全部文档。
multi_match	在多个字段上做全文检索。
match_phrase	短语匹配，要求词序一致。
exists	判断字段是否存在或非空。
ids	按文档 ID 查询。
prefix	前缀匹配。
wildcard	通配符匹配（*、?），不支持以通配符开头。
query_string	支持 Lucene 语法的高级查询。
regexp	正则匹配。
search_after	基于上一页排序值进行深度分页。

七、聚合 DSL

以下 DSL 语法所涉及字段需在索引配置中开启索引，且需在索引配置中开启统计。

DSL 语法	说明
avg	计算数值字段的平均值，例如统计商品平均价格。
sum	计算数值字段的总和，例如统计单日总销售额。
max	获取数值字段的最大值，例如查找最高用户积分。
min	获取数值字段的最小值，例如查找最低商品库存。
value_count	统计字段值的个数，例如统计订单号数量。
percentiles	计算百分位数，用于分析数据分布，例如统计95%的请求响应时间在多少毫秒以内。
cardinality	近似去重计数，例如统计独立访客数 UV。
top_hits	获取每个分组中排序靠前的几条文档，例如查看每个分类下销量最高的3个商品。
terms	按字段值分组，类似 SQL 的 GROUP BY，例如按商品分类统计数量。
filter	按一个过滤条件筛选文档后再统计，例如只统计已支付的订单。
filters	按多个过滤条件分别分组统计，例如分别统计已支付和未支付的订单数。
range	按自定义数值区间分组，例如按价格0 – 100、100 – 500分别统计商品数。
date_range	按自定义日期区间分组，例如分别统计今年和去年的订单量，仅支持 @timestamp 字段。
histogram	按固定数值间隔分组，例如每100元一个区间统计商品数。
date_histogram	按固定时间间隔分组，例如按天、周或月统计订单量，仅支持 @timestamp 字段。

八、字段映射

Elasticsearch	CLS	说明
@timestamp	__TIMESTAMP__	查询语句中指定了@timestamp 字段时，实际查询的是 CLS 中的 __TIMESTAMP__ 字段。

九、查询示例

查询2026-06-09T07:38:04.240 ～ 2026-06-09T07:53:04.240时间范围（ UTC 时区）中，level 为 WARNING 的前10条日志：

curl -X POST "https://ap-guangzhou.cls.tencentcs.com/elasticsearch/34373f59-b5cc-4a54-902a-4a98cade60ea/_search" \\ -H "Content-Type: application/json" \\ -H "X-CLS-ES-Protocol-Version: v1" \\ -u AKIDxxxxxxxxxxxxxxxxxxxxxxxxxx:B9xxxxxxxxxxxxxxxxxxxxxxx \\ -d '{ "track_total_hits": false, "from": 0, "size": 10, "sort": [ { "@timestamp": { "order": "desc" } } ], "query": { "bool": { "filter": [ { "match": { "level": "WARNING" } }, { "range": { "@timestamp": { "gte": "2026-06-09T07:38:04.240Z", "lt": "2026-06-09T07:53:04.240Z" } } } ] } } }'

十、聚合示例

查询 2026-06-09T07:38:04.240 ～ 2026-06-09T07:53:04.240 时间范围（ UTC 时区）包含 user-service 关键词的日志，并按照 level 分组统计日志条数：

curl -X POST "https://ap-guangzhou.cls.tencentcs.com/elasticsearch/34373f59-b5cc-4a54-902a-4a98cade60ea/_search" \\ -H "Content-Type: application/json" \\ -H "X-CLS-ES-Protocol-Version: v1" \\ -u AKIDxxxxxxxxxxxxxxxxxxxxxxxxxx:B9xxxxxxxxxxxxxxxxxxxxxxx \\ -d '{ "size": 0, "query": { "bool": { "filter": [ { "multi_match": { "type": "best_fields", "query": "user-service", "lenient": true } }, { "range": { "@timestamp": { "gte": "2026-06-09T07:38:04.240Z", "lt": "2026-06-09T07:53:04.240Z" } } } ] } }, "aggs": { "level_distribution": { "terms": { "field": "level", "size": 100, "min_doc_count": 1 } } } }'

十一、兼容 Kibana

详细说明参见通过 Kibana 使用 CLS。

日志服务 兼容 Elasticsearch 接口