帮你快速理解、总结文档立即下载
文档中心>日志服务>操作指南>检索分析（日志主题）>兼容 Elasticsearch 接口

兼容 Elasticsearch 接口

最近更新时间：2026-10-28 14:08:01
我的收藏

本页目录：

操作场景

Elasticsearch 是一个开源的分布式搜索和分析引擎，日志服务兼容其部分接口。当您从 Elasticsearch 迁移到日志服务时，如果您之前使用的一些 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}/_search
POST /${topic_id}/_search
GET /${searchview_id}/_search
POST /${searchview_id}/_search
POST /${topic_id}/_msearch
POST /${searchview_id}/_msearch
POST /_msearch
GET /${topic_id}/_mapping
GET /${searchview_id}/_mapping
POST /${topic_id}/_field_caps
POST /${searchview_id}/_field_caps
其中：
${topic_id}：日志主题 ID，相当于 Elasticsearch 中的 index，可在 日志主题列表 页面中获取，仅可填写一个主题 ID。如需同时查询多个主题，请使用${searchview_id}。
${searchview_id}：查询视图 ID，一个查询视图中可包含多个主题，需通过 API 提前创建好查询视图。
注意：
所有请求中，请添加 Header X-CLS-ES-Protocol-Version: v1。

兼容 DSL

通用参数

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。

中国站