【ES】【Reference 7.8 译】官方文档Mapping说明

Elasticsearch Reference 7.8

Mapping 映射

Mapping的组成

Mapping是定义一个文档及其包含的字段是否会被stored和indexed的过程。比如，可以使用Mapping定义：

• 哪些字符串字段作为full text字段
• 哪些字段包含numbers,dates或geolocations
• date值的格式
• 定制化控制动态添加字段的映射行为

一个Mapping定义包括两个部分：

Meta-fields 元数据字段：元数据字段用来定义文档相关的元数据的行为，比如_index, _id和_source。

Fields 或 properties：一个Mapping包括一组fields字段或与其相关的properties属性。

注：在7.0.0版本后Mapping定义去除了type字段，即在mapping定义后直接写字段定义即可，原因见 Removal of mapping types

Field data types 字段数据类型

每个field都有一个type属性，可以是：

• 简单类型如, keyword, date, long, double, boolean 或 ip
• 支持JSON层级结构的类型，如 或 nested
• 特殊的类型如 geo_point, geo_shape, 或 completion

同一个字段可以使用不同的方式检索。如，一个string字段可以作为 text被full-text检索，可以作为keyword字段，用于排序和聚合。可以使用分词器对string 字段进行分词。

大多数数据类型通过fields参数支持multi-field。

设置参数，防止映射字段爆炸

过多在设置映射的字段可能导致很多问题，如内存错误等无法恢复的错误。可以使用下面的参数限制映射中的字段数量（手动或自动创建的字段），从而阻止字段爆炸。

index.mapping.total_fields.limit 单个索引中的最大字段数量，默认1000个

index.mapping.depth.limit* 单个字段的最大深度，用于衡量内部对象的数量，默认20

index.mapping.depth.limit 单个索引中不同nested mappings的最大数量，默认50

index.mapping.nested_objects.limit 单个文档可以包含所有嵌套类型中的嵌套 JSON 对象的最大数量，默认10000

index.mapping.field_name_length.limit 字段名称最大长度，默认是Long.MAX_VALUE（无限制）

Dynamic mapping 动态映射

字段和映射类型并不需要在使用前定义。借助于dynamic mapping，新增文档时，如果有新字段，新字段会被自动映射。新字段可以添加到顶层映射类型，也可以添加到内部对象 object和nested 字段。

Explicit mappings 显式映射

如果想指定字段数据类型，则需要显式指定。可以在 create an index 和add fields to an existing index指定。

使用 create index API显式创建索引

PUT /my-index
{
  "mappings": {
    "properties": {
      "age":    { "type": "integer" },  
      "email":  { "type": "keyword"  }, 
      "name":   { "type": "text"  }     
    }
  }
}

使用 put mapping API添加一个或多个新字段到已有索引中

下面的例子添加了keyword类型的字段employee-id，同时index属性设置为false。这意味着，employee-id字段的值会被存储但是不能被查询。

PUT /my-index/_mapping
{
  "properties": {
    "employee-id": {
      "type": "keyword",
      "index": false
    }
  }
}

更新映射中的字段

除了支持的mapping parameters，不能修改一个已经存在的字段的mapping或类型。修改一个已经存在的字段会使已经存在的文档失效。如果确实需要修改字段映射，需要重新建立索引并使用reindex 迁移文档数据到新索引。

Field data types 字段数据类型

Elasticsearch 在一个文档中支持不同的字段数据类型。通过字段的type属性指定。

PUT my_index
{
  "mappings": {
    "properties": {
      "full_name": {
        "type":  "text"
      }
    }
  }
}

核心数据类型 Core data types

string

text and keyword

Numeric

long`, `integer`, `short`, `byte`, `double`, `float`, `half_float`, `scaled_float

Date

date

Date nanoseconds

date_nanos

Boolean

boolean

Binary

binary

Range

integer_range`, `float_range`, `long_range`, `double_range`, `date_range`, `ip_range

复杂数据类型 Complex data types

Object

object for single JSON objects

Nested

nested for arrays of JSON objects

地理数据类型 Geo data types

Geo-point

geo_point for lat/lon points

Geo-shape

geo_shape for complex shapes like polygons

专业数据类型 Specialised data type

IP

ip for IPv4 and IPv6 addresses

Completion data type

completion to provide auto-complete suggestions

Token count

token_count to count the number of tokens in a string

mapper-murmur3

murmur3 to compute hashes of values at index-time and store them in the index

mapper-annotated-text

annotated-text to index text containing special markup (typically used for identifying named entities)

Percolator

Accepts queries from the query-dsl

Join

Defines parent/child relation for documents within the same index

Rank feature

Record numeric feature to boost hits at query time.

Rank features

Record numeric features to boost hits at query time.

Dense vector

Record dense vectors of float values.

Sparse vector

Record sparse vectors of float values.

Search-as-you-type

A text-like field optimized for queries to implement as-you-type completion

Alias

Defines an alias to an existing field.

Flattened

Allows an entire JSON object to be indexed as a single field.

Shape

shape for arbitrary cartesian geometries.

Histogram

histogram for pre-aggregated numerical values for percentiles aggregations.

Constant keyword

Specialization of keyword for the case when all documents have the same value.

Arrays

Elasticsearch中，不需要一个专门的数组数据类型。数组中的数据类型必须相同。Arrays

Multi-fields

根据不同的目的可以对同一字段使用不同的方式检索。如，一个string字段可以作为 text被full-text检索，可以作为keyword字段，用于排序和聚合。可以使用分词器对string 字段进行分词。Most data types support multi-fields via the fields parameter.

Meta-Fields 元数据字段

每个文档都有与之关联的元数据，比如_index，mapping _type和_id 元数据字段。这些元字段可以在mapping type创建时指定。

标识元字段 Identity meta-fields

_index	The index to which the document belongs.
_type	The document’s mapping type.
_id	The document’s ID.

文档source 元字段 Document source meta-fields

_source

The original JSON representing the body of the document.

_size

The size of the _source field in bytes, provided by the mapper-size plugin.

检索元字段 Indexing meta-fields

_field_names

All fields in the document which contain non-null values.

_ignored

All fields in the document that have been ignored at index time because of ignore_malformed.

路由元字段 Routing meta-field

_routing

A custom routing value which routes a document to a particular shard.

其他元字段 Other meta- field

_meta

Application specific metadata

Mapping Parameters 映射参数

下面的每项提供了 field mappings的属性的映射参数的详细解释，即每个字段都可以有以下属性。

• analyzer 只有 text支持该映射参数

  PUT my_index
  {
     "settings":{
        "analysis":{
           "analyzer":{
              "my_analyzer":{ 
                 "type":"custom",
                 "tokenizer":"standard",
                 "filter":[
                    "lowercase"
                 ]
              },
              "my_stop_analyzer":{ 
                 "type":"custom",
                 "tokenizer":"standard",
                 "filter":[
                    "lowercase",
                    "english_stop"
                 ]
              }
           },
           "filter":{
              "english_stop":{
                 "type":"stop",
                 "stopwords":"_english_"
              }
           }
        }
     },
     "mappings":{
         "properties":{
            "title": {
               "type":"text",
               "analyzer":"my_analyzer", 
               "search_analyzer":"my_stop_analyzer", 
               "search_quote_analyzer":"my_analyzer" 
           }
        }
     }
  }
  
  PUT my_index/_doc/1
  {
     "title":"The Quick Brown Fox"
  }
  
  PUT my_index/_doc/2
  {
     "title":"A Quick Brown Fox"
  }
  
  GET my_index/_search
  {
     "query":{
        "query_string":{
           "query":""the quick brown fox"" 
        }
     }
  }
  

• boost

• coerce

• copy_to 允许将多个字段值复制到一个新的分组字段中，这个字段可以作为单个字段被查询。

• doc_values 默认情况下，大部分字段都是indexed，这样才可以被搜索。该设置默认为true。They store the same values as the _source but in a column-oriented fashion that is way more efficient for sorting and aggregations. Doc values are supported on almost all field types, with the notable exception of text and annotated_text fields.

• dynamic

• eager_global_ordinals

• enabled Elasticsearch会尝试index所有映射的字段，但是有时我们只希望存储字段而不想index它。该属性只能应用于top-level mapping 定义，以及只能应用于object字段。设置false会使Elasticsearch完全跳过解析该字段。但是该JSON仍可从_source字段获取，但是无法以任何形势搜索和stored。

  PUT my_index
  {
    "mappings": {
      "properties": {
        "user_id": {
          "type":  "keyword"
        },
        "last_updated": {
          "type": "date"
        },
        "session_data": { 
          "type": "object",
          "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"
  }
  
  PUT my_index/_doc/session_2
  {
    "user_id": "jpountz",
    "session_data": "none", 
    "last_updated": "2015-12-06T18:22:13"
  }
  

• fielddata

• fields 多字段属性，允许针对同一字段以不同方式检索。

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

• format 在JSON文档中，date是字符串。Elasticsearch可以配置日期格式，将时间解析为long类型的 UTC 毫秒值

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

• ignore_above

• ignore_malformed

• index_options

• index_phrases

• index_prefixes

• index 控制字段是否可以被检索

• meta

• normalizer

• norms 用于计算score。如果不需要字段被计算score，应该关闭，计算占用空间。

• null_value A null value cannot be indexed or searched. When a field is set to null, (or an empty array or an array of null values) it is treated as though that field has no values.

• position_increment_gap

• properties

• search_analyzer

• similarity

• store 默认情况下，字段值是indexed的，这样才能被搜索。但是它们默认是不存储的。也就是说这个字段可以被查询，但是不能获取到原始值。通常情况下，这没关系，因为字段值都存储在_source字段了，默认都会存储到该字段。如果只想获取一个或一些字段而非整个_source，可以使用source filtering。

  在某些情况下，store一个字段也是有意义的。比如，如果有一个文档包括tile，date 和一个非常大的content字段，你可能只希望获取title和date而不是从_source字段中抽取这两个字段:

  // The title and date fields are stored.
  PUT my_index
  {
    "mappings": {
      "properties": {
        "title": {
          "type": "text",
          "store": true 
        },
        "date": {
          "type": "date",
          "store": true 
        },
        "content": {
          "type": "text"
        }
      }
    }
  }
  
  PUT my_index/_doc/1
  {
    "title":   "Some short title",
    "date":    "2015-01-01",
    "content": "A very long content field..."
  }
  
  GET my_index/_search
  {
    "stored_fields": [ "title", "date" ]// This request will retrieve the values of the title and date fields.
  }
  

• term_vector