dense_vector 字段类型 #

dense_vector 用于保存稠密浮点向量，并通过 Lucene 原生 HNSW 索引执行近似最近邻搜索。该能力从 Easysearch 2.4.0 开始内置，不需要安装 k-NN 插件。

旧 k-NN 插件的 knn_dense_float_vector 和 knn_sparse_bool_vector 字段仍然保留，参考 K-NN 向量字段类型。两套字段和查询语法不同， 新建原生 HNSW 索引时使用本页的 dense_vector。

创建映射 #

Easysearch 2.4.0 要求显式指定 dims、index: true 和 index_options.type: hnsw：

PUT /native-hnsw-demo
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text"
      },
      "embedding": {
        "type": "dense_vector",
        "dims": 4,
        "element_type": "float",
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "hnsw",
          "m": 16,
          "ef_construction": 100
        }
      }
    }
  }
}

映射参数 #

index_options 支持以下参数：

未指定 m 和 ef_construction 时，可以使用简化写法：

"embedding": {
  "type": "dense_vector",
  "dims": 4,
  "index": true,
  "index_options": {
    "type": "hnsw"
  }
}

相似度 #

所有向量元素必须是有限数值，不能包含 NaN 或无穷值。写入向量和查询向量的维度必须与 dims 完全一致。

写入向量 #

向量直接使用 JSON 数组写入：

PUT /native-hnsw-demo/_doc/v01
{
  "title": "向量文档一",
  "embedding": [1.0, 0.0, 0.0, 0.0]
}

index、create、Bulk、Update 和 Reindex 写入都会执行相同的类型、维度和相似度约束。字段值为 null 时不会创建向量索引项。

版本和更新限制 #

• 只有使用 Easysearch 2.4.0 或更高版本创建的索引才能新增已索引的 dense_vector 字段。
• 旧索引不能通过更新 mapping 直接获得原生 HNSW 能力。请创建新索引并使用 Reindex 或迁移流程导入数据。
• 集群中存在 2.4.0 之前的数据节点时，包含已索引 dense_vector 的 mapping 和请求会被拒绝。

已存在字段的 mapping 更新规则如下：

更新 m 或 ef_construction 不会重写已经存在的 segment，新的参数只用于更新后生成的 segment。因此同一索引可能暂时包含 使用不同 HNSW 构建参数的 segment。需要让全部数据使用统一参数时，请创建新索引并 Reindex；不要依赖 mapping 更新或 force merge 改写已有图。

字段能力 #

dense_vector 是单值、已索引但没有 doc values 的专用向量字段：

使用 cosine 时，Easysearch 会将用于 HNSW 索引的向量归一化，但 _source 仍保留客户端写入的原始向量。读取 _source 得到的值不一定等于底层索引使用的归一化值。

当前限制 #

Easysearch 2.4.0 的原生 HNSW 范围不包括：

• byte、bit 向量类型；
• int8_hnsw、int4_hnsw、bbq_hnsw 和 flat 索引类型；
• 省略 dims 后由首个文档推导维度；
• index: false 的非索引向量；
• nested kNN 查询。

查询方法参考 原生 HNSW 搜索。