From 840cd116d0b319bde02b19267e8835d8003b18f8 Mon Sep 17 00:00:00 2001
From: Julie Tibshirani <julie.tibshirani@elastic.co>
Date: Mon, 27 Jul 2020 12:08:41 -0700
Subject: [PATCH] Document that arrays are returned in an undefined order.

---
 docs/reference/search/search-fields.asciidoc             | 9 +++++++++
 .../java/org/elasticsearch/index/mapper/FieldMapper.java | 6 ++++--
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/docs/reference/search/search-fields.asciidoc b/docs/reference/search/search-fields.asciidoc
index 102b56a8a8928..b3de7b0e58016 100644
--- a/docs/reference/search/search-fields.asciidoc
+++ b/docs/reference/search/search-fields.asciidoc
@@ -151,6 +151,15 @@ the `_source`. Other mapping options are also respected, including
 <<ignore-above, `ignore_above`>>, <<ignore-malformed, `ignore_malformed`>> and
 <<null-value, `null_value`>>.
 
+NOTE: The `fields` response always returns an array of values for each field,
+even when there is a single value in the `_source`. This is because {es} has
+no dedicated array type, and any field could contain multiple values. The
+`fields` parameter also does not guarantee that array values are returned in
+a specific order. See the mapping documentation on <<array, arrays>> for more
+background.
+
+
+
 [discrete]
 [[docvalue-fields]]
 === Doc value fields
diff --git a/server/src/main/java/org/elasticsearch/index/mapper/FieldMapper.java b/server/src/main/java/org/elasticsearch/index/mapper/FieldMapper.java
index 58bbf9c2b8379..7581833648603 100644
--- a/server/src/main/java/org/elasticsearch/index/mapper/FieldMapper.java
+++ b/server/src/main/java/org/elasticsearch/index/mapper/FieldMapper.java
@@ -284,9 +284,11 @@ public void parse(ParseContext context) throws IOException {
      * In addition to pulling out the values, mappers can parse them into a standard form. This
      * method delegates parsing to {@link #parseSourceValue} for parsing. Most mappers will choose
      * to override {@link #parseSourceValue} -- for example numeric field mappers make sure to
-     * parse the  source value into a number of the right type.
+     * parse the source value into a number of the right type. Some mappers may need more
+     * flexibility and can override this entire method instead.
      *
-     * Some mappers may need more flexibility and can override this entire method instead.
+     * Note that for array values, the order in which values are returned is undefined and should
+     * not be relied on.
      *
      * @param lookup a lookup structure over the document's source.
      * @param format an optional format string used when formatting values, for example a date format.