OpenSearch 查看分词与词频技术指南

1 _analyze API

不依赖已有文档，直接测试一段文本会被拆成哪些 token。不返回词频统计，如果同一个词出现多次，需要自己统计 token 数组中的重复项。

用法 1：指定 analyzer 测试任意文本

POST /{index}/_analyze
{
  "analyzer": "ik_smart",
  "text": "OpenSearch向量搜索性能优化，向量搜索需要合理配置分片"
}

返回结果（节选）：

{
  "tokens": [
    {"token": "opensearch", "position": 0, ...},
    {"token": "向量", "position": 1, ...},
    {"token": "搜索", "position": 2, ...},
    ...
    {"token": "向量", "position": 5, ...},  // "向量" 第 2 次出现
    {"token": "搜索", "position": 6, ...}   // "搜索" 第 2 次出现
  ]
}

"向量"、"搜索" 各出现 2 次（position 1/5、2/6），手动统计即可得到词频。

用法 2：指定 field，使用该字段 mapping 中配置的分析器

POST /{index}/_analyze
{
  "field": "content",
  "text": "我们完成了Series A融资，融资金额创新高"
}

比手动指定 analyzer 更贴近真实索引行为——会自动读取该字段 mapping 里配置的 analyzer（如自定义的 ik_english_mixed）。

2 Term Vectors API

直接返回 term_freq 字段，是获取单文档精确词频的最佳方法。支持查看词在文档中的出现位置（position）和字符偏移（offset）。

基本用法：查询已索引文档

GET /{index}/_termvectors/{doc_id}
{
  "fields": ["text"],
  "term_statistics": true,
  "positions": true,
  "offsets": true
}

绕过方案：Artificial Document（实时生成，不依赖 mapping 配置）

不传 _id，用 doc 字段提供虚构文档内容，OpenSearch 会实时分词并计算词频：

POST /{index}/_termvectors
{
  "doc": {
    "content": "我们完成了Series A融资，融资金额创新高"
  },
  "field_statistics": true,
  "fields": ["content"],
  "offsets": true,
  "positions": true,
  "term_statistics": true
}

返回结果（节选）：

{
  "term_vectors": {
    "content": {
      "field_statistics": {"sum_doc_freq": 0, "doc_count": 0, "sum_ttf": 0},
      "terms": {
        "融资": {
          "term_freq": 2,
          "tokens": [
            {"position": 4, ...},
            {"position": 5, ...}
          ]
        },
        "我们": {"term_freq": 1, ...},
        ...
      }
    }
  }
}

term_freq 直接给出词频，"融资" = 2 次。

正确方案（生产环境）：在 mapping 中开启 term_vector 存储

要让已索引的真实文档支持直接查询词频（无需 artificial document），需要在字段 mapping 加上 term_vector 参数：

PUT /my-index
{
  "mappings": {
    "properties": {
      "message": {
        "type": "text",
        "term_vector": "with_positions_offsets",
        "fields": {
          "keyword": {"type": "keyword", "ignore_above": 256}
        }
      }
    }
  }
}

term_vector 支持以下值：

Filter 参数：精确控制返回的 Term

Term Vectors API 支持 filter 对象来过滤返回的 token：

POST /{index}/_termvectors/{doc_id}
{
  "fields": ["content"],
  "term_statistics": true,
  "filter": {
    "max_num_terms": 10,
    "min_term_freq": 2,
    "min_word_length": 2
  }
}

3 Terms Aggregation

统计整个索引范围内某个字段的文档频率分布（doc_count = 包含该词的文档数，不是词在单文档内的出现次数）。

前提：字段必须可聚合

text 类型字段默认不支持聚合，直接使用会报错：

// 错误信息：
Text fields are not optimised for operations that require per-document 
field data like aggregations and sorting, so these operations are 
disabled by default. Please use a keyword field instead.

两种解决方式：

基本用法：对 keyword 子字段聚合

POST /{index}/_search
{
  "size": 0,
  "aggs": {
    "top_terms": {
      "terms": {
        "field": "payload.category.keyword",
        "size": 15
      }
    }
  }
}

返回结果示例：

{
  "aggregations": {
    "top_terms": {
      "buckets": [
        {"key": "short_term", "doc_count": 314},
        {"key": "project", "doc_count": 266},
        {"key": "experience", "doc_count": 192},
        {"key": "environment", "doc_count": 109},
        {"key": "decision", "doc_count": 42},
        {"key": "preference", "doc_count": 24}
      ]
    }
  }
}

高级用法：配合 query 筛选范围

POST /{index}/_search
{
  "size": 0,
  "query": {
    "range": {
      "@timestamp": {
        "gte": "2026-07-01",
        "lt": "2026-07-25"
      }
    }
  },
  "aggs": {
    "top_terms": {
      "terms": {
        "field": "action.keyword",
        "size": 20,
        "order": {"_count": "desc"}
      }
    }
  }
}