CLS 索引策略最佳实践：全文索引与键值索引的选择之道

摘要：

索引是 CLS 检索分析的前提，分为全文索引和键值索引两种类型。合理的索引配置既能满足查询需求，又能有效控制成本。本文详解两种索引的工作原理、适用场景和优化策略，帮助用户制定高效的索引方案。

一、索引在日志检索中的核心作用

在使用 CLS 进行日志检索和分析之前，必须先开启索引配置。CLS 作为腾讯云提供的一体化可观测 SaaS 服务，支持日志（Log）和指标（Metric）数据的采集、存储、检索分析、加工投递、可视化仪表盘和告警，并已上线 AI 助手（支持自然语言生成检索分析语句）和 MCP Server（让大模型直接查日志）等智能化能力。索引的本质是将原始日志按照指定规则切分为多个片段（即分词），并对这些分词建立倒排索引。这个过程类似于书籍的目录索引，通过预先整理好的索引结构，系统可以在海量日志中快速定位到包含特定关键词的记录。

在 CLS 控制台中，索引配置的入口位于日志主题管理页 → 索引配置页签。首次开启时推荐使用"推荐配置"一键完成自动设置。CLS 默认分词符为 @&?|#()='",;:<>[]{}/ \n\t\r\\，覆盖了绝大多数编程和日志场景中的分隔符号。

没有开启索引的日志数据只能被存储和投递，无法进行检索和分析。索引配置生效后约一分钟即可开始检索，从日志上报到可被检索分析的延迟小于1分钟。需要注意的是，索引规则的变更仅对新写入的日志生效，已有数据不会更新索引——如需更新已有数据，需使用 CLS 的重建索引功能（单日志主题同时仅允许运行一个重建任务，所选时间范围对应日志写流量不超过5TB）。

二、全文索引详解

2.1 工作原理

全文索引将原始日志整体切分为多个分词进行索引构建。检索时直接通过关键词进行搜索，系统会在所有已索引的分词中查找匹配项。例如输入 error 作为查询条件，系统会返回所有包含 error 这个分词的日志。

全文索引的配置相对简单，在 CLS 控制台索引配置 → 全文索引中启用即可。系统会使用默认分词符 @&?|#()='",;:<>[]{}/ \n\t\r\\ 对日志进行切分。CLS 还支持高级设置中的"内置保留字段包含至全文索引"和"元数据字段包含至全文索引"选项，可灵活控制 __FILENAME__、__SOURCE__、__HOSTNAME__ 及 __TAG__.* 等系统字段是否参与全文检索。

2.2 关键配置项

CLS 全文索引提供了以下重要配置选项：

分词符决定了日志文本如何被切分成独立的分词。仅支持英文符号、\n\t\r 及转义符 \。如果某个分词长度超过 10000 个字符，系统只会为前 10000 个字符建立索引，超出部分无法被检索到，但完整的日志内容仍会被存储。

大小写敏感选项控制检索时是否区分字母大小写。例如当日志中包含 Error 而检索词为 error 时，如果开启了大小写敏感则无法匹配，关闭则可以匹配。

允许中文分词选项在日志包含中文字符且需要按中文关键词检索时必须启用。如果未开启此选项，只能通过完整的原始日志文本来查询包含中文的日志，无法使用中文关键词进行模糊搜索。

内置保留字段处理：CLS 针对 __FILENAME__（采集文件名）、__SOURCE__（源IP）、__HOSTNAME__（机器名称）三个内置字段自动创建键值索引且不产生额外费用。在高级设置中可选择这些字段是否包含至全文索引——选择"包含"时可直接全文检索 /var/log/access.log，选择"不包含"时只能通过 __FILENAME__:"/var/log/access.log" 键值方式检索。

2.3 适用场景

全文索引适合以下场景：

需要对日志内容进行自由关键词搜索的情况，例如快速定位包含特定错误信息的日志。在故障排查的初期阶段，运维人员往往不清楚具体问题出在哪个字段，全文检索可以快速缩小范围。

日志格式不固定或字段结构复杂的场景。当日志来源多样、格式不统一时，为每个可能的字段配置键值索引工作量很大，全文索引提供了一种低成本的兜底方案。

临时性的探索式查询。在进行数据分析时，分析师可能需要尝试不同的关键词组合来发现规律，全文索引的灵活性正好满足这种需求。

三、键值索引详解

3.1 工作原理

键值索引将原始日志按字段分别切分为多个分词进行索引构建。检索时基于键值方式进行精确查询。例如输入 level:error 表示检索 level 字段中包含 error 的日志。

在 CLS 控制台中配置键值索引时，需输入字段名称并选择字段类型。单个日志主题最多可添加 300 个键值索引字段（含元数据字段）。CLS 支持四种字段类型：

其中 text 和 json 类型支持通配符模糊检索但不支持范围比较；long 和 double 类型支持范围比较但不支持模糊检索。json 类型目前处于白名单阶段，需联系腾讯云开通。

此外，CLS 还内置了保留字段自动索引——__FILENAME__（文件名）、__SOURCE__（源IP）、__HOSTNAME__（机器名）、__TIMESTAMP__（日志时间戳）、__INDEX_STATUS__（索引异常状态）这五个字段会自动创建键值索引且不产生任何索引流量费用。

3.2 统计功能的开启

在 CLS 键值索引配置中，"开启统计"是一个重要选项。只有对某个字段开启了统计开关后，该字段才能在 SQL 统计分析中使用。例如要对 status_code 字段进行聚合统计（如计算各状态码的请求数量），必须在索引配置中为该字段启用统计。

开启统计不会产生额外的索引流量费用，因此 CLS 官方建议尽量多地为字段开启统计功能。需要注意的是，text 类型字段开启统计时，如果值过长仅前 32766 个字符参与统计运算；检索时每个字段仅前 1MB 的日志参与检索。

3.3 元数据索引

元数据索引本质上也是一种键值索引，区别在于字段名称以 __TAG__ 前缀标识。元数据索引通常用于按采集维度分类日志，例如按地域、按机器组等维度进行筛选。查询时使用类似 __TAG__.region:ap-beijing 的语法来过滤特定地域的日志。

在 CLS 高级设置中，可以选择元数据字段是否包含至全文索引：选择"包含"时可直接搜索 ap-beijing 匹配，选择"不包含"时只能通过 __TAG__.region:ap-beijing 键值方式检索。低频存储类型的日志主题不支持键值检索，此时若选择不包含则无法检索这些字段。

3.4 适用场景

键值索引适合以下场景：

结构化日志的精确查询。当日志已经被解析为明确的字段结构后，针对特定字段的查询使用键值索引效率更高。例如查询所有状态码为 500 的请求，使用 status_code:500 比全文检索更加精准。

需要进行 SQL 统计分析的场景。只有通过键值索引开启了统计功能的字段才能参与聚合计算。对于需要定期生成报表的业务指标监控，键值索引是必不可少的配置。配合 CLS 兼容 SQL 92 标准的 200+ SQL 函数，可以实现复杂的业务分析需求。

高基数字段的过滤。对于取值范围较大的字段（如请求 ID、用户 ID 等），全文索引可能会产生大量无意义的分词，而键值索引可以精确地对这些字段建立索引。CLS 单字段检索限制为前 1MB 日志参与检索，分词后单个词仅前 10000 个字符参与检索，超出部分虽完整存储但无法被检索到。

四、索引策略优化实践

4.1 简化索引降低成本

索引流量和索引存储费用按照未压缩的原始日志量计算，在中国大陆地区标准索引流量单价为 0.35 元/GB、标准索引存储为 0.0115 元/GB/日，在 CLS 各项费用中占比较高。因此，简化索引配置是降低使用成本的有效手段。

如果业务场景中主要进行键值查询，可以考虑关闭全文索引。CLS 官方文档明确指出"已开启全文索引时，键值索引不产生任何额外索引流量/存储费用"——这意味着关闭全文索引后，索引流量将仅根据开启了键值索引的字段长度计算，费用会大幅下降。需要注意的是，关闭全文索引后将无法直接使用关键词进行全文检索，所有查询都必须指定字段名。

在键值索引中，可以优先删除没有检索需求且字段长度较大的索引。例如某些调试信息字段或大段文本字段，如果日常查询中很少用到，就没有必要为其建立索引。text 类型字段开启统计后仅前 32766 个字符参与 SQL 运算，超出部分虽完整存储但不会被统计。

4.2 防止自动配置干扰

CLS 控制台的自动配置功能会在启用后自动将日志内的字段添加到键值索引中（包括后续新增的字段），并根据字段值自动判断类型（text/long/double）。这个功能在初期使用时很方便，但当索引配置稳定后，建议关闭自动配置。否则之前手动删除的字段可能会被重新添加回来，导致索引费用意外增加。

另外需要注意，自动配置添加字段时要求字段名称仅支持字母、数字、下划线和 -./@，且不能以下划线开头——不符合规则的字段不会自动添加，需要手动配置。

4.3 结合数据加工优化索引

对于日志量大且类型多样的场景，可以使用 CLS 数据加工功能先将原始日志按类别分发到不同的日志主题中。源日志主题可以关闭索引以避免索引费用，然后根据下游的不同需求，在各个目标主题中配置差异化的索引策略。

CLS 数据加工支持过滤、清洗、脱敏、富化、分发、结构化六种操作，单价为 0.15 元/GB。例如可以将 ERROR 级别的日志单独分发到一个主题中并配置完整的全文+键值索引，而 INFO 级别的日志分发到另一个主题中仅配置少量关键字段的键值索引。这样既保证了重要日志的可检索性，又控制了整体的索引成本。

4.4 分层索引策略与冷热存储联动

根据日志的生命周期制定分层的索引策略也是一种有效的做法。近期日志保持完整的索引配置以支持快速检索和分析，历史日志在沉降到低频存储后可以适当简化索引。

这里有一个重要的技术细节：CLS 低频存储仅支持全文索引，不支持键值索引。因此当日志从标准存储沉降到低频存储后，原有的键值索引将不再生效，只能通过全文检索方式查询。这一特性意味着：对于需要长期保留但查询频率低的历史日志，可以在沉降前将其键值索引精简至最少，因为沉降后这些配置本身也不会生效。同时低频索引流量单价为 0.10 元/GB（约为标准的 1/3），低频索引存储为 0.0025 元/GB/日（约为标准的 1/5），进一步降低了历史数据的持有成本。

五、常见误区与建议

5.1 不要为所有字段开启索引

有些用户在配置索引时倾向于将所有字段都纳入索引范围，认为这样可以获得最大的查询灵活性。但实际上，很多字段在实际使用中很少被查询，为其建立索引只会增加不必要的费用。CLS 单个日志主题最多支持 300 个键值索引字段，但实际生产中通常只需配置 10~30 个核心业务字段即可覆盖绝大多数查询场景。

建议先观察一段时间的实际查询模式——通过 CLS 控制台的检索分析页面查看常用的检索关键词和 SQL 中涉及的字段，再决定哪些字段真正需要索引。对于 CLB 访问日志、Nginx 日志等腾讯云生态产品日志，CLS 已提供预置的索引推荐配置，可直接参考使用。

5.2 全文索引和键值索引不是互斥的

两者可以并存且各有优势。全文索引提供灵活的模糊搜索能力，键值索引提供精确的字段级查询和统计分析能力。在实际应用中，通常是同时启用全文索引和部分关键字段的键值索引，形成互补。

一个典型的 CLS 索引配置组合是：保持全文索引开启以应对探索式查询 + 为核心业务字段（如 status_code、method、url、level、service_name 等）配置键值索引并开启统计。这样既能用 error timeout 这样的关键词快速定位异常日志，也能用 status_code:500 | select count(*) group by url 进行精确的聚合分析。如果担心全文索引费用过高，也可以通过高级设置排除内置保留字段和元数据字段来缩小全文索引范围。

5.3 利用 AI 助手优化查询效率

CLS 已上线 AI 助手功能，支持通过自然语言描述自动生成检索分析语句。当不确定某个字段是否配置了索引、或不知道如何编写复杂的 SQL 查询时，可以直接向 AI 助手提问。例如输入"统计过去1小时各接口状态码分布"，AI 助手会自动生成对应的检索+SQL 语句。这一能力大幅降低了索引和 SQL 的学习门槛，让团队成员无需深入理解 CLS 的索引机制也能高效完成日志分析工作。

5.4 定期审视索引配置

业务的查询需求会随时间变化，索引配置也应该随之调整。建议每隔一段时间回顾一下索引的使用情况，检查是否有长期未被使用的索引字段，或者是否有新的查询需求需要补充索引。CLS 控制台提供了索引配置的导入/导出功能，可以在多个日志主题之间复用经过验证的索引方案，确保团队内索引策略的一致性。

另外需要注意的是，修改索引配置（包括新增/编辑/删除字段、调整分词符等）仅对新写入的日志生效。如果需要更新已有数据的索引，需使用 CLS 的重建索引功能——单日志主题同时仅允许运行一个重建任务，所选时间范围对应日志写流量不超过 5TB。

想要为业务搭建 CLS 高效的检索索引体系，新用户开通即可领取 10U × 3 个月 免费资源包用于体验，首单特惠最低至 0.8 折起；新老用户购买资源包常规档位最低可享 6.3 折优惠。如需了解更多详情或领取优惠，可访问 腾讯云 CLS 产品页 及 特惠活动页。