1. 从一次失败的搜索说起为什么你的查询结果总是不对如果你用过 Elasticsearch大概率遇到过这种情况你明明在文档里存了“苹果手机”但搜索“苹果”却搜不到这条记录或者你存了一个产品编号“ABC-123”想精确匹配它结果连“ABC-1234”这种相似的编号也一起被搜了出来。这背后的“元凶”十有八九就是字段类型没选对——具体来说就是在text和keyword之间做出了错误的选择。这两个类型是 Elasticsearch 里最基础、最常用也最容易让人困惑的一对。表面上看它们都是用来存字符串的但它们在索引、搜索和聚合时的行为逻辑天差地别。选错了轻则搜索结果不准确重则拖垮集群性能。我见过不少项目初期为了图省事所有字符串字段都用了默认的text类型等到数据量上来要做精确匹配、排序或者聚合分析时才发现查询又慢又乱不得不回头重构映射那工程量可就大了。所以今天我们不谈空洞的理论就从实际应用场景出发彻底掰扯清楚text和keyword到底有什么区别以及在不同场景下你应该怎么选、怎么用。我会结合我踩过的坑和优化过的案例把原理、行为和实操建议都讲透。无论你是刚接触 Elasticsearch 的新手还是已经用过一段时间但对其内部机制一知半解的开发者这篇文章都能帮你建立起清晰、正确的认知。2. 核心差异解剖分词器是那个“分水岭”要理解text和keyword的区别核心就在于一点是否经过分析Analysis。这个“分析”过程最主要的工作就是“分词”。2.1 Text类型为全文搜索而生当你将一个字段定义为text类型时Elasticsearch 会默认使用一个叫做“标准分析器Standard Analyzer”的东西来处理它。这个过程可以拆解为三步字符过滤Character Filter先处理原始字符串比如去掉 HTML 标签如果你存了网页片段。分词Tokenization这是最关键的一步。分析器会根据规则默认是遇到空格、标点就切把一整段文本切分成一个个独立的词条Term。例如“Elasticsearch is great!” 会被切分成[“elasticsearch”, “is”, “great”]。词条过滤Token Filter对分出来的词条再做加工。比如把所有字母转成小写Lowercasing去掉“a”、“the”、“is”这种没实际搜索意义的词停用词Stop Words或者把单词还原成它的原型词干提取Stemming如“running”变成“run”。最终存入倒排索引的不是原始文本“Elasticsearch is great!”而是经过处理后的词条[“elasticsearch”, “great”]假设“is”是停用词被去掉了。当你进行全文搜索时你的搜索词也会经过同样的分析过程然后去倒排索引里匹配这些词条。这带来了text类型的核心特性支持全文搜索你可以搜索“great”也能搜到包含“great!”的文档。因为搜索词“great”经过分析后也变成了词条“great”。无法精确匹配你无法精确匹配“Elasticsearch is great!”这个完整的句子因为索引里根本没有这个完整的字符串。默认不支持排序和聚合因为排序和聚合通常需要对整个字段值进行操作而text字段存储的是分词后的词条列表。如果你强行对text字段排序Elasticsearch 会使用该字段的第一个词条来排序这通常毫无意义且会报一个警告建议你使用keyword子字段。2.2 Keyword类型为精确值而设与text相反keyword类型字段的值会被视为一个不可分割的整体。它不会经过任何分析器处理。你存入“ABC-123”索引里存的就是完整的“ABC-123”你存入“北京市海淀区”存的就是整个字符串。这决定了keyword类型的核心用途精确匹配用于过滤filter、精确查询term query。比如用户ID、状态码“published”, “draft”、标签、邮箱、邮编等。排序Sorting因为它是完整的值所以可以按字母序或其它规则进行可靠的排序。聚合Aggregations比如根据“城市”这个keyword字段做桶聚合Terms Aggregation统计每个城市的文档数量结果准确无误。不支持全文搜索如果你在keyword字段上搜索“北京”那么只有字段值完全等于“北京”的文档才会被匹配值为“北京市”的文档则不会被找到。简单来说text是为了“搜内容”准备的而keyword是为了“找标识”准备的。一个追求模糊和关联一个追求精确和确定。2.3 一个经典的组合Multi-fields 映射既然两者各有不可替代的用途那如果一个字段既需要被全文搜索又需要被精确匹配或聚合该怎么办呢难道要存两份数据Elasticsearch 提供了一个非常优雅的解决方案多字段Multi-fields映射。你可以在定义一个字段为text类型的同时为其指定一个keyword类型的子字段。PUT my_index { mappings: { properties: { product_name: { type: text, // 主字段用于全文搜索 fields: { keyword: { // 子字段用于精确匹配、排序、聚合 type: keyword, ignore_above: 256 // 只索引长度小于256的字符避免长字符串浪费资源 } } } } } }这样当你索引一个文档{“product_name”: “Apple iPhone 15 Pro”}后你可以用match查询在product_name字段上搜索“iphone”进行全文检索。同时你可以用term查询在product_name.keyword字段上精确匹配“Apple iPhone 15 Pro”或者用它来做排序和聚合。这几乎成为了处理用户输入文本、产品名称、文章标题等场景的标准做法。我强烈建议你在设计索引映射时对任何可能需要精确处理的text字段都习惯性地加上.keyword子字段这是一种低成本高回报的“防御性编程”。3. 实战行为对比查询、排序与聚合的现场演绎理解了核心差异我们通过几个具体的查询场景来看看它们的行为有何不同。假设我们有一个简单的索引包含一个text字段和一个keyword字段。PUT test_behavior { mappings: { properties: { title_text: { type: text }, title_keyword: { type: keyword }, status: { type: keyword } } } } PUT test_behavior/_doc/1 { title_text: Quick Brown Fox, title_keyword: Quick Brown Fox, status: PUBLISHED }3.1 查询Search行为对比场景一全文搜索Match QueryGET test_behavior/_search { query: { match: { title_text: brown fox } } }这个查询能成功匹配到文档1。因为match查询会对“brown fox”进行分词变成[“brown”, “fox”]然后去title_text的倒排索引里查找发现匹配。如果你对title_keyword字段执行同样的match查询将不会匹配任何文档。因为keyword类型不分析它试图把“brown fox”作为一个整体去匹配完整的“Quick Brown Fox”显然不相等。场景二精确匹配Term QueryGET test_behavior/_search { query: { term: { title_keyword: { value: Quick Brown Fox } } } }这个查询能精确匹配到文档1。因为term查询不分析搜索词直接查找值完全相等的文档。如果你对title_text字段执行term查询搜索词是“Quick Brown Fox”同样不会匹配。因为title_text字段里存储的是分词后的小写词条[“quick”, “brown”, “fox”]而term查询的“Quick Brown Fox”未经分析无法匹配到这些词条。你必须使用小写的“quick brown fox”作为term查询的值才能匹配但这在实际应用中几乎无法预测所以永远不要用term查询来搜索text字段。实操心得记住这个黄金法则——match用于textterm用于keyword。混用是导致搜索结果诡异的最常见原因。3.2 排序Sort行为对比排序要求字段的值具有可比性且通常需要完整的值。GET test_behavior/_search { sort: [ { title_keyword: { order: asc } } // 可以正常排序 // { title_text: { order: asc } } // 如果取消注释可能会触发警告且结果不可预期 ] }对keyword字段排序是明确且可靠的。对text字段排序Elasticsearch 会尝试使用其第一个词条本例中是“quick”来排序这通常没有业务意义并且控制台会给出警告“Fielddata is disabled on text fields by default...” 建议你改用title_text.keyword来排序。3.3 聚合Aggregation行为对比聚合特别是词项聚合Terms Aggregation是数据分析的利器。GET test_behavior/_search { size: 0, aggs: { status_count: { terms: { field: status } // keyword字段完美聚合 }, title_terms: { terms: { field: title_text } // text字段默认情况下会报错 } } }对keyword字段status做聚合会得到清晰的结果桶例如{ “key”: “PUBLISHED”, “doc_count”: 1 }。而直接对text字段title_text进行聚合在默认情况下会抛出异常“Fielddata is disabled on text fields by default...”。这是因为对分词字段做聚合需要将倒排索引的所有词条加载到内存即开启 fielddata这是一个非常消耗内存和 CPU 的操作尤其是对于长文本字段极易导致节点内存溢出OOM。因此 Elasticsearch 默认禁用了它。如果你确实需要对text字段的内容进行分析型聚合例如找出文章中最常出现的词汇你需要显式地在映射中为该字段开启fielddata: true但必须极其谨慎仅对值域很小、内容很短的字段这样做。对于像标题、内容这样的字段正确的做法是使用前面提到的多字段映射对.keyword子字段进行聚合这聚合的是完整的标题文本。4. 高级话题与性能陷阱掌握了基本行为我们再看几个更深层次的话题这些往往是性能问题的根源。4.1 忽略大小写与规范化Normalizationkeyword字段是精确匹配那如果用户搜索“published”和“PUBLISHED”想被同等对待呢这就需要“规范化”。你可以在keyword字段上定义normalizer。normalizer类似于分析器但只包含字符过滤器和词条过滤器不能有分词器。常用的过滤器是lowercase。PUT my_index { settings: { analysis: { normalizer: { lowercase_normalizer: { type: custom, filter: [lowercase] } } } }, mappings: { properties: { status: { type: keyword, normalizer: lowercase_normalizer // 存入和查询时都会转为小写 } } } }这样无论存入“PUBLISHED”还是“published”索引里都是“published”。查询时搜索词也会被转为小写再去匹配实现了大小写不敏感的精确匹配。这比用text类型做模糊匹配要高效、准确得多。4.2 动态映射的“坑”与显式映射的重要性如果你不预先定义映射就直接写入数据Elasticsearch 会尝试猜测字段类型这称为动态映射。对于字符串新版 Elasticsearch7.x 以后的默认规则是同时映射为text和keyword。这听起来很美好但隐藏着风险。假设一个字段你本意只用于精确过滤如订单号动态映射会同时生成text类型。这会导致不必要的分析开销占用更多磁盘和内存。如果有人误用match查询该字段可能得到错误结果。聚合时你需要明确指定.keyword子字段增加了查询语句的复杂性。最佳实践是对于生产环境永远使用显式映射。在索引创建之初就根据业务场景明确每个字段的类型。对于字符串问自己两个问题1. 需要被全文搜索吗2. 需要被精确匹配、排序或聚合吗根据答案选择text、keyword或textwithkeywordsubfield。4.3 性能考量存储、内存与查询速度存储text字段因为要存储分词后的词条列表、位置、偏移量等信息通常比存储原始字符串的keyword字段占用更多磁盘空间。内存text字段如果开启了 fielddata 用于聚合会将所有词条加载到堆内存对内存压力极大。keyword字段的 doc values用于排序、聚合是存储在磁盘上的通过文件系统缓存高效访问内存友好。查询速度对于精确匹配term查询keyword字段远快于text字段因为后者需要分析搜索词然后遍历倒排索引。对于全文搜索text字段是唯一选择其速度取决于分析器的复杂度和词条数量。一个常见的性能反模式是将一个高基数字段如用户ID、手机号错误地设为text类型并对其进行聚合。这会导致 fielddata 占用海量内存直接拖垮节点。请务必确保所有用于聚合、排序的字段都是keyword类型或其等效形式。5. 场景化选型指南与配置建议理论说了这么多到底怎么选我们看几个具体场景。场景一产品名称/文章标题需求支持用户输入关键词搜索如“手机”搜出所有手机同时后台可能需要按名称精确去重或排序。方案text类型 keyword子字段。这是标准答案。映射示例“product_name”: { “type”: “text”, “analyzer”: “ik_max_word”, // 使用中文分词器如IK “fields”: { “keyword”: { “type”: “keyword”, “ignore_above”: 256 } } }场景二用户ID、订单号、状态码需求精确匹配用于过滤、聚合。绝不需要分词搜索。方案纯keyword类型。如果值可能很长如UUID考虑设置ignore_above如512来限制索引长度避免存储和性能问题。注意即使全是数字如果不需要范围查询也应作为keyword处理因为手机号、邮编等作为数字处理没有意义。场景三文章正文、商品描述需求复杂的全文搜索需要支持同义词、拼音搜索等。方案text类型并精心选择分析器如IK分词器同义词过滤器。通常不需要.keyword子字段因为几乎不会对全文内容做精确匹配或聚合。性能提示避免对长text字段进行聚合或脚本访问。如果必须考虑额外存储一个摘要或关键词字段keyword类型用于此类操作。场景四标签Tags、分类Categories需求既可以按单个标签精确过滤又希望用户输入部分标签名能搜到相关标签。方案有两种思路多字段映射textkeyword。这是最灵活通用的。使用keyword并配置自定义分析器如果标签本身是短词且不需要复杂分词可以定义一个使用pattern分词器或whitespace分词器的text字段但这样会失去精确匹配的能力。因此方案1更推荐。关于ignore_above参数这是keyword字段的一个重要参数。它指定了字符串长度的字节数上限超过此长度的部分将不会被索引即无法被搜索、排序或聚合但原始值仍会存储在_source中。这是一个重要的性能优化手段可以防止超长字符串如错误的日志行、Base64编码污染你的索引影响性能。通常设置为 256 或 512 是一个安全的选择。最后也是最关键的一条建议在写入第一批真实数据之前花时间设计好你的映射。映射一旦确定虽然可以新增字段但修改已有字段的类型几乎是不可能的需要重建索引。前期在映射设计上多投入一小时可能避免后期数天的数据迁移和问题排查工作。