Document that arrays are returned in an undefined order.

Author: jtibshirani

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

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.