Elasticsearch使用指南之Elasticsearch Mapping parameters(主要参数一览)

作者简介：《RocketMQ技术内幕》作者、中间件兴趣圈微信公众号维护者。

本文将详细介绍Elasticsearch在创建索引映射时可指定的参数，并重点分析其含义。

1、analyzer
指定分词器。elasticsearch是一款支持全文检索的分布式存储系统，对于text类型的字段，首先会使用分词器进行分词，然后将分词后的词根一个一个存储在倒排索引中，后续查询主要是针对词根的搜索。

analyzer该参数可以在每个查询、每个字段、每个索引中使用，其优先级如下（越靠前越优先）：
1）字段上定义的分词器
2）索引配置中定义的分词器
3）默认分词器(standard)

在查询上下文，分词器的查找优先为：
1）full-text query中定义的分词器
2）定义类型映射时，字段中search_analyzer 定义的分词器。
3）定义字段映射时analyzer定义的分词器
4）索引中default_search中定义的分词器。
5）索引中默认定义的分词器
6）标准分词器（standard）。

2、normalizer
规划化，主要针对keyword类型，在索引该字段或查询字段之前，可以先对原始数据进行一些简单的处理，然后再将处理后的结果当成一个词根存入倒排索引中，举例如下：

PUT index
{
  "settings": {
    "analysis": {
      "normalizer": {
        "my_normalizer": {                                    // @1
          "type": "custom",
          "char_filter": [],
          "filter": ["lowercase", "asciifolding"]             // @2
        }
      }
    }
  },
  "mappings": {
    "_doc": {
      "properties": {
        "foo": {
          "type": "keyword",
          "normalizer": "my_normalizer"                      // @3
        }
      }
    }
  }
}

代码@1：首先在settings中的analysis属性中定义normalizer。
代码@2：设置标准化过滤器，示例中的处理器为小写、asciifolding。
代码@3：在定义映射时，如果字段类型为keyword，可以使用normalizer引用定义好的normalizer。

3、 boost
权重值，可以提升在查询时的权重，对查询相关性有直接的影响，其默认值为1.0。其影响范围为词根查询(team query),对前缀、范围查询、全文索引(match query)不生效。

注意：不建议在创建索引映射时使用boost属性，而是在查询时通过boost参数指定。其主要原因如下：
1）无法动态修改字段中定义的boost值，除非使用reindex命令重建索引。
2）相反，如果在查询时指定boost值，每一个查询都可以使用不同的boost值，灵活。
3）在索引中指定boost值，boost存储在记录中，从而会降低分数计算的质量。

4、coerce
是否进行类型“隐式转换”。es最终存储文档的格式是字符串。

例如存在如下字段类型：

"number_one": {
   "type": "integer"
}

声明number_one字段的类型为数字类型，那是否允许接收“6”字符串形式的数据呢？因为在JSON中，“6”用来赋给int类型的字段，也是能接受的，默认coerce为true，表示允许这种赋值，但如果coerce设置为false，此时es只能接受不带双引号的数字，如果在coerce=false时，将“6”赋值给number_one时会抛出类型不匹配异常。

可以在创建索引时指定默认的coerce值，示例如下：

PUT my_index
{
  "settings": {
    "index.mapping.coerce": false
  },
  "mappings": {
    // 省略字段映射定义
  }
}

5、copy_to
copy_to参数允许您创建自定义的_all字段。换句话说，多个字段的值可以复制到一个字段中例如，first_name和last_name字段可以复制到full_name字段如下:

PUT my_index
{
  "mappings": {
    "_doc": {
      "properties": {
        "first_name": {
          "type": "text",
          "copy_to": "full_name" 
        },
        "last_name": {
          "type": "text",
          "copy_to": "full_name" 
        },
        "full_name": {
          "type": "text"
        }
      }
    }
  }
}

表示字段full_name的值来自 first_name + last_name。

关于copy_to重点说明：
1）字段的复制是原始值，而不是分词后的词根。
2）复制字段不会包含在_souce字段中，但可以使用复制字段进行查询。
3）同一个字段可以复制到多个字段，写法如下："copy_to": [ "field_1", "field_2" ]

6、 doc_values
当需要对一个字段进行排序时，es需要提取匹配结果集中的排序字段值集合，然后进行排序。倒排索引的数据结构对检索来说相当高效，但对排序就不那么擅长了。

业界对排序、聚合非常高效的数据存储格式首推列式存储，在elasticsearch中,doc_values就是一种列式存储结构，默认情况下绝大多数数据类型都是开启的，即在索引时会将字段的值（或分词后的词根序列）加入到倒排索引中，同时也会该字段的值加入doc_values中，所有该类型的索引下该字段的值用一列存储。

doc_values的使用示例：

PUT my_index
{
  "mappings": {
    "_doc": {
      "properties": {
        "status_code": { 
          "type":       "keyword"      // 默认情况下，“doc_values”:true
        },
        "session_id": { 
          "type":       "keyword",
          "doc_values": false
        }
      }
    }
  }
}

7、dynamic
是否允许动态的隐式增加字段。在执行index api或更新文档API时，对于_source字段中包含一些原先未定义的字段采取的措施，根据dynamic的取值，会进行不同的操作：
1）true，默认值，表示新的字段会加入到类型映射中。
2）false,新的字段会被忽略，即不会存入_souce字段中，即不会存储新字段，也无法通过新字段进行查询。
3）strict，会显示抛出异常，需要新使用put mapping api先显示增加字段映射。

dynamic设置为false，也是可以通过put mapping api进行字段的新增，同样put mapping api可以对dynamic值进行更新。

举例说明：

PUT my_index/_doc/1 
{
  "username": "johnsmith",
  "name": {
    "first": "John",
    "last": "Smith"
  }
}
PUT my_index/_doc/2              // @1
{
  "username": "marywhite",
  "email": "mary@white.com",
  "name": {
    "first": "Mary",
    "middle": "Alice",
    "last": "White"
  }
}
GET my_index/_mapping  // @2

代码@1在原有的映射下，增加了username，name.middle两个字段，通过代码@2获取映射API可以得知，es已经为原本不存在的字段自动添加了类型映射定义。

注意：dynamic只对当前层级具有约束力，例如：

PUT my_index
{
  "mappings": {
    "_doc": {
      "dynamic": false,         // @1
      "properties": {
        "user": {                    // @2
          "properties": {
            "name": {
              "type": "text"
            },
            "social_networks": {    // @3
              "dynamic": true,
              "properties": {}
            }
          }
        }
      }
    }
  }
}

代码@1：_doc类型的顶层不能不支持动态隐式添加字段映射。
代码@2：但_doc的嵌套对象user对象，是支持动态隐式添加字段映射。
代码@3：同样对于嵌套对象social_networks，也支持动态隐式添加字段映射。

8、enabled
是否建立索引，默认情况下es会尝试为你索引所有的字段，但有时候某些类型的字段，无需建立索引，只是用来存储数据即可。只有映射类型(type)和object类型的字段可以设置enabled属性。示例如下：

PUT my_index
{
  "mappings": {
    "_doc": {
      "properties": {
        "user_id": {
          "type":  "keyword"
        },
        "last_updated": {
          "type": "date"
        },
        "session_data": { 
          "enabled": false
        }
      }
    }
  }
}

PUT my_index/_doc/session_1
{
  "user_id": "kimchy",
  "session_data": { 
    "arbitrary_object": {
      "some_array": [ "foo", "bar", { "baz": 2 } ]
    }
  },
  "last_updated": "2015-12-06T18:20:22"
}

上述示例，es会存储session_data对象的数据，但无法通过查询API根据session_data中的属性进行查询。

同样，可以通过put mapping api更新enabled属性。

9、eager_global_ordinals
全局序列号，它以字典顺序为每个惟一的术语保持递增的编号。全局序号只支持字符串类型（关键字和文本字段）。在关键字字段中，它们在默认情况下是可用的，但文本字段只能fielddata=true时可用。doc_values(和fielddata)也有序号，是特定段（segment）和字段中所有词根(term)的唯一编号。全局序号只是在此之上构建的，它提供了段序号（segment ordinals）和全局序号(global ordinals)之间的映射，全局序号在整个分片中是唯一的。由于每个字段的全局序号与一个分片(shard)的所有段(segment)相关联，因此当一个新的segment(段)变为可见时，需要完全重新构建它们。术语聚合依懒全局序号，首先在分片级别(shard)执行聚合，然后汇聚所有分片的结果(reduce)并将全局序号转换为真正的词根(字符串)，合并后返回聚合后的结果。默认情况下，全局序号是在搜索时加载的，这对提高索引API的速度会非常有利。但是，如果您更加重视搜索性能，，那么在您计划使用的聚合的字段上设置eager_global_ordinals，会对提高查询效率更有帮助。
eager_global_ordinals的意思是预先加载全局序号。

其示例如下：

PUT my_index/_mapping/_doc
{
  "properties": {
    "tags": {
      "type": "keyword",
      "eager_global_ordinals": true
    }
  }
}

10、fielddata
为了解决排序与聚合，elasticsearch提供了doc_values属性来支持列式存储，但doc_values不支持text字段类型。因为text字段是需要先分析（分词），会影响doc_values列式存储的性能。es为了支持text字段高效排序与聚合，引入了一种新的数据结构(fielddata)，使用内存进行存储。默认构建时机为第一次聚合查询、排序操作时构建，主要存储倒排索引中的词根与文档的映射关系，聚合，排序操作在内存中执行。因此fielddata需要消耗大量的JVM堆内存。一旦fielddata加载到内存后，它将永久存在。通常情况下，加载fielddata是一个昂贵的操作，故默认情况下，text字段的字段默认是不开启fielddata机制。在使用fielddata之前请慎重考虑为什么要开启fielddata。通常text字段用来进行全文搜索，对于聚合、排序字段，建议使用doc_values机制。

为了节省内存的使用，es提供了另一项机制（fielddata_frequency_filter），允许只加载那些词根频率在指定范围(最大，小值)直接的词根与文档的映射关系，最大最小值可以指定为绝对值，例如数字，也可以基于百分比（百分比的计算是基于整个分段(segment)，其频率分母不是分段(segment)中所有的文档，而是segment中该字段有值的文档）。可以通过min_segment_size参数来指定分段中必须包含的最小文档数量来排除小段，也就是说可以控制fielddata_frequency_filter的作用范围是包含大于min_segment_size的文档数量的段。

11、format
在JSON文档中，日期表示为字符串。Elasticsearch使用一组预先配置的格式来识别和解析这些字符串，并将其解析为long类型的数值(毫秒)。
日期格式主要包括如下3种方式：
1）自定义格式
2）date mesh(已在DSL查询API中详解)
3）内置格式
一：自定义格式
首先可以使用java定义时间的格式，例如：

PUT my_index
{
  "mappings": {
    "_doc": {
      "properties": {
        "date": {
          "type":   "date",
          "format": "yyyy-MM-dd HH:mm:ss"
        }
      }
    }
  }
}

二：date mesh
某些API支持，已在DSL查询API中详细介绍过，这里不再重复。

三：内置格式
elasticsearch为我们内置了大量的格式，如下：

1. epoch_millis
   时间戳，单位，毫秒。
2. epoch_second
   时间戳，单位，秒。
3. date_optional_time
   日期必填，时间可选，其支持的格式如下：

1. basic_date
   其格式表达式为 ：yyyyMMdd
2. basic_date_time
   其格式表达式为：yyyyMMdd'T'HHmmss.SSSZ
3. basic_date_time_no_millis
   其格式表达式为：yyyyMMdd'T'HHmmssZ
4. basic_ordinal_date
   4位数的年 + 3位(day of year)，其格式字符串为yyyyDDD
5. basic_ordinal_date_time
   其格式字符串为yyyyDDD'T'HHmmss.SSSZ
6. basic_ordinal_date_time_no_millis
   其格式字符串为yyyyDDD'T'HHmmssZ
7. basic_time
   其格式字符串为HHmmss.SSSZ
8. basic_time_no_millis
   其格式字符串为HHmmssZ
9. basic_t_time
   其格式字符串为'T'HHmmss.SSSZ
10. basic_t_time_no_millis
    其格式字符串为'T'HHmmssZ
11. basic_week_date
    其格式字符串为xxxx'W'wwe，4为年 ，然后用'W', 2位week of year（所在年里周序号） 1位 day of week。
12. basic_week_date_time
    其格式字符串为xxxx'W'wwe'T'HH:mm:ss.SSSZ.
13. basic_week_date_time_no_millis
    其格式字符串为xxxx'W'wwe'T'HH:mm:ssZ.
14. date
    其格式字符串为yyyy-MM-dd
15. date_hour
    其格式字符串为yyyy-MM-dd'T'HH
16. date_hour_minute
    其格式字符串为yyyy-MM-dd'T'HH:mm
17. date_hour_minute_second
    其格式字符串为yyyy-MM-dd'T'HH:mm:ss
18. date_hour_minute_second_fraction
    其格式字符串为yyyy-MM-dd'T'HH:mm:ss.SSS
19. date_hour_minute_second_millis
    其格式字符串为yyyy-MM-dd'T'HH:mm:ss.SSS
20. date_time
    其格式字符串为yyyy-MM-dd'T'HH:mm:ss.SSS
21. date_time_no_millis
    其格式字符串为yyyy-MM-dd'T'HH:mm:ss
22. hour
    其格式字符串为HH
23. hour_minute
    其格式字符串为HH:mm
24. hour_minute_second
    其格式字符串为HH:mm:ss
25. hour_minute_second_fraction
    其格式字符串为HH:mm:ss.SSS
26. hour_minute_second_millis
    其格式字符串为HH:mm:ss.SSS
27. ordinal_date
    其格式字符串为yyyy-DDD,其中DDD为 day of year。
28. ordinal_date_time
    其格式字符串为yyyy-DDD‘T’HH:mm:ss.SSSZZ,其中DDD为 day of year。
29. ordinal_date_time_no_millis
    其格式字符串为yyyy-DDD‘T’HH:mm:ssZZ
30. time
    其格式字符串为HH:mm:ss.SSSZZ
31. time_no_millis
    其格式字符串为HH:mm:ssZZ
32. t_time
    其格式字符串为'T'HH:mm:ss.SSSZZ
33. t_time_no_millis
    其格式字符串为'T'HH:mm:ssZZ
34. week_date
    其格式字符串为xxxx-'W'ww-e,4位年份，ww表示week of year，e表示day of week。
35. week_date_time
    其格式字符串为xxxx-'W'ww-e'T'HH:mm:ss.SSSZZ
36. week_date_time_no_millis
    其格式字符串为xxxx-'W'ww-e'T'HH:mm:ssZZ
37. weekyear
    其格式字符串为xxxx
38. weekyear_week
    其格式字符串为xxxx-'W'ww,其中ww为week of year。
39. weekyear_week_day
    其格式字符串为xxxx-'W'ww-e,其中ww为week of year,e为day of week。
40. year
    其格式字符串为yyyy
41. year_month
    其格式字符串为yyyy-MM

42. year_month_day
    其格式字符串为yyyy-MM-dd

    温馨提示，日期格式时，es建议在上述格式之前加上strict_前缀。

12、ignore_above
超过ignore_above设置的字符串不会被索引或存储。对于字符串数组，将分别对每个数组元素应ignore_above，超过ignore_above的字符串元素将不会被索引或存储。目前测试的结果为：对于字符串字符长度超过ignore_above会存储，但不索引（也就是无法根据该值去查询）。

其测试效果如下：

public static void create_mapping_ignore_above() {   // 创建映射
        RestHighLevelClient client = EsClient.getClient();
        try {
            CreateIndexRequest request = new CreateIndexRequest("mapping_test_ignore_above2");
            XContentBuilder mapping = XContentFactory.jsonBuilder()
                    .startObject()
                        .startObject("properties")
                            .startObject("lies")
                                .field("type", "keyword")      // 创建关键字段
                                .field("ignore_above", 10)     // 设置长度不能超过10
                            .endObject()
                        .endObject()
                    .endObject();
            
//            request.mapping("user", mapping_user);
            request.mapping("_doc", mapping);
            System.out.println(client.indices().create(request, RequestOptions.DEFAULT));
        } catch (Throwable e) {
            e.printStackTrace();
        } finally {
            EsClient.close(client);
        }
    }
    
    public static void index_mapping_ignore_above() {  // 索引数据
        RestHighLevelClient client = EsClient.getClient();
        try {
            IndexRequest request = new IndexRequest("mapping_test_ignore_above2", "_doc");
            Map<String, Object> data = new HashMap<>();
            data.put("lies", new String[] {"dingabcdwei","huangsw","wuyanfengamdule"});
            request.source(data);
            System.out.println(client.index(request, RequestOptions.DEFAULT));
        } catch (Throwable e) {
            e.printStackTrace();
        } finally {
            EsClient.close(client);
        }
    }

public static void search_ignore_above() {  // 查询数据
        RestHighLevelClient client = EsClient.getClient();
        try {
            SearchRequest searchRequest = new SearchRequest();
            searchRequest.indices("mapping_test_ignore_above2");
            SearchSourceBuilder sourceBuilder = new SearchSourceBuilder();
            sourceBuilder.query(
                    // QueryBuilders.matchAllQuery()    // @1
                    // QueryBuilders.termQuery("lies", "dingabcdwei")  // @2
                    // QueryBuilders.termQuery("lies", "huangsw")      // @3
            ); 
            searchRequest.source(sourceBuilder);
            SearchResponse result = client.search(searchRequest, RequestOptions.DEFAULT);
            System.out.println(result);
        } catch (Throwable e) {
            e.printStackTrace();
        } finally {
            EsClient.close(client);
        }
    }

代码@1：首先查询所有数据，其_souce字段的值为："_source":{"lies":["dingabcdwei","huangsw","wuyanfengamdule"]}，表名不管字符串的值是否大于ignore_above指定的值，都会存储。
代码@2：用超过ignore_above长度的值尝试去搜索，发现无法匹配到记录，表明并未加入到倒排索引中。
代码@3：用未超过ignore_above长度的值尝试去搜索，发现能匹配到记录。

注意：在es中,ignore_above的长度是字符的长度，而es其底层实现lucene是使用字节进行计算的，故，如果要反馈到lucnce，请注意关系。

13、ignore_malformed
试图将错误的数据类型索引到字段中，默认情况下会抛出异常，并拒绝整个文档。ignore_malformed参数，如果设置为真，允许错误被忽略。格式不正确的字段不建立索引，但是文档中的其他字 段正常处理。可以创建索引时，设置index.mapping.ignore_malformed 配置项来定义索引级别的默认值，其优先级为 字段级、索引级。

14、index
定义字段是否索引，true:代表索引，false表示不索引（则无法通过该字段进行查询），默认值为true。

• index_options
  控制文档添加到反向索引的额外内容，其可选择值如下：

1. docs：文档编号添加到倒排索引。
2. freqs：文档编号与访问频率。
3. positions：文档编号、访问频率、词位置（顺序性），proximity 和phrase queries 需要用到该模式。
4. offsets：文档编号，词频率，词偏移量（开始和结束位置）和词位置（序号），高亮显示，需要设置为该模式。
   默认情况下，被分析的字符串（analyzed string）字段使用positions，其他字段使用docs;

15、fields
fields允许对同一索引中同名的字段进行不同的设置，举例说明：

PUT my_index
{
  "mappings": {
    "_doc": {
      "properties": {
        "city": {
          "type": "text",        // @1
          "fields": {              // @2
            "raw": { 
              "type":  "keyword"   // @3
            }
          }
        }
      }
    }
  }
}

@1：上述映射为city字段，定义类型为text，使用全文索引。
@2：为city定义多字段，city.raw，其类型用keyword。
主要就可以用user进行全文匹配，也可以用user.raw进行聚合、排序等操作。另外一种比较常用的场合是对该字段使用不同的分词器。

16、norms
字段的评分规范，存储该规范信息，会提高查询时的评分计算效率。虽然规范对计分很有用，但它也需要大量磁盘(通常是索引中每个字段的每个文档一个字节的顺序，甚至对于没有这个特定字段的文档也是如此)。从这里也可以看出，norms适合为过滤或聚合的字段。
注意，可以通过put mapping api 将norms=true更新为norms=false，但无法从false更新到true。

17、null_value
将显示的null值替换为新定义的额值。用如下示例做一个说明：

PUT my_index
{
  "mappings": {
    "_doc": {
      "properties": {
        "status_code": {
          "type":       "keyword",
          "null_value": "NULL"             // @1
        }
      }
    }
  }
}

PUT my_index/_doc/1
{
  "status_code": null                     // @2
}

PUT my_index/_doc/2
{
  "status_code": []                       // @3
}

GET my_index/_search
{
  "query": {
    "term": {
      "status_code": "NULL"               // @4
    }
  }
}

代码@1：为status_code字段定义“NULL”为空值null；
代码@2：该处，存储在status_code为 null_value中定义的值，即"NULL"
代码@3：空数组不包含显式null，因此不会被null_value替换。
代码@4：该处查询，会查询出文档1。其查询结果如下：

{
    "took":4,
    "timed_out":false,
    "_shards":{
        "total":5,
        "successful":5,
        "skipped":0,
        "failed":0
    },
    "hits":{
        "total":1,
        "max_score":0.2876821,
        "hits":[
            {
                "_index":"mapping_test_null_value",
                "_type":"_doc",
                "_id":"RyjGEmcB-TTORxhqI2Zn",
                "_score":0.2876821,
                "_source":{
                    "status_code":null
                }
            }
        ]
    }
}

null_value具有如下两个特点：
null_value需要与字段的数据类型相同。例如，一个long类型的字段不能有字符串null_value。
null_value只会索引中的值（倒排索引），无法改变_souce字段的值。

18、position_increment_gap
针对多值字段，值与值之间的间隙。举例说明：

PUT my_index
{
  "mappings": {
    "_doc": {
      "properties": {
        "names": {
          "type": "text",
          "position_increment_gap": 0      // @1
          // "position_increment_gap": 10  // @2
        }
      }
    }
  }
}

PUT my_index/_doc/1
{
    "names": [ "John Abraham", "Lincoln Smith"]
}

names字段是个数组，也即ES中说的多值字段
当position_increment_gap=0时，es的默认使用标准分词器，分成的词根为：
position 0 : john
position 1 : abraham
position 2 : lincoln
position 3 : smith
当position_increment_gap = 10时，es使用默认分词器，分成的词根为：
position 0 : john
position 1 : abraham
position 11 : lincoln 这是第二个词，等于上一个词的position + position_increment_gap。
position 12 : smith

针对如下下查询：

GET my_index/_search
{
    "query": {
        "match_phrase": {
            "names": "Abraham Lincoln" 
        }
    }
}

针对position_increment_gap=0时，能匹配上文档，如果position_increment_gap=10,则无法匹配到文档，因为abraham与lincoln的位置相差10，如果要能匹配到该文档，需要在查询时设置slop=10，该参数在前面的DSL查询部分已详细介绍过。

19、properties
为映射类型创建字段定义。

20、search_analyzer
通常，在索引时和搜索时应用相同的分析器，以确保查询中的术语与反向索引中的术语具有相同的格式，如果想要在搜索时使用与存储时不同的分词器，则使用search_analyzer属性指定，通常用于ES实现即时搜索(edge_ngram)。

21、similarity
指定相似度算法，其可选值：

1. BM25
   当前版本的默认值，使用BM25算法。
2. classic
   使用TF/IDF算法，曾经是es,lucene的默认相似度算法。
3. boolean
   一个简单的布尔相似度，当不需要全文排序时使用，并且分数应该只基于查询条件是否匹配。布尔相似度为术语提供了一个与它们的查询boost相等的分数。

22、store
默认情况下，字段值被索引以使其可搜索，但它们不存储。这意味着可以查询字段，但无法检索原始字段值。通常这并不重要。字段值已经是_source字段的一部分，该字段默认存储。如果您只想检索单个字段或几个字段的值，而不是整个_source，那么这可以通过字段过滤上下文(source filting context来实现，在某些情况下，存储字段是有意义的。例如，如果您有一个包含标题、日期和非常大的内容字段的文档，您可能只想检索标题和日期，而不需要从大型_source字段中提取这些字段，es还提供了另外一种提取部分字段的方法，stored_fields，stored_fields过滤，只支持字段的store定义为ture，该部分内容已经在Elasticsearch Doc api时，_souce过滤部分详细介绍过，这里不过多介绍。

23、term_vector
term_vector包含分析过程产生的术语的信息，包括:

1. 术语列表。
2. 每一项的位置(或顺序)。
3. 开始和结束字符偏移量。
   term_vector可取值：

• no
  不存储term_vector信息，默认值。
• yes
  只存储字段中的值。
• with_positions
  存储字段中的值与位置信息。
• with_offsets
  存储字段中的值、偏移量
• with_positions_offsets
  存储字段中的值、位置、偏移量信息。