From 9da8822aedcc01b4f44551947136b0f38425e2c5 Mon Sep 17 00:00:00 2001
From: Clinton Gormley <clint@traveljury.com>
Date: Thu, 6 Aug 2015 20:09:42 +0200
Subject: [PATCH] Docs: Made multi-fields more prominent

---
 docs/reference/mapping.asciidoc       | 11 +++++++++++
 docs/reference/mapping/types.asciidoc | 14 ++++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc
index e7d15aa42b7..407f43625fa 100644
--- a/docs/reference/mapping.asciidoc
+++ b/docs/reference/mapping.asciidoc
@@ -53,6 +53,17 @@ Each field has a data `type` which can be:
 * or a specialised type like <<geo-point,`geo_point`>>,
   <<geo-shape,`geo_shape`>>, or <<search-suggesters-completion,`completion`>>.
 
+It is often useful to index the same field in different ways for different
+purposes. For instance, a `string` field could be <<mapping-index,indexed>> as
+an `analyzed` field for full-text search, and as a `not_analyzed` field for
+sorting or aggregations.  Alternatively, you could index a string field with
+the <<analysis-standard-analyzer,`standard` analyzer>>, the
+<<english-analyzer,`english`>> analyzer, and the
+<<french-analyzer,`french` analyzer>>.
+
+This is the purpose of _multi-fields_.  Most datatypes support multi-fields
+via the <<multi-fields>> parameter.
+
 [float]
 == Dynamic mapping
 
diff --git a/docs/reference/mapping/types.asciidoc b/docs/reference/mapping/types.asciidoc
index f7c93b04718..abefda42085 100644
--- a/docs/reference/mapping/types.asciidoc
+++ b/docs/reference/mapping/types.asciidoc
@@ -40,6 +40,20 @@ Attachment datatype::
     which supports indexing ``attachments'' like Microsoft Office formats, Open
     Document formats, ePub, HTML, etc. into an `attachment` datatype.
 
+[float]
+=== Multi-fields
+
+It is often useful to index the same field in different ways for different
+purposes. For instance, a `string` field could be <<mapping-index,indexed>> as
+an `analyzed` field for full-text search, and as a `not_analyzed` field for
+sorting or aggregations.  Alternatively, you could index a string field with
+the <<analysis-standard-analyzer,`standard` analyzer>>, the
+<<english-analyzer,`english`>> analyzer, and the
+<<french-analyzer,`french` analyzer>>.
+
+This is the purpose of _multi-fields_.  Most datatypes support multi-fields
+via the <<multi-fields>> parameter.
+
 include::types/array.asciidoc[]
 
 include::types/binary.asciidoc[]