mapping.asciidoc 3.6 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495
  1. [[mapping]]
  2. = Mapping
  3. [partintro]
  4. --
  5. Mapping is the process of defining how a document, and the fields it contains,
  6. are stored and indexed.
  7. Each document is a collection of fields, which each have their own
  8. <<mapping-types,data type>>. When mapping your data, you create a mapping
  9. definition, which contains a list of fields that are pertinent to the document.
  10. A mapping definition also includes <<mapping-fields,metadata fields>>, like the
  11. `_source` field, which customize how a document's associated metadata is
  12. handled.
  13. Use _dynamic mapping_ and _explicit mapping_ to define your data. Each method
  14. provides different benefits based on where you are in your data journey. For
  15. example, explicitly map fields where you don't want to use the defaults, or to
  16. gain greater control over which fields are created. You can then allow {es} to
  17. add other fields dynamically.
  18. NOTE: Before 7.0.0, the mapping definition included a type name.
  19. {es} 7.0.0 and later no longer accept a _default_ mapping. See <<removal-of-types>>.
  20. .Experiment with mapping options
  21. ****
  22. <<runtime-search-request,Define runtime fields in a search request>> to
  23. experiment with different mapping options, and also fix mistakes in your index
  24. mapping values by overriding values in the mapping during the search request.
  25. ****
  26. [discrete]
  27. [[mapping-dynamic]]
  28. == Dynamic mapping
  29. <<dynamic-field-mapping,Dynamic mapping>> allows you to experiment with
  30. and explore data when you’re just getting started. {es} adds new fields
  31. automatically, just by indexing a document. You can add fields to the top-level
  32. mapping, and to inner <<object,`object`>> and <<nested,`nested`>> fields.
  33. Use <<dynamic-templates,dynamic templates>> to define custom mappings that are
  34. applied to dynamically added fields based on the matching condition. You can
  35. <<match-mapping-runtime-fields,map runtime fields in a dynamic template>>
  36. so that new fields are automatically added to the index mapping as runtime
  37. fields.
  38. [discrete]
  39. [[mapping-explicit]]
  40. == Explicit mapping
  41. <<explicit-mapping,Explicit mapping>> allows you to precisely choose how to
  42. define the mapping definition, such as:
  43. * Which string fields should be treated as full text fields.
  44. * Which fields contain numbers, dates, or geolocations.
  45. * The <<mapping-date-format,format>> of date values.
  46. * Custom rules to control the mapping for
  47. <<dynamic-mapping,dynamically added fields>>.
  48. <<runtime-mapping-fields,Explicitly mapping runtime fields>> allows you to make
  49. schema changes without reindexing. You can use runtime fields in conjunction
  50. with indexed fields to balance resource usage and performance. Your index will
  51. be smaller, but with slower search performance.
  52. [discrete]
  53. [[mapping-limit-settings]]
  54. == Settings to prevent mapping explosion
  55. Defining too many fields in an index can lead to a mapping explosion, which can
  56. cause out of memory errors and difficult situations to recover from.
  57. Consider a situation where every new document inserted
  58. introduces new fields, such as with <<dynamic-mapping,dynamic mapping>>.
  59. Each new field is added to the index mapping, which can become a
  60. problem as the mapping grows.
  61. Use the <<mapping-settings-limit,mapping limit settings>> to limit the number
  62. of field mappings (created manually or dynamically) and prevent documents from
  63. causing a mapping explosion.
  64. --
  65. include::mapping/dynamic-mapping.asciidoc[]
  66. include::mapping/explicit-mapping.asciidoc[]
  67. include::mapping/runtime.asciidoc[]
  68. include::mapping/types.asciidoc[]
  69. include::mapping/fields.asciidoc[]
  70. include::mapping/params.asciidoc[]
  71. include::mapping/mapping-settings-limit.asciidoc[]
  72. include::mapping/removal_of_types.asciidoc[]