短语查询（位置索引版）-日志服务(SLS)-阿里云帮助中心

位置索引记录词元的顺序和位置，用于在索引层完成短语匹配。开启后，短语查询可以返回精确的日志结果和直方图，无需扫描候选日志。

重要

位置索引目前处于灰度阶段，免费使用，仅向白名单用户开放。如需使用，请提交工单申请开通。

前提条件

已通过工单为目标 LogStore 开通位置索引白名单。
目标 LogStore 已配置全文索引或 text 类型的字段索引。具体操作，请参见创建索引。

索引覆盖范围

位置索引是 LogStore 级开关，沿用现有索引的大小写敏感、中文分词和分词符配置，不会扩大原有索引的覆盖范围。开启后，系统会为已有的可分词文本索引记录词元位置，包括全文索引、text 类型字段索引，以及 JSON 类型字段索引中按 text 类型建立索引的叶子字段；未建立文本索引的字段不会生成位置索引。

例如，未开启全文索引，仅为 message 配置了 text 类型字段索引，并为 JSON 字段 payload 中的 error 叶子字段配置了 text 类型索引，则只有 message 和 payload.error 会建立位置索引。

开启位置索引

重要

位置索引仅对新写入或重新构建索引的数据生效，历史数据不会自动生成位置索引。查询范围内的数据全部具备位置索引时，才会使用增强版短语查询。

通过控制台开启

登录日志服务控制台。
进入目标 LogStore 的查询和分析页面。
选择查询分析属性 > 属性。
打开页面底部的开启位置索引开关，然后单击保存。配置约一分钟后生效。

通过 SDK 开启

以下以 Python SDK 为例，其他语言 SDK 的操作方式类似。安装 Python SDK：

pip install -U aliyun-log-python-sdk

更新索引会覆盖完整配置，因此需要先读取现有配置，再增加顶层配置项 "position_index": true：

from aliyun.log import LogClient

class IndexConfigJson(dict):
    def to_json(self):
        return self

client = LogClient(
    "your-endpoint",
    "your-access-key-id",
    "your-access-key-secret",
)

project = "your-project"
logstore = "your-logstore"

config = client.get_index_config(project, logstore).get_body()
config.pop("lastModifyTime", None)
config["position_index"] = True
client.update_index(project, logstore, IndexConfigJson(config))

使用短语查询

短语查询使用 # 作为标识，并使用半角双引号包裹短语。

查询方式	语法	示例
全文短语查询	`#"短语"`	`#"connection reset"`
字段短语查询	`字段名:#"短语"`	`message:#"connection reset"`

短语查询匹配分词后的词元序列及相邻位置，不是逐字符匹配。例如 connection reset by peer 匹配 #"connection reset"，connection was reset by peer 不匹配。

能力对比

位置索引不改变短语查询语法，但增强了查询能力：

对比项	未开启位置索引	开启位置索引
匹配方式	读取候选日志后逐条校验	在索引层直接完成精确匹配
结果翻页	仅支持连续翻页	支持正常翻页和随机跳转
直方图	按关键词候选结果统计	按短语精确结果统计
条件组合	不支持搭配 `NOT` 或模糊查询条件	支持与 `AND`、`OR`、`NOT` 和模糊查询条件组合
查询分析	不支持分析语句	支持分析语句
SPL	不支持与 SPL 组合	支持与 SPL 组合

例如：

not #"connection reset"
#"connection reset" and host:api-*
#"connection reset" | SELECT level, count(*) GROUP BY level
#"connection reset" | where level = 'ERROR'

限制与优化建议

位置索引只对新写入或重新构建索引的数据生效。历史数据不会自动生成位置索引。
查询范围内的数据全部具备位置索引时，才会使用增强版短语查询。只要包含未生成位置索引的数据，本次查询整体使用非位置索引处理路径。
开启位置索引会增加索引构建和存储开销，增量主要取决于词元的出现次数。
高频词元和较长时间范围会增加位置数据读取量。建议缩小时间范围、增加字段条件或使用更具体的短语。
如果 LogStore 同时配置了全文索引和 text 类型的字段索引，并且两者的分词配置不同，全文短语查询 #"短语" 仅按全文索引的分词结果匹配。对于只能通过字段索引命中的内容，请使用字段短语查询 字段名:#"短语"。
通过 API 或 SDK 更新索引时，应保留原有索引配置，避免完整覆盖导致已有配置丢失。