Scenarios
Elasticsearch is an open-source distributed search and analytics engine. CLS is compatible with a subset of its APIs. When migrating from Elasticsearch to CLS, if certain Elasticsearch APIs you previously used fall within CLS's compatibility scope, you can continue to use the same APIs, reducing migration complexity.
CLS's compatible API is based on Elasticsearch version 7.10.
Prerequisites
Indexing must be enabled for logs to use the corresponding DSL. For details, see Index Configuration. Access mode
Public network address: https://${region}.cls.tencentcs.com/elasticsearch/
Private network address: https://${region}.cls.tencentyun.com/elasticsearch/
where ${region} is the region abbreviation, please use the region where the log topic is located. The API uses Basic Auth for authentication. Use the SecretId and SecretKey from the API Key as the username and password, respectively. Note:
It is recommended that you create a separate sub-account and use its SecretId and SecretKey. This account only needs to be granted permissions for the following APIs; for configuration methods, see Sub-Account Authorization. {
"version": "2.0",
"statement": [
{
"effect": "allow",
"action": [
"cls:SearchLog"
],
"resource": [
"*"
]
}
]
}
Compatible APIs
Search API
GET /${topic_id}/_search
POST /${topic_id}/_search
where ${topic_id} is the log topic ID, equivalent to the index in Elasticsearch, and can be obtained on the log topic list page. Compatible with DSL
Note:
When querying data by log time range, use the __TIMESTAMP__ field instead of the @timestamp field in Elasticsearch.
Query DSL
term and terms: The specified field must have key-value indexing enabled.
match_phrase: The specified field must have key-value indexing enabled.
range: The specified field must have key-value indexing enabled.
Aggregation DSL
terms: The specified field must have key-value indexing added and statistics enabled.
General Parameters
Pagination and Sorting: from, size, sort. Fields used for sorting must have key-value indexing added and statistics enabled.
Result Control: track_total_hits.
Example
Note:
In the example, __TIMESTAMP__ is the log time, which is a Unix timestamp in milliseconds, using range for filtering, representing the time range for querying logs.
Query logs in the time range 2026-03-31 10:26:35 to 2026-03-31 10:41:35 where reqMethod is GET.
curl -X POST "https://ap-chongqing.cls.tencentcs.com/elasticsearch/58b9496c-c6c6-48b3-xxx-50824857a13c/_search" \\
-H "Content-Type: application/json" \\
-u AKIDBFvNbcOwLWTXXXXXXXXXXXXXXXXXXXXX:bx5zf6JI3wb18XXXXXXXXXXXXXXXXXXXXX \\
-d '{
"track_total_hits": true,
"size": 10,
"query": {
"bool": {
"filter": [
{ "match": { "reqMethod": "GET" } },
{
"range": {
"__TIMESTAMP__": {
"gte": 1774923995000,
"lte": 1774924895000
}
}
}
]
}
}
}'
Query logs in the time range 2026-03-31 10:26:35 to 2026-03-31 10:41:35 containing the keyword USER in the full log text, and perform grouped statistics by resHttpCode.
curl -X POST "https://ap-chongqing.cls.tencentcs.com/elasticsearch/58b9496c-c6c6-48b3-xxxx-50824857a13c/_search" \\
-H "Content-Type: application/json" \\
-u AKIDBFvNbcOwLWTXXXXXXXXXXXXXXXXXXXXX:bx5zf6JI3wb18XXXXXXXXXXXXXXXXXXXXX \\
-d '{
"query": {
"bool": {
"filter": [
{
"multi_match": {
"type": "best_fields",
"query": "USER",
"lenient": true
}
},
{
"range": {
"__TIMESTAMP__": {
"gte": 1774923995000,
"lte": 1774924895000
}
}
}
]
}
},
"aggs": {
"http_code_distribution": {
"terms": {
"field": "resHttpCode",
"size": 100,
"min_doc_count": 1
}
}
}
}'