field-mapping.asciidoc 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132
  1. [[dynamic-field-mapping]]
  2. === Dynamic field mapping
  3. By default, when a previously unseen field is found in a document,
  4. Elasticsearch will add the new field to the type mapping. This behaviour can
  5. be disabled, both at the document and at the <<object,`object`>> level, by
  6. setting the <<dynamic,`dynamic`>> parameter to `false` (to ignore new fields) or to `strict` (to throw
  7. an exception if an unknown field is encountered).
  8. Assuming `dynamic` field mapping is enabled, some simple rules are used to
  9. determine which datatype the field should have:
  10. [horizontal]
  11. *JSON datatype*:: *Elasticsearch datatype*
  12. `null`:: No field is added.
  13. `true` or `false`:: <<boolean,`boolean`>> field
  14. floating{nbsp}point{nbsp}number:: <<number,`float`>> field
  15. integer:: <<number,`long`>> field
  16. object:: <<object,`object`>> field
  17. array:: Depends on the first non-`null` value in the array.
  18. string:: Either a <<date,`date`>> field
  19. (if the value passes <<date-detection,date detection>>),
  20. a <<number,`double`>> or <<number,`long`>> field
  21. (if the value passes <<numeric-detection,numeric detection>>)
  22. or a <<text,`text`>> field, with a <<keyword,`keyword`>> sub-field.
  23. These are the only <<mapping-types,field datatypes>> that are dynamically
  24. detected. All other datatypes must be mapped explicitly.
  25. Besides the options listed below, dynamic field mapping rules can be further
  26. customised with <<dynamic-templates,`dynamic_templates`>>.
  27. [[date-detection]]
  28. ==== Date detection
  29. If `date_detection` is enabled (default), then new string fields are checked
  30. to see whether their contents match any of the date patterns specified in
  31. `dynamic_date_formats`. If a match is found, a new <<date,`date`>> field is
  32. added with the corresponding format.
  33. The default value for `dynamic_date_formats` is:
  34. &#91; <<strict-date-time,`"strict_date_optional_time"`>>,`"yyyy/MM/dd HH:mm:ss Z||yyyy/MM/dd Z"`]
  35. For example:
  36. [source,console]
  37. --------------------------------------------------
  38. PUT my_index/_doc/1
  39. {
  40. "create_date": "2015/09/02"
  41. }
  42. GET my_index/_mapping <1>
  43. --------------------------------------------------
  44. <1> The `create_date` field has been added as a <<date,`date`>>
  45. field with the <<mapping-date-format,`format`>>: +
  46. `"yyyy/MM/dd HH:mm:ss Z||yyyy/MM/dd Z"`.
  47. ===== Disabling date detection
  48. Dynamic date detection can be disabled by setting `date_detection` to `false`:
  49. [source,console]
  50. --------------------------------------------------
  51. PUT my_index
  52. {
  53. "mappings": {
  54. "date_detection": false
  55. }
  56. }
  57. PUT my_index/_doc/1 <1>
  58. {
  59. "create": "2015/09/02"
  60. }
  61. --------------------------------------------------
  62. <1> The `create_date` field has been added as a <<text,`text`>> field.
  63. ===== Customising detected date formats
  64. Alternatively, the `dynamic_date_formats` can be customised to support your
  65. own <<mapping-date-format,date formats>>:
  66. [source,console]
  67. --------------------------------------------------
  68. PUT my_index
  69. {
  70. "mappings": {
  71. "dynamic_date_formats": ["MM/dd/yyyy"]
  72. }
  73. }
  74. PUT my_index/_doc/1
  75. {
  76. "create_date": "09/25/2015"
  77. }
  78. --------------------------------------------------
  79. [[numeric-detection]]
  80. ==== Numeric detection
  81. While JSON has support for native floating point and integer datatypes, some
  82. applications or languages may sometimes render numbers as strings. Usually the
  83. correct solution is to map these fields explicitly, but numeric detection
  84. (which is disabled by default) can be enabled to do this automatically:
  85. [source,console]
  86. --------------------------------------------------
  87. PUT my_index
  88. {
  89. "mappings": {
  90. "numeric_detection": true
  91. }
  92. }
  93. PUT my_index/_doc/1
  94. {
  95. "my_float": "1.0", <1>
  96. "my_integer": "1" <2>
  97. }
  98. --------------------------------------------------
  99. <1> The `my_float` field is added as a <<number,`float`>> field.
  100. <2> The `my_integer` field is added as a <<number,`long`>> field.