【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