映射参数 #

映射参数用于控制字段的索引方式、存储行为和搜索特性。合理配置这些参数可以优化查询性能和存储效率。

概念指南 → 了解如何设计映射，请阅读：
映射基础
映射模式与常见坑

按功能分类 #

索引控制 #

控制字段是否可被搜索以及如何索引。

参数	说明	默认值
index	是否索引该字段（可搜索）	`true`
enabled	是否解析和索引该对象字段	`true`
doc_values	是否存储列式数据（用于排序/聚合）	`true`
store	是否独立存储字段值	`false`
norms	是否存储长度归一化因子	text: `true`

文本分析 #

控制文本字段的分词和搜索行为。

参数	说明	默认值
analyzer	索引和搜索时的分词器	`standard`
search_analyzer	仅搜索时使用的分词器	同 `analyzer`
search_quote_analyzer	带引号短语查询时使用的分词器	同 `search_analyzer`
normalizer	keyword 字段的归一化器	无
term_vector	是否存储词条向量	`no`
position_increment_gap	数组元素间的位置间隔	`100`
fielddata_frequency_filter	字段数据频率过滤器配置	无
index_phrases	是否为短语查询构建额外索引	`false`
index_prefixes	是否为前缀查询构建额外索引	`false`
split_queries_on_whitespace	查询是否在空白处拆分	`false`

数据转换 #

控制数据类型转换和格式化。

参数	说明	默认值
format	日期字段的解析格式	`strict_date_optional_time\\|\\|epoch_millis`
locale	解析日期/范围时使用的区域设置	无
coerce	是否自动转换数据类型	`true`
null_value	null 的替代值	无
ignore_malformed	是否忽略格式错误的值	`false`
ignore_above	超长字符串不索引的阈值	`2147483647`
ignore_z_value	是否忽略地理坐标的 Z 值	`true`

字段结构 #

控制字段的组织和扩展方式。

参数	说明	默认值
fields	多字段定义（同字段多种索引方式）	无
properties	对象/嵌套字段的子字段定义	无
copy_to	将字段值复制到目标字段	无
dynamic	是否动态添加新字段	`true`

搜索与评分 #

控制搜索行为和相关性评分。

参数	说明	默认值
boost	字段权重提升因子	`1.0`
similarity	相关性评分算法	`BM25`
fielddata	text 字段是否启用堆内存聚合	`false`
eager_global_ordinals	是否提前构建全局序数	`false`

完成字段（Completion） #

特定于自动完成/搜索建议的参数。

参数	说明	默认值
preserve_separators	是否保留分隔符	`true`
preserve_position_increments	是否保留位置增量	`true`
contexts	完成上下文定义	无
max_input_length	最大输入长度	`50`

Mapper 扩展模块参数 #

mapper-extras 模块提供的特殊字段类型的参数。

参数	字段类型	说明	默认值
scaling_factor	`scaled_float`	浮点数的缩放因子	—
positive_score_impact	`rank_feature`	特性对得分的影响	`true`
enable_position_increments	`token_count`	是否包含位置增量	`true`
max_shingle_size	`search_as_you_type`	最大 shingle 大小	`3`

元数据 #

附加信息和说明。

参数	说明	默认值
meta	自定义元数据（单位、说明等）	无

常用参数详解 #

index — 是否可搜索 #

{
  "properties": {
    "internal_id": {
      "type": "keyword",
      "index": false
    }
  }
}

true（默认）：字段可被搜索
false：字段不可搜索，但仍可聚合（如果 doc_values=true）

使用场景：仅用于聚合或排序的字段可设为 index: false

doc_values — 列式存储 #

{
  "properties": {
    "description": {
      "type": "text",
      "doc_values": false
    }
  }
}

true（默认）：支持排序和聚合
false：节省磁盘空间，但无法排序/聚合

使用场景：纯全文搜索字段可关闭 doc_values

copy_to — 字段合并 #

{
  "properties": {
    "title": {
      "type": "text",
      "copy_to": "full_content"
    },
    "body": {
      "type": "text",
      "copy_to": "full_content"
    },
    "full_content": {
      "type": "text"
    }
  }
}

将多个字段内容复制到一个目标字段，便于跨字段搜索。

fields — 多字段 #

{
  "properties": {
    "title": {
      "type": "text",
      "fields": {
        "keyword": {
          "type": "keyword"
        },
        "english": {
          "type": "text",
          "analyzer": "english"
        }
      }
    }
  }
}

同一字段以多种方式索引：

title → 默认分词搜索
title.keyword → 精确匹配、聚合
title.english → 英语词干搜索

ignore_above — 截断长字符串 #

{
  "properties": {
    "tag": {
      "type": "keyword",
      "ignore_above": 256
    }
  }
}

超过 256 字符的值不被索引（但仍存储在 _source 中）。

参数适用类型 #

参数	text	keyword	numeric	date	boolean	object	nested
analyzer	✓	-	-	-	-	-	-
boost	✓	✓	✓	✓	✓	-	-
coerce	-	-	✓	✓	-	-	-
copy_to	✓	✓	✓	✓	✓	-	-
doc_values	-	✓	✓	✓	✓	-	-
dynamic	-	-	-	-	-	✓	✓
enabled	-	-	-	-	-	✓	-
fielddata	✓	-	-	-	-	-	-
fields	✓	✓	✓	✓	✓	-	-
format	-	-	-	✓	-	-	-
ignore_above	-	✓	-	-	-	-	-
ignore_malformed	-	-	✓	✓	-	-	-
index	✓	✓	✓	✓	✓	-	-
meta	✓	✓	✓	✓	✓	✓	✓
normalizer	-	✓	-	-	-	-	-
norms	✓	✓	-	-	-	-	-
null_value	-	✓	✓	✓	✓	-	-
properties	-	-	-	-	-	✓	✓
search_analyzer	✓	-	-	-	-	-	-
similarity	✓	-	-	-	-	-	-
store	✓	✓	✓	✓	✓	-	-
term_vector	✓	-	-	-	-	-	-

完整参数列表 #

参数	描述	默认值
analyzer	指定索引和搜索时使用的分词器	`standard`
boost	查询时的字段权重提升因子	`1.0`
coerce	控制是否自动将值转换为字段类型	`true`
contexts	完成字段的上下文定义	—
copy_to	将字段值复制到目标字段	—
doc_values	是否存储列式数据以加速排序和聚合	`true`
dynamic	是否动态添加新字段	`true`
eager_global_ordinals	是否在刷新时提前构建全局序数	`false`
enable_position_increments	令牌计数是否包含位置增量	`true`
enabled	是否解析和索引该字段	`true`
fielddata	是否为 text 字段启用堆内存排序/聚合	`false`
fielddata_frequency_filter	字段数据频率过滤器配置	—
fields	为同一字段定义多种索引方式	—
format	指定日期字段的解析格式	`strict_date_optional_time\\|\\|epoch_millis`
ignore_above	超过指定长度的字符串不被索引	`2147483647`
ignore_malformed	是否忽略格式错误的值	`false`
ignore_z_value	是否忽略地理坐标的 Z 值	`true`
index	控制字段是否可被搜索	`true`
index_phrases	是否为短语查询构建额外索引	`false`
index_prefixes	是否为前缀查询构建额外索引	`false`
locale	解析日期/范围时的区域设置	—
max_input_length	完成字段的最大输入长度	`50`
max_shingle_size	search_as_you_type 的最大 shingle 大小	`3`
meta	附加自定义元数据	—
normalizer	keyword 字段的归一化处理器	—
norms	是否存储字段长度归一化因子	text: `true`
null_value	用指定值替代 null	—
position_increment_gap	数组元素间的位置间隔	`100`
positive_score_impact	rank_feature 对得分的影响方向	`true`
preserve_position_increments	完成字段是否保留位置增量	`true`
preserve_separators	完成字段是否保留分隔符	`true`
properties	定义对象/嵌套字段的子字段映射	—
scaling_factor	scaled_float 字段的缩放因子	—
search_analyzer	查询时使用的分词器	同 `analyzer`
search_quote_analyzer	带引号短语查询时的分词器	同 `search_analyzer`
similarity	相关性评分算法	`BM25`
split_queries_on_whitespace	查询是否在空白处拆分	`false`
store	是否独立存储字段值	`false`
term_vector	是否存储词条向量	`no`