做ES开发运维这些年几乎每个项目都躲不过text字段的坑。有人建了索引写入时一切正常回头用match查询却一个结果都搜不出来有人想把某个text字段拿来排序结果控制台直接甩了一行红色报错还有人为了“分词”把keyword稀里糊涂换成text结果聚合报表全废。这些场景背后的基本面其实都是同一个东西text类型的映射配置没有真正吃透。这篇就单独把text字段拎出来聊透。适合正在学ES映射的初学者也适合已经被线上问题折磨过、想系统补一遍基础的开发运维。整个系列是ES基础映射相关的第十二篇前前后后聊过不少字段类型text是整个系列里最贴近“搜索引擎”这个原生定位的一种它背后牵出的倒排索引、分词器、评分、高亮这一整套体系是理解ES最推荐的一个切入点。1. 从源头理解text字段它是在解决什么问题1.1 倒排索引与全文检索text存在的理由我在讲映射类型时经常打一个比方keyword类型的字段像是一张图书目录上的书名你只能按完整、精确的名字去找text类型则像是把那本书的内容拆成了一张关键词卡片每个词后面记着一堆章节页码。图书目录用于精确查找关键词卡片用于全文检索这是两种完全不同的数据组织逻辑。ES的全文检索能力来自倒排索引。text字段在索引时会把传入的字符串交给分词器分词器按一套规则把长文本切成一个个词项再为每个词项建立倒排链表记录哪些文档包含这个词。查询阶段你再一次把查询字符串交给分词器切一遍得到词项后去倒排索引里做匹配和打分就能找到包含对应词的文档。整个过程的核心是“查询端和索引端必须使用同一套分词规则”否则词项对不上搜索就是一个字都命中不了。这个设计让我想起很多团队自建的搜索模块一开始就是拿字符串like去筛数据量一上来接口就超时。换到ES其实本质是把“扫描匹配”的活前置到了写入阶段用空间换时间把每个词和文档的关系提前算好查询时只查链表自然快得多。理解这一层你就能明白为什么text字段天然和“分析”“分词”绑定在一起而不是一个简单的字符串容器。1.2 一个不落的分工text和keyword选型对比新手最容易犯的错是把“包含”和“等于”混为一谈。很多后端同学从数据库把数据搬到ES习惯性把VARCHAR全改成keyword结果搜“华为”时文档里的“华为”能命中“华为技术有限公司”却命中不了因为keyword是按完整值匹配的。反过来也有人把状态码、订单号这种本就该精确匹配的字段全设成text导致term查询永远得到空结果还得在聚合里一次次踩坑。我习惯在选型时用下面这张判断表落地项目时基本按这张表过一遍字段能省掉大量后续返工判断场景推荐类型原因订单号、手机号、状态码、开关标识keyword精确匹配、term、terms、聚合排序都方便商品标题、文章正文、评论内容text需要按词项匹配、相关度评分、高亮用户昵称、品牌名称keyword text多字段既要精确匹配又想做搜索建议字段套字段IP、URLkeyword通常做过滤、去重不适合全文检索日志消息、监控描述text需要按关键词模糊定位异常内容这张表是我实际工作经验的浓缩。比如昵称用户在搜索框输入片段可能只想找“阿强”但后台管理里又需要精确过滤“阿强”这个昵称本身单用一个类型很难同时满足这时候就要用text和keyword的多字段组合后面我会详细讲。先记住一个结论text面向的是“内容查找”keyword面向的是“值匹配”。这个结论贯穿后面所有的配置决策也是你判断字段类型第一个要想明白的问题。2. 映射参数逐个拆解配置text字段的完整姿势2.1 最简单的一行映射到底配了什么刚开始接触ES时很多人写过这样一段映射{ mappings: { properties: { content: { type: text } } } }这一段看似啥都没配其实背后有一整套默认参数在生效分词器默认用standard索引规则和查询规则都用它fields没有额外子字段单独一个text值norms默认开启评分时会作为权重因子fielddata默认关闭所以这个字段不能直接排序和聚合boost默认1.0index默认true参与索引和搜索store默认false查询时从_source返回数据而非额外存储。很多人入坑就是从“默认值”开始的。写的时候只写了一个type心里想的是“存进去搜得出来就行”结果后期需求冒出来要么排序要么聚合要么想换中文分词映射已经写死了只能重建索引回填数据。所以我一直强调真正生产使用text一定要在写映射前把下面这些参数全部过一遍想清楚再动手。2.2 analyzer与search_analyzer两套分词规则务必要分清先理解两个时机的区别。写入数据时ES用analyzer处理原始字符串把结果写进倒排索引查询时如果查询本身是match、multi_match这类需要分析的全文查询ES会拿着查询字符串再走一遍分析流程这次使用的就是search_analyzer。如果只配置了analyzer且没有单独配置search_analyzer查询会沿用同一个analyzer也就是索引分词的同一套规则。为什么非得分两个因为索引时我们希望切得尽量细提高召回率查询时又希望切得尽量准提高准确率。以中文为例索引用ik_max_word会把“中华人民共和国”切得很细查询用ik_smart只切出粗粒度词查询端更理性能避免不少无谓匹配。一个实战配置片段长这样{ settings: { analysis: { analyzer: { my_text_analyzer: { type: custom, tokenizer: ik_max_word, filter: [lowercase, stop] } } } }, mappings: { properties: { title: { type: text, analyzer: my_text_analyzer, search_analyzer: ik_smart } } } }顺带提醒一个坑自定义分词器的filter里如果加了stop停用词过滤像“的、了、是”这种高频无语义词会被丢掉建索引和查询两端如果规则不一致会出现搜“的确”却没结果的情况。我排查过不止一次类似的问题最后定位时才发现某个词在查询端被过滤掉了所以设置词过滤器时尽量保证两端对齐避免明明有数据却搜不出来的怪现象。IK、smartcn这类中文分词插件我一般建议可以单独开一篇讲这里只提醒IK分词器有ik_max_word与ik_smart两种模式写中文业务时几乎绕不开生产环境可以直接按中文场景来做默认配置。2.3 fielddata、norms、index_prefixes等容易被忽略的参数fielddata是我最想拉出来重点批评的一个参数。text字段默认不能排序、不能聚合原因就是fielddata默认关闭。官方文档写得很明白把fielddata打开可以让text字段临时支持排序和聚合但这玩意儿会直接加载到堆内存可能一个字段就把几个G内存吃光。我见过一个团队为了给某个textarea字段排序把fielddata开成true集群GC飙到几十秒节点频频掉线后来拆成keyword多字段才救回来。所以再次强调永远不要用fielddata解决排序聚合问题。正确做法是给text字段配一个keyword子字段或者新建一个keyword字段用于聚合排序。除非你明确知道字段很小、分片很少、内存充裕否则别碰fielddata。norms参数代表标准化因子默认开启用于相关度评分。如果字段纯做过滤不做评分可以把norms关掉能节省一些磁盘和内存。不过实际收益要看数据量很多项目不用动它了解有这个优化点即可。index_prefixes是前缀索引可以在text字段上开启让前缀查询更快。比如{ mappings: { properties: { content: { type: text, index_prefixes: { min_chars: 2, max_chars: 5 } } } } }这个参数很实用但注意它只对前缀查询有效对中间匹配没帮助。开启后相当于额外建立一份前缀索引空间有开销。用不用要看业务查询是否大量以“开头是xxx”为主是就可以开不是就别浪费空间。2.4 ignore_above、store、similarity等边角参数ignore_above是keyword字段的常用参数放在text上很多人会混淆。其实text字段本身没有ignore_above直接生效的概念多数场景是放在keyword子字段上超过长度就不建索引用于控制字段的索引规模。如果你希望某个text字段超长内容仍能搜索就别设置ignore_above否则可能丢失长文本命中能力。store参数默认falseES默认从_source返回原始文档。如果关闭了_source或者个别字段想节省_source覆盖空间才需要额外storetrue。实际场景用得不算太多但如果你做的是大数据量日志系统只保留少数字段的可搜索能力可以考虑store。这里不展开知道有这么个参数即可。similarity可以定制打分算法text常用BM25也可以设为boolean等等。但说实话绝大多数业务场景用默认BM25就够了替换要谨慎否则相关度评分会变得不可预期。我一般只在调试排序异常时才看它日常配置不会动。3. text字段实战全文检索场景下的设计与调优3.1 从建索引到写入数据的一条完整流程写一段完整示例方便你直接照抄。目标一个新闻标题字段既要全文搜索标题内容又要支持后台精确筛选还要支持按标题排序。所以主字段用text做全文子字段keyword做精确匹配和排序再加一个ik子字段做中文分词搜索。先创建索引时的映射{ settings: { number_of_shards: 3, number_of_replicas: 1, analysis: { analyzer: { news_analyzer: { type: custom, tokenizer: ik_max_word, filter: [lowercase] } } } }, mappings: { properties: { news_id: { type: keyword }, title: { type: text, analyzer: news_analyzer, search_analyzer: news_analyzer, fields: { keyword: { type: keyword, ignore_above: 128 } } }, publish_time: { type: date } } } }写入一条新闻POST /news_index/_doc { news_id: n00101, title: 城市马拉松报名人数创历史新高, publish_time: 2024-03-15 }写入后title字段会被ik_max_word切成“城市”“马拉松”“报名”“人数”“创历史新高”等词项同时子字段keyword保存完整原始字符串“城市马拉松报名人数创历史新高”。搜索时用match查“马拉松”能命中用term查完整标题串也能命中按title.keyword排序、聚合也不会报错。这就是一个字段同时承担多种职责的典型做法。3.2 全文检索查询match、multi_match、match_phrase的选择text字段最常用的是match。它会把查询词先按search_analyzer分析再逐个匹配词项。例如搜“马拉松报名”先分词成“马拉松”“报名”只要文档包含其中一个词就命中。好处是召回高坏处是可能把“报名系统”这种不相干的也拉进来。所以需要更严谨的匹配时可以用match_phrase它要求词项按顺序紧跟出现查询匹配更精准。再看一个很多新人困惑的现象如果没有配置search_analyzer同时用了standard分词器查询词“城市马拉松”会被切成“城市”“马拉松”。如果文档里只有“马拉松报名人数”没有“城市”这个词standard分词器的match也能命中“马拉松”这一项所以结果照样出来。这个现象不是bug是全文检索的特性。要精确到短语级别就用match_phrase。multi_match用于一次查询多个text字段比如同时搜标题和正文{ query: { multi_match: { query: 马拉松, fields: [title^3, content] } } }字段后面带^3的意思是加权title命中比content命中权重更高。这些是搜索引擎的老本行ES里都是通过查询语句实现的。理解它们比记参数更关键match管召回match_phrase管短语精确度multi_match管多字段相关性排序。3.3 高亮的实现与常见注意事项全文检索场景里高亮几乎必配。ES的高亮分成plain、unified、fvh三种一般推荐unified兼容性最好。默认情况下只要字段参与索引就能高亮但如果想对长文本做更快更准的高亮可以在映射里设置term_vector为with_positions_offsets。这是text字段的进阶设置能提升高亮速度。常见问题高亮出来却看不到命中词。这通常有两种原因。第一种是字段用了标准分词器中文被切得乱七八糟高亮的词片段对不上第二种是高亮片段是由ES重新计算出来的如果字段内容很长默认片段数或片段大小太短可能刚好把命中词切掉。遇到这种问题我会用fragment_size把片段调长再限制number_of_fragments就能稳住。{ query: { match: { title: 马拉松 } }, highlight: { fields: { title: { fragment_size: 80, number_of_fragments: 3 } } } }高亮看起来简单但在实际业务里踩坑率很高尤其是中文场景。我建议做高亮前先用分词器接口验证一遍真实分词结果再决定用哪种分词器能省后面大量调试时间。4. 常见坑与排查实录text字段翻车现场4.1 排序聚合报错Fielddata is disabled这个报错几乎每个ES新手都会遇到对text字段直接排序或聚合报错信息大致是“Fielddata is disabled on text fields by default. Set fielddatatrue on [xxx]”。错误很容易理解但很多人在排查时总想点进去按提示打开fielddata。我再强调一遍优先级不要开。这个参数开了就像给内存开了一个无底洞。正确解法是给text字段设置keyword子字段用子字段做排序和聚合。如果字段已经在索引里了可以加一个keyword字段并用reindex迁数据。另一种场景是terms聚合时明确只想对词级别聚合这时才考虑更细的多字段设计而不是贸然开fielddata。构造一个最容易复现的报错并解决POST /news_index/_search { size: 0, aggs: { by_title: { terms: { field: title.keyword } } } }用title.keyword聚合而不要用title。索引层面title是texttitle.keyword是keyword这就是标准解法。别嫌多写几个字这比重新reindex的成本低得多也不会给集群埋下内存隐患。4.2 分词不一致导致的搜索零结果或乱结果有次业务方反馈搜某个词明明文档里就有就是搜不到。查下来发现索引时模板里自定义了分析器查询时在查询DSL里又临时指定了另一个分析器导致词项对不上。ES允许在查询时临时写一个analyzer覆盖search_analyzer这个特性方便但也是隐患来源{ query: { match: { title: { query: 城市马拉松, analyzer: ik_smart } } } }一旦这个analyzer和索引时的词项切法不统一效果就会乱。比如索引时用ik_max_word把“城市马拉松”切成“城市”“马拉松”查询时用standard切割结果也算一致但如果查询时用ngram之类的切割点完全不同就大概率搜不出结果。建议约定生产环境不要随便在查询DSL里覆盖analyzer除非你明确知道切词结果长什么样否则就是给自己埋雷。4.3 ignore_above引发的精度问题前面提到ignore_above多半用在keyword子字段上。它的作用很直白超过设定长度的值不再建立索引。带来的后果是这个值在term查询或聚合里会消失但它还在_source里所以你会看到一个诡异现象源数据里有数据但查不到。很多人排查半天忽略了ignore_above这个细节。比如title.keyword设置ignore_above为128出现长度超过128的标题精确查询title.keyword就查不到。解决办法不是简单取消ignore_above而是评估业务上是否有超长标题的精确过滤需求。如果有就把值调大或者不给keyword子字段加这个限制。用过ES的人都知道这种小参数最容易坑到人因为报错不会提示你只有结果和预期不一致时才会想到。4.4 映射已经写死需求变了怎么办索引创建之后普通字段的analyzer改不了。如果只是新增一个字段可以直接PUT mapping加新字段但已有的text字段要换分词器、加子字段就没法原地更新只能重建索引。重建索引的标准步骤我屡次用也推荐给团队第一步用新映射创建临时索引第二步把数据从一个索引拷贝到另一个用reindex接口做注意设置好冲突处理和并行线程数第三步验证数据量和查询结果一致第四步通过别名切换流量把旧索引下线。整个过程尽量利用别名业务方只感知别名不用感知底层换索引。伪代码如下PUT /news_index_new POST /_reindex { source: { index: news_index }, dest: { index: news_index_new } }然后更新别名指向新索引。这套流程听着简单但生产环境还要考虑reindex期间的增量数据丢失问题所以时间窗口要选在低峰期或者采用双写策略。这些细节如果不做就会在线上踩坑尤其是白天直接reindex被业务方问“为什么数据少了”的情况我是见过不只一次的。5. 个人经验与操作建议最后聊一点我自己的实操体会。很多人以为text就是一个加了分词的字符串其实它背后是整个全文检索引擎的交互命脉。真正用好的关键不是记住所有参数而是在设计索引时就想清楚这个字段将来会被怎么查精确匹配用keyword全文匹配用text两种都要就建多字段排序聚合尽量别碰fielddata。这些决策做在前后面会少非常多运维事故。再分享一个我长期使用的检查习惯每次写完映射先插入几条测试数据用_analyze接口把分词结果打印出来再跑一两轮match、match_phrase、term查询把高亮和聚合也顺手验证一遍。这个过程不用五分钟却能帮你把映射问题从上线前挡掉大半。如果你的业务也是中文全文检索强烈建议早点把分词器方案和text字段的多字段设计固定下来形成团队规范不要等线上报警了再回去补课。text字段的边界很明显它不适合做精确等于判断不适合做统计不适合做排序。这些“不适合”不是缺陷而是全文检索的本性。懂得它的边界ES才能真正成为检索体系里趁手的工具。这篇就聊到这里下一次准备仔细讲讲中文分词器内容会更偏实战。