dynamic.asciidoc 2.8 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889
  1. [[dynamic]]
  2. === `dynamic`
  3. By default, fields can be added _dynamically_ to a document, or to
  4. <<object,inner objects>> within a document, just by indexing a document
  5. containing the new field. For instance:
  6. [source,js]
  7. --------------------------------------------------
  8. PUT my_index/_doc/1 <1>
  9. {
  10. "username": "johnsmith",
  11. "name": {
  12. "first": "John",
  13. "last": "Smith"
  14. }
  15. }
  16. GET my_index/_mapping <2>
  17. PUT my_index/_doc/2 <3>
  18. {
  19. "username": "marywhite",
  20. "email": "mary@white.com",
  21. "name": {
  22. "first": "Mary",
  23. "middle": "Alice",
  24. "last": "White"
  25. }
  26. }
  27. GET my_index/_mapping <4>
  28. --------------------------------------------------
  29. // CONSOLE
  30. <1> This document introduces the string field `username`, the object field
  31. `name`, and two string fields under the `name` object which can be
  32. referred to as `name.first` and `name.last`.
  33. <2> Check the mapping to verify the above.
  34. <3> This document adds two string fields: `email` and `name.middle`.
  35. <4> Check the mapping to verify the changes.
  36. The details of how new fields are detected and added to the mapping is explained in <<dynamic-mapping>>.
  37. The `dynamic` setting controls whether new fields can be added dynamically or
  38. not. It accepts three settings:
  39. [horizontal]
  40. `true`:: Newly detected fields are added to the mapping. (default)
  41. `false`:: Newly detected fields are ignored. These fields will not be indexed so will not be searchable
  42. but will still appear in the `_source` field of returned hits. These fields will not be added
  43. to the mapping, new fields must be added explicitly.
  44. `strict`:: If new fields are detected, an exception is thrown and the document is rejected. New fields
  45. must be explicitly added to the mapping.
  46. The `dynamic` setting may be set at the mapping type level, and on each
  47. <<object,inner object>>. Inner objects inherit the setting from their parent
  48. object or from the mapping type. For instance:
  49. [source,js]
  50. --------------------------------------------------
  51. PUT my_index
  52. {
  53. "mappings": {
  54. "_doc": {
  55. "dynamic": false, <1>
  56. "properties": {
  57. "user": { <2>
  58. "properties": {
  59. "name": {
  60. "type": "text"
  61. },
  62. "social_networks": { <3>
  63. "dynamic": true,
  64. "properties": {}
  65. }
  66. }
  67. }
  68. }
  69. }
  70. }
  71. }
  72. --------------------------------------------------
  73. // CONSOLE
  74. <1> Dynamic mapping is disabled at the type level, so no new top-level fields will be added dynamically.
  75. <2> The `user` object inherits the type-level setting.
  76. <3> The `user.social_networks` object enables dynamic mapping, so new fields may be added to this inner object.
  77. TIP: The `dynamic` setting can be updated on existing fields
  78. using the <<indices-put-mapping,PUT mapping API>>.