cls_search_log
Search and analyze logs in Tencent Cloud Log Service using CQL queries and SQL pipelines to filter, aggregate, and extract insights from log data.
Instructions
检索分析 CLS 日志。支持 CQL 检索和 SQL 管道分析。
CQL 语法速查
CQL (CLS Query Language) 是 CLS 自研的检索分析语法，语句结构为：[检索条件] | [SQL 语句]。
检索条件用于过滤日志，SQL 用于统计分析。不需要分析时可省略 | 及 SQL 部分。
检索语法
键值检索:
status:404、level:ERROR（字段值包含该词）全文检索:
error、timeout（全文中包含该词）短语检索:
"connection timeout"或'user_name:"bob"'（精确短语，支持通配符如"/var/log/acc*.log"）逻辑操作符:
AND、OR、NOT（不区分大小写，AND 优先级高于 OR）分组:
level:(ERROR OR WARNING) AND pid:1234数值比较:
status:>400、status:>=400、status:=200、latency:<100模糊匹配:
host:www.test*.com（*匹配零到多个字符，不支持前缀模糊如*test）字段存在性:
key:*（字段存在）、key:""（字段存在但值为空）转义:
body:user_name\:bob（特殊字符用\转义）
SQL 分析（检索条件 | SQL，无需 FROM 和分号）
字符串用单引号
''，字段名冲突用双引号""* | SELECT COUNT(*) AS total* | SELECT status, COUNT(*) AS cnt GROUP BY status ORDER BY cnt DESC默认返回 100 行，LIMIT 最大 100 万行
CLS 扩展函数
histogram（时间分桶）:
histogram(__TIMESTAMP__, interval 1 hour)— 直接传 LONG 型，自动 UTC+8time_series（时序补全）:
time_series(__TIMESTAMP__, '5m', '%Y-%m-%d %H:%i:%s', '0')— 必须 GROUP BY + ORDER BY，不支持 DESC，分钟用 %icompare（同环比）:
compare(count(*), 86400)— 返回数组下标从 1 开始，86400=日/604800=周IP 地理:
ip_to_province/city/country/provider(ip)百分位:
APPROX_PERCENTILE(field, 0.99)
关键注意
CQL 是 CLS 推荐语法（SyntaxRule=1），相比 Lucene 更简便，特殊字符限制更少
CQL 中多个分词默认为 AND 关系（Lucene 默认为 OR）
__TIMESTAMP__是 bigint 毫秒时间戳，from_unixtime要除 1000脏数据用
try_cast代替cast时区：histogram/time_series 传 LONG 型自动 UTC+8，其他日期函数默认 UTC+0，需手动加 8 小时
参数说明
topic_id: 日志主题 ID（必填）
query: CQL 检索语句（必填），如
level:ERROR或* | SELECT COUNT(*) as cntstart_time: 起始时间，Unix 时间戳（毫秒）
end_time: 结束时间，Unix 时间戳（毫秒）
limit: 返回条数，默认 100，最大 1000（仅对原始日志有效，SQL 分析不受此限制）
context: 翻页游标，首次查询无需传入，从上次返回结果获取
sort: 排序方式，asc（升序）或 desc（降序，默认）
注意事项
⏰ start_time/end_time 为毫秒时间戳，请先调用 cls_convert_time 工具转换，不要手动计算
💡 编写 SQL 分析语句前，建议先调用 cls_describe_index 获取索引配置，确认字段名称和类型
❌ CQL 执行报错时，可调用 cls_describe_search_syntax 获取 CLS 完整扩展语法参考文档
region: 地域（可选），如 ap-guangzhou、na-ashburn，不传则使用默认地域
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| topic_id | Yes | ||
| query | Yes | ||
| start_time | Yes | ||
| end_time | Yes | ||
| limit | No | ||
| context | No | ||
| sort | No | desc | |
| region | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |