Elasticsearch系列（7）Mapping之参数

前言

映射参数（mapping parameters）用于字段类型的映射，每个字段类型有一个或多个映射参数搭配使用，每个映射参数都有其特定的作用，以下是对字段映射使用的一些重要映射参数的说明。

• 上图是映射参数表，列出了一些重要的映射参数。

analyzer

• analyzer参数指定一个用于索引text字段时的文本分析的分析器，如果search_analyzer参数没有覆盖，该分析器也用于搜索时的文本分析。
• 只有text字段支持analyzer参数。
• 例如，自定义一个分析器，分析器的分词器tokenizer采用standard（按空格先拆分词）， 过滤器filter使用lowercase（转换为小写）， 通过analyzer参数指定该分析器，示例如下：

PUT my_index_01
{
   "settings":{
      "analysis":{
         "analyzer":{
            "my_analyzer":{ 
               "type":"custom",
               "tokenizer":"standard",
               "filter":[
                  "lowercase"
               ]
            }
         }
      }
   },
   "mappings":{
       "properties":{
          "title": {
             "type":"text",
             "analyzer":"my_analyzer"
         }
      }
   }
}
PUT my_index_01/_doc/1
{"title":"The Quick Brown Fox"}
# 通过小写也可以查询匹配结果数据
GET my_index_01/_search
{"query":{"query_string":{"query":"the quick brown fox"}}}

search_analyzer

• 默认情况下，搜索时将使用参数analyzer定义的分析器，从而保持与索引时一样的分析器，不过可以设置search_analyzer来覆盖搜索时的分析器，示例如下：

#  双斜线//在执行时需要去掉
PUT my_index_01
{
  "settings": {
    "analysis": {
      "filter": {
        "autocomplete_filter": {
          "type": "edge_ngram",
          "min_gram": 1,
          "max_gram": 20
        }
      },
      "analyzer": {
        "autocomplete": { 
          "type": "custom",
          "tokenizer": "standard",
          "filter": [
            "lowercase",
            "autocomplete_filter"
          ]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "text": {
        "type": "text",
        "analyzer": "autocomplete", 
        "search_analyzer": "standard" 
      }
    }
  }
}
PUT my_index_01/_doc/1 //1
{"text":"Quick Brown Fox"} 
GET my_index_01/_search //2
{"query":{"match":{"text":{"query":"Quick Br","operator":"and"}}}}

注释1：字段索引时拆分后的词条：[ q, qu, qui, quic, quick, b, br, bro, brow, brown, f, fo, fox ]
注释2：字段搜索时拆分后的词条：[ quick, br ]

search_quote_analyzer

• search_quote_analyzer参数指定一个短语分析器，在处理短语查询（phrases query）禁用停止词时特别有用，当search_quote_analyzer参数设置时，analyzer参数和search_analyzer参数也必须设置。
• 禁用字段的短语的停止词示例如下：

#  双斜线//在执行时需要去掉
PUT my_index_01
{
   "settings":{
      "analysis":{
         "analyzer":{
            "my_analyzer":{  //1
               "type":"custom",
               "tokenizer":"standard",
               "filter":[
                  "lowercase"
               ]
            },
            "my_stop_analyzer":{  //2
               "type":"custom",
               "tokenizer":"standard",
               "filter":[
                  "lowercase",
                  "english_stop"
               ]
            }
         },
         "filter":{
            "english_stop":{
               "type":"stop",
               "stopwords":"_english_"
            }
         }
      }
   },
   "mappings":{
       "properties":{
          "title": {
             "type":"text",
             "analyzer":"my_analyzer",  //3
             "search_analyzer":"my_stop_analyzer",  //4
             "search_quote_analyzer":"my_analyzer"  //5
         }
      }
   }
}
PUT my_index_01/_doc/1
{"title":"The Quick Brown Fox"}
PUT my_index_01/_doc/2
{"title":"A Quick Brown Fox"}
GET my_index_01/_search
{"query":{"query_string":{"query":"\"the quick brown fox\""}}}  //6

注释1：my_analyzer分析器将标记所有词元包括停用词，且标记的词元为小写。比如文本“The Quick Brown Fox”经过分析分词后变成[the，quick，brown，fox]。
注释2：my_stop_analyzer分析器将会移除停用词，比如文本“The Quick Brown Fox”经过分析分词后变成[quick， brown， fox]，停用词不会被标记。
注释3：analyzer指定索引时使用的分析器，设置为my_analyzer。
注释4：search_analyzer指定搜索时使用的分析器，设置为my_stop_analyzer。
注释5：search_quote_analyzer参数设置为my_analyzer。确保短语查询时停用词不会被移除。
注释6：由于查询被包装在引号中，因此会检测到短语查询，因此会使用search_quote_analyzer来确保停止词不会从查询中删除。然后，my_analyzer将返回以下标记[The, quick, brown, fox]，这些标记将匹配其中一个文档。同时，词条查询将用my_stop_analyzer分析，它将过滤掉停止词。因此，搜索“The quick brown fox”或“A quick brown fox”都会返回两个文档，因为两个文档都包含以下标记[quick, brown, fox]。如果没有search_quote_analyzer，就不可能对短语查询进行精确匹配，因为短语查询中的停止词将被删除，从而导致两个文档都匹配。

boost

• 通过设置boost参数的值，改变相关性得分的计算，进而可以影响单个字段相比于其他字段在查询时自动提升。
• 示例如下：

#  双斜线//在执行时需要去掉
PUT my_index_01
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "boost": 2
      },
      "content": {
        "type": "text"
      }
    }
  }
}
PUT my_index_01/_doc/1
{"title":"Quick Fox","content":"Brown Fox"}
PUT my_index_01/_doc/2
{"title":"Brown Fox","content":"Quick Fox"}
GET my_index_01/_search //1
{
  "query": {
    "bool": {
      "should": [
        {
          "query_string": {
            "default_field": "title",
            "query": "Brown"
          }
        },
        {
          "query_string": {
            "default_field": "content",
            "query": "Brown"
          }
        }
      ]
    }
  }
}

注释1：查询时，title字段上匹配项的权重是content字段上的两倍，boost默认是1.0，查询出结果文档2得分是文档1得分的两倍。

• boost只应用于查询时提升，并且仅应用于词条查询(前缀、范围和模糊查询不被增强)。
• 也可以通过在查询中直接使用boost参数来实现相同的效果。示例如下：

POST my_index_01/_search
{"query":{"match":{"title":{"query":"Quick Fox","boost":2}}}}

coerce

• coerce（强制）参数默认值true，表示尝试清除脏数据值，以符合字段的数据类型，例如，如果字段数据类型为整数类型，那么输入的字符串强制转换为数字，浮点数将被截断。如果coerce参数设置为false，那么遇到脏数据不会进行强制转换，而是直接抛出异常。
  示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "number_one": {
        "type": "integer"
      },
      "number_two": {
        "type": "integer",
        "coerce": false
      }
    }
  }
}
# 因为coerce参数设置false，所以直接抛出异常
PUT my_index_01/_doc/1
{"number_two":"5"}

• 通过配置参数index.mapping.coerce，可以进行索引级别的禁用coercion，类型级别的coercion作用优先级大于索引级别，示例如下：

PUT my_index_01
{
  "settings": {
    "index.mapping.coerce": false
  },
  "mappings": {
    "properties": {
      "number_one": {
        "type": "integer",
        "coerce": true
      },
      "number_two": {
        "type": "integer"
      }
    }
  }
}
# 类型级别的coercion设置开启，成功索引，强制转换数据
PUT my_index_01/_doc/1
{ "number_one": "10" } 
# 字段number_two继承索引级coercion的设置，直接抛出异常
PUT my_index_01/_doc/2
{ "number_two": "10" } 

copy_to

• copy_to参数用于将多个字段的值复制到组合字段中，然后可以将这个组合字段作为单个字段进行查询。如果经常搜索多个字段，可以通过copy_to参数来搜索更少的字段，进而提高搜索速度，操作示例如下：

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

PUT my_index_01/_doc/1
{"first_name":"John","last_name":"Smith"}
GET my_index_01/_search
{
  "query": {
    "match": {
      "full_name": {
        "query": "John Smith",
        "operator": "and"
      }
    }
  }
}

doc_values

• doc_values参数为true表示激活字段的Doc Values，默认情况下每个字段的 Doc Values 都是激活的。几乎所有类型字段都支持doc_values参数，只有text和annotated_text字段除外。
• Doc Values是一个列式存储结构，在索引时创建的，当字段索引时，Elasticsearch 为了能够快速检索，会把字段的值加入到倒排索引中，同时它也会存储该字段的Doc Values。
• Doc Values支持需要在每个文档基础上查找字段值的聚合、排序等其他操作，它常被应用到以下场景：
  （1）对一个字段进行排序
  （2）对一个字段进行聚合
  （3）某些过滤，比如地理位置过滤
  （4）某些与字段相关的脚本计算
  这些场景使用Doc Values列式结构比倒排索引结构有很大优势。
• 字段的Doc Values需要很大的空间开销，如果确定一个字段不需要排序或聚合，或脚本访问字段值，那么可以禁用字段Doc Values，以节省磁盘空间，示例如下:

# session_id字段已经禁用Doc Values，它仍然可以继续被查询，只是有些场景查询效率没那么理想
PUT my_index_01
{
  "mappings": {
    "properties": {
      "status_code": {
        "type":       "keyword"
      },
      "session_id": {
        "type":       "keyword",
        "doc_values": false
      }
    }
  }
}

dynamic

通过设置参数dynamic，可以在文档和对象级别控制动态映射，参数dynamic可以设置为下列三种值：
（1）true：将新的检测到的字段添加到映射中。(默认)
（2）false：忽略新检测到的字段。这些字段将不会被索引，因此不能被搜索，但仍然会出现在返回命中的_source字段中。这些字段将不会添加到映射中，新的字段必须显式添加。
（3）strict：如果检测到新字段，则抛出异常并拒绝索引文档。新字段必须显式地添加到映射中。
操作示例如下：

# 1 - dynamic设置为strict，并且是类型级别，表示不会动态添加top级字段
# 2 - user 对象继承类型级别设置
# 3 - dynamic设置为true，并且是对象级别，表示social_networks对象可以动态添加字段
PUT my_index
{
  "mappings": {
    "dynamic": "strict", // 1
    "properties": { 
      "user": {              // 2
        "properties": {
          "social_networks": { 
            "dynamic": "true", // 3
            "properties": {}
          }
        }
      }
    }
  }
}

eager_global_ordinals

• eager_global_ordinals参数设置为true表示开启全局序数映射，false表示禁止全局序数映射，默认true。
• 如果是基于词条的字段类型(如关键字)， Elasticsearch会根据词汇顺序为每个词条分配的一个递增的整数或有序数，然后使用序数映射存储的doc值，以获得更紧凑的表示。
• 字段的doc值只存储序数，而不是原始的词条，使用单独的查找结构在序数和词条之间进行转换，每个索引分段定义自己的有序映射，但是聚合在整个碎片上收集数据。因此，为了能够在分片级操作(如聚合)中使用序数，Elasticsearch创建了一个称为全局序数的统一映射。全局序号映射建立在分段序数之上，通过维护每个分段从全局序数到局部序数的映射来工作。
• 在搜索过程中使用序数之前，必须先构建全局序数映射。默认情况下，在搜索第一次需要全局序数时加载全局序数映射。通过全局序数映射可以提升聚合、排序等操作性能，开启示例如下：

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

• 全局序数在加载时间和内存使用方面通常不会带来很大的开销。但是如果索引具有较大的碎片，或者字段包含大量唯一的词条值，则加载全局序数的开销可能很大。因为全局序数为分片上的所有分段提供了统一的映射，所以当一个新的分段创建可见后，全局序数还需要完全地重新构建。
• eager_global_ordinals不应该用于冻结的索引，对于一个冻结索引，全局序数在每次搜索时重建后被丢弃，当请求它们时重新构建，这导致在每次搜索时重新加载全局序数。有效方法是，可以在冻结之前，索引应该被强制合并到单个段，这样就避免了每次构建全局序数。

enabled

• enabled参数控制字段是否被Elasticsearch索引，默认情况下，Elasticsearch会尝试索引所有输入的字段。通过设置enabled为false来禁止索引字段，禁止后Elasticsearch会完全跳过字段内容的解析（异常类型的数据也会完全忽略）。虽然仍然可以从_source字段检索，但它不能以任何其他方式搜索或存储。
• enabled只能应用于顶级mapping定义和object字段中。
• 例如，假设使用Elasticsearch作为web会话存储，希望只索引会话ID和上次更新时间，但不需要对会话数据本身查询或运行聚合，操作示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "user_id": {
        "type": "keyword"
      },
      "last_updated": {
        "type": "date"
      },
      "session_data": { //1
        "type": "object",
        "enabled": false
      }
    }
  }
}

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

PUT my_index_01/_doc/session_2
{
  "user_id": "jpountz",
  "session_data": "none", //3
  "last_updated": "2015-12-06T18:22:13"
}

注释1：session_data字段被禁用。
注释2：任何数据都可以传递到session_data字段，因为它将被完全忽略。
注释3：session_data也会忽略非JSON对象的值。

• 整个mapping中也可设置被禁用，在这种情况下，文档会存储在
  _source字段中，但文档的内容不会以任何方式索引。操作示例如下：

PUT my_index_01
{"mappings":{"enabled":false}}

fielddata

• 如果搜索需要回答“哪些文档包含这个词条?”，而排序和聚合需要回答另一个问题:“这个文档的这个字段的值是多少?”，大多数字段可以使用doc_valuse数据访问模式来回答这些问题，但是text类型不支持doc_valuse，所以Elasticsearch提供了另外一种数据结构可用于text类型字段，它就是fielddata数据结构，fielddata存储内存中，查询时构建，相反doc_valuse存储磁盘上、索引时构建。具体点说，fielddata数据结构是在字段第一次用于聚合、排序或在脚本中使用时按需构建的。通过读取磁盘中每个分段的倒排索引，获取词条与文档的关系并进行逆转，最后将结果存储在JVM堆内存中。
• 默认情况下，text类型字段会禁用fielddata，因为fielddata会消耗大量堆空间，特别是在加载高基数文本字段时。一旦fielddata被加载到堆中，它在分段生命周期中一直存在。此外，加载fielddata是一个昂贵的过程，可能会导致用户体验延迟。这就是为什么默认情况下禁用fielddata的原因。开启操作示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "tag": {
        "type": "text",
        "fielddata": true,
        "fielddata_frequency_filter": { //1
          "min": 0.001,
          "max": 0.1,
          "min_segment_size": 500
        }
      }
    }
  }
}

注释1： fielddata_frequency_filter频率过滤器用于减少加载到内存中的词条的数量，只加载每分段文档频率在min和max之间的分段，min和max的值是0到1范围的浮点数值，min_segment_size指定分段中应该包含的最小文档数，这样可以完全排除小的分段。
每分段文档频率=分段中字段有值文档数/分段中总的文档数

• 一般不建议开启fielddata。如果既需要text类型字段用于全文搜索，也需要字段未分析以便能聚合操作，那么可以再定义一个未分析的keyword类型字段，它可以使用doc_values数据结构来进行聚合等操作，示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "my_field": {
        "type": "text", //1
        "fields": {
          "keyword": { //2
            "type": "keyword" 
          }
        }
      }
    }
  }
}

注释1：使用my_field字段来进行全文搜索。
注释2：使用my_field.keyword字段来进行聚合、排序或在脚本中使用。

fields

• fields参数用于提供多字段。使得字段具有多种类型的功能。fields不会修改原始字段_source的值。
• 操作示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "city": {
        "type": "text",
        "fields": {
          "raw": { 
            "type":  "keyword"
          }
        }
      }
    }
  }
}
PUT my_index_01/_doc/1
{"city":"New York"}
PUT my_index_01/_doc/2
{"city":"York"}
GET my_index_01/_search
{
  "query": {
    "match": {
      "city": "york" 
    }
  },
  "sort": {
    "city.raw": "asc" 
  },
  "aggs": {
    "Cities": {
      "terms": {
        "field": "city.raw" 
      }
    }
  }
}

• 多字段用于多分析器，示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "text": { //1
        "type": "text",
        "fields": {
          "english": { //2
            "type":     "text",
            "analyzer": "english"
          }
        }
      }
    }
  }
}

PUT my_index_01/_doc/1
{ "text": "quick brown fox" } 
PUT my_index_01/_doc/2
{ "text": "quick brown foxes" } 
GET my_index_01/_search
{
  "query": {
    "multi_match": {
      "query": "quick brown foxes",
      "fields": [ //3
        "text",
        "text.english"
      ],
      "type": "most_fields" //3
    }
  }
}

注释1：text字段使用standard分析器。
注释2：text.english字段使用english分析器。
注释3：通过text和text.english字段合并得分。

format

• 通过format参数设置日期格式，参数值需要符合日期格式语法。自定义格式操作如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "date": {
        "type": "date",
        "format": "yyyy-MM-dd"
      }
    }
  }
}

• 支持日期格式语法包括但不限以下这些：
  （1）epoch_millis：long类型整数，表示自纪元以来的毫秒数
  （2）epoch_second：long类型整数，表示自纪元以来的秒数
  （3）date_optional_time or strict_date_optional_time：形式如
  yyyy-MM-dd'T'HH:mm:ss.SSSZ 或yyyy-MM-dd。
  （4）strict_date_optional_time_nanos：形式如
  yyyy-MM-dd 'HH: mm: ss。SSSSSSZ或yyyy-MM-dd。
  （5）basic_date：形式如yyyyMMdd。
  （6）basic_date_time：形式如yyyyMMdd'T'HHmmss.SSSZ。
  （7）basic_date_time_no_millis：形式如yyyyMMdd'T'HHmmssZ。
  （8）basic_ordinal_date：形式如yyyyDDD。
  （9）basic_ordinal_date_time：形式如yyyyDDD'T'HHmmss.SSSZ。
  （10）basic_time：HHmmss.SSSZ。
  （11）basic_time_no_millis：HHmmssZ。
  （12）basic_t_time：'T'HHmmss.SSSZ。
  更多参考官方文档

ignore_above

• 字段的字符串长度超过ignore_above参数设置的值将不会被索引或存储。对于字符串数组，ignore_above将分别应用于每个数组元素，长度超过ignore_above值的字符串元素将不会被索引或存储，但是在_source字段中仍然会存在此元素。操作示例如下:

PUT my_index_01
{
  "mappings": {
    "properties": {
      "message": {
        "type": "keyword",
        "ignore_above": 20 
      }
    }
  }
}

PUT my_index_01/_doc/1
{"message":"Syntax error"}
PUT my_index_01/_doc/2
{"message":"Syntax error with some long stacktrace"} //1

注释1：该文档将被索引，由于长度超过设置值，不会索引message字段

ignore_malformed

• 如果在字段中索引错误的数据类型，默认情况下会抛出异常，并拒绝整个文档。ignore_malform参数如果设置为真，则允许忽略异常，格式不正确的字段没有索引，但是文档中的其他字段会正常处理。操作示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "number_one": {
        "type": "integer",
        "ignore_malformed": true
      },
      "number_two": {
        "type": "integer"
      }
    }
  }
}
# 文档能索引成功，忽略number_one字段的值
PUT my_index_01/_doc/1
{"text":"Some text value","number_one":"foo"}
#  直接拒绝，抛出异常
PUT my_index_01/_doc/2
{"text":"Some text value","number_two":"foo"}

• index.mapping.ignore_malform可在索引级别上设置。用来在所有允许的类型上全局忽略格式不正确的内容。此外，索引级别的设置会被类型级别的设置覆盖。操作示例如下：

PUT my_index_01
{
  "settings": {
    "index.mapping.ignore_malformed": true
  },
  "mappings": {
    "properties": {
      "number_one": {
        "type": "byte"
      },
      "number_two": {
        "type": "integer",
        "ignore_malformed": false
      }
    }
  }
}

index

• index参数控制字段值是否被索引。它接受true或false，默认为true。没有索引的字段是不可查询的。该参数与enabled参数有一定区别：
  （1）enabled参数只作用与object字段或顶级mapping中，如果设置了enabled为false，那么不能同时设置store为true。
  （2）index参数作用于其他类型字段，并且可以和store参数同时使用。
• 禁用字段index操作示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "text": {
        "type": "text",
        "index": false
      }
    }
  }
}

index_options

• index_options参数控制将哪些信息添加到倒排索引中，用于搜索和高亮显示。
• index_options参数仅用于text字段。
• index_options参数接受下列值：
  （1）docs：只有文档编号被索引。
  （2）freqs：文档编号和词条频率（词条出现次数）被索引。词频用于给重复词评分高于单个词评分。
  （3）positions (默认)：文档编号、词条频率和词条位置(或顺序)被索引。位置可用于邻近度或短语查询。
  （4）offsets：对文档编号、词条频率、位置以及开始和结束字符偏移量(将词条映射回原始字符串)进行索引。统一高亮器使用偏移量来加快高亮的速度。
• 操作示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "text": {
        "type": "text",
        "index_options": "offsets"
      }
    }
  }
}
PUT my_index_01/_doc/1
{"text":"Quick brown fox"}
GET my_index_01/_search
{
  "query": {
    "match": {
      "text": "brown fox"
    }
  },
  "highlight": {
    "fields": {
      "text": {} 
    }
  }
}

index_phrases

• index_phrases如果被启用，则将两个词条的单词组合编入一个单独的字段。这允许精确短语查询更高效地运行，但以更大的索引为代价。注意，当停用词没有被删除时，这种方法的效果最好，因为包含停用词的短语将不会使用子字段，并且会退回到标准短语查询。该参数接受true或false(默认)。示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "text": {
        "type": "text",
        "index_phrases": "true"
      }
    }
  }
}

index_prefixes

• index_prefixes参数允许对词条前缀进行索引，以加速前缀搜索。它接受以下可选设置:
  （1）min_chars：索引的最小前缀长度（包含）。必须大于0，默认值为2。
  （2）max_chars：索引的最大前缀长度（包含）。必须小于20，默认值为5。
  操作示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "full_name": {
        "type": "text",
        "index_prefixes": {
          "min_chars" : 1,
          "max_chars" : 10
        }
      }
    }
  }
}

meta

• meta参数设置附加到字段的元数据。这个元数据对Elasticsearch来说是不透明的，它既不会存储于_source字段，也不会用于搜索、排序等操作，它只对在相同索引上工作的多个应用程序有用，以共享关于字段的元信息。操作示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "latency": {
        "type": "long",
        "meta": {
          "unit": "ms"
        }
      }
    }
  }
}

normalizer

• normalizer归一化器作用于keyword字段，常在以下情况使用：
  （1）对keyword字段进行索引之前。
  （2）通过查询解析器(如match查询)搜索keyword字段时。
  （3）通过词条级查询(如term查询)搜索keyword字段。
  操作示例如下：

PUT my_index_01
{
  "settings": {
    "analysis": {
      "normalizer": {
        "my_normalizer": { //1
          "type": "custom",
          "char_filter": [],
          "filter": ["lowercase", "asciifolding"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "foo": {
        "type": "keyword",
        "normalizer": "my_normalizer"
      }
    }
  }
}
PUT my_index_01/_doc/1 
{"foo":"BÀR"} //2
PUT my_index_01/_doc/2
{"foo":"bar"} //2
POST my_index_01/_refresh
GET my_index_01/_search 
{"query":{"term":{"foo":"BAR"}}} //2
GET my_index_01/_search 
{"query":{"match":{"foo":"BAR"}}} //2

注释1：自定义归一化器，其过滤器使用lowercase（转换为小写）和asciifolding（转换ascii编码格式字体）
注释2：索引和查询时，BÀR、BAR都会转换为bar。

norms

• norms存储各种各样的归一化因子，在后续查询时使用，以便计算一个查询的文档相关性得分。
• 虽然norms对于评分很有用，但它也需要大量的磁盘空间。因此，如果不需要在某个特定领域计算得分，应该禁用该领域的norms（默认禁用），特别是仅用于过滤或聚合的字段。禁用norms操作如下：

PUT my_index_01/_mapping
{
  "properties": {
    "title": {
      "type": "text",
      "norms": false
    }
  }
}

• 禁用后，归一化因子不会立即被删除，但是当继续索引新的文档时，旧的分段会被合并成新的分段，归一化因子就会被删除。在归一化因子被删除的字段上的任何分数计算都可能返回不一致的结果，因为一些文档不再有归一化因子，而其他文档可能仍然有归一化因子。

null_value

• 一个null值不能被索引或搜索。当一个字段被设置为null(或一个空数组或一个空值数组)时，该字段被视为没有值。
• null_value参数默认值为null，可以指定值来替换显式的空值，以便对其进行索引和搜索。操作示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "status_code": {
        "type": "keyword",
        "null_value": "NULL" //1
      }
    }
  }
}
PUT my_index_01/_doc/1
{"status_code":null} 
PUT my_index_01/_doc/2
{"status_code":[null]}
GET my_index_01/_search
{"query":{"term":{"status_code":"NULL"}}} //2

注释1：null值被替换为字符串NULL
注释2：文档1和文档2包括null值或null值元素，所以全部查询出来

• null_value指定值不会修改_source字段的内容。

position_increment_gap

文本字段在分析时会考虑词条的位置，以便能够支持邻近或短语查询。当索引具有多个值的文本字段时，在值之间添加一个“假”间隙，以防止大多数短语查询在值之间匹配。这个间隙的大小使用position_increment_gap配置，默认值为100。

PUT my_index_01/_doc/1
{"names":["John Abraham","Lincoln Smith"]}
GET my_index_01/_search  //1
{
  "query": {
    "match_phrase": {
      "names": {
        "query": "Abraham Lincoln"
      }
    }
  }
}
GET my_index_01/_search  //2
{
  "query": {
    "match_phrase": {
      "names": {
        "query": "Abraham Lincoln",
        "slop": 101 
      }
    }
  }
}

注释1：此短语查询与文档不匹配，查无匹配数据
注释2：此短语查询匹配文档，即使Abraham和Lincoln在不同的字符串中，因为slop > position_increment_gap，slop参数告诉match_phrase查询词条能够相隔多少空隙时仍然将文档视为匹配。

• 可以修改参数position_increment_gap的值，示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "names": {
        "type": "text",
        "position_increment_gap": 0
      }
    }
  }
}

properties

• 类型映射、object字段和nested字段包含的子字段称为属性（properties）。这些属性可以是任何数据类型，包括object和nested。属性可以在通过下列方式添加:
  （1）通过在创建索引时显式地定义它们。
  （2）通过在使用PUT Mapping API添加或更新映射类型时显式地定义它们。
  （3）动态地索引包含新字段的文档。
• 创建索引时显式地定义示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": { 
      "manager": {
        "properties": { 
          "age":  { "type": "integer" },
          "name": { "type": "text"  }
        }
      },
      "employees": {
        "type": "nested",
        "properties": { 
          "age":  { "type": "integer" },
          "name": { "type": "text"  }
        }
      }
    }
  }
}

similarity

• similarity相似度用于配置每个字段的评分算法或相似度算法。默认的评分算法是BM25。
• similarity参数主要用于文本字段，但也可以应用于其他字段类型。
• similarity参数支持的配置值有BM25和boolean（布尔相似性会给词条一个与查询boost相等的分数）。可以字段的similarity配置，示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "default_field": { 
        "type": "text"
      },
      "boolean_sim_field": {
        "type": "text",
        "similarity": "boolean" 
      }
    }
  }
}

store

• 默认情况下，字段值被索引以使其可搜索，但不会被存储。这意味着可以查询字段，但不能检索原始字段值。通常这并不重要。字段值已经是_source字段的一部分，该字段默认存储。 如果您只想检索单个字段或几个字段的值，而不是整个_source的值，则可以使用source filtering来实现。
• 在某些情况下，文本的内容可能过大，我们不想将所有文本内容存储在_source字段，但有些字段内容又希望能被查找到，在这种情况下，可以使用store参数。例如，如果有一个有标题的文档，一个日期，和一个非常大的内容字段，我们只想要获取标题和日期内容，但又不想要内容字段，操作示例如下：

PUT my_index_01
{
  "mappings": {
    "_source": {
      "enabled": false
    },
    "properties": {
      "title": {
        "type": "text",
        "store": true 
      },
      "date": {
        "type": "date",
        "store": true 
      },
      "content": {
        "type": "text"
      }
    }
  }
}
PUT my_index_01/_doc/1
{
  "title":   "Some short title",
  "date":    "2015-01-01",
  "content": "A very long content field..."
}
GET my_index_01/_search
{
  "stored_fields": [
    "title",
    "date"
  ],
  "query": {
    "match": {
      "content": "content"
    }
  }
}

term_vector

• 词条向量包含着分析过程中产生的词条的相关信息，这些信息包括:
  （1）词条列表。
  （2）每一个词条的位置(或顺序)。
  （3）将词条映射到其所在的原始字符串中的开始和结束字符偏移量。
  （4）可用的有效载荷—用户定义的与每个词条位置相关联的二进制数据。
• 词条向量可以被存储，以便能对特定文档检索它们。
• term_vector参数支持以下配置值：
  （1）no：不存储词条向量(默认)。
  （2）yes：只存储字段中的词条。
  （3）with_positions：存储词条和位置。
  （4）with_offsets：存储词条和字符偏移量。
  （5）with_positions_offsets：存储词条、位置和字符偏移量。
  （6）with_positions_payloads：存储词条、位置和有效载荷。
  （7）with_positions_offsets_payloads：存储词条、位置、偏移量和有效载荷。
• term_vector参数设置操作示例如下：

PUT my_index_01
{
  "mappings": {
    "properties": {
      "text": {
        "type": "text",
        "term_vector": "with_positions_offsets"
      }
    }
  }
}

PUT my_index_01/_doc/1
{"text":"Quick brown fox"}

结语

至此，本文对Elasticsearch Mapping中常用且重要的参数已做了一个基本大致介绍，后续有时间会进一步分析并介绍映射参数的作用及其底层原理。