update documentation

docs/reference/mapping/fields/synthetic-source.asciidoc

@@ -207,13 +207,21 @@ Values of `geo_point` fields are represented in synthetic `_source` with reduced
 <<geo-point-synthetic-source, examples>>.
 
 [[synthetic-source-keep]]
-====== Keeping the origical source
+====== Minimizing source modifications
 
-It is possible to record the original source of an object or field, at extra storage cost, using param
-`synthetic_source_keep`. The default value is `none`; setting it to `arrays` leads to storing the original source for
-arrays of the corresponding field or object, while setting it to `all` records both singleton instances and arrays of
-the object or value it is applied to. When applied to objects, the source of all sub-objects and sub-fields gets
-captured. For instance:
+It is possible to avoid the synthetic source modifications for a particular object or field, at extra storage cost.
+This is controlled through param `synthetic_source_keep` with the following values:
+
+ - `none`: synthetic source diverges from the original source as described above (default).
+ - `arrays`: arrays of the corresponding field or object preserve the original element ordering and duplicate elements.
+The synthetic source fragment for such arrays is not guaranteed to match the original source exactly, e.g. array
+`[1, 2, [5], [[4, [3]]], 5]` may appear as-is or in an equivalent format like `[1, 2, 5, 4, 3, 5]`. The exact format
+may change in the future, in an effort to reduce the storage overhead of this option.
+- `all`: the source for both singleton instances and arrays of the corresponding field or object gets recorded. When
+applied to objects, the source of all sub-objects and sub-fields gets captured. Furthermore, the original source of
+arrays gets captured and appears in synthetic source with no modifications.
+
+For instance:
 
 [source,console,id=create-index-with-synthetic-source-keep]
 ----

server/src/main/java/org/elasticsearch/index/mapper/DocumentParser.java

@@ -802,8 +802,8 @@ private static void parseNonDynamicArray(
         // Check if we need to record the array source. This only applies to synthetic source.
         if (context.canAddIgnoredField()) {
             boolean objectRequiresStoringSource = mapper instanceof ObjectMapper objectMapper
-                && ((getSourceKeepMode(context, objectMapper.sourceKeepMode()) == Mapper.SourceKeepMode.ALL
-                    || getSourceKeepMode(context, objectMapper.sourceKeepMode()) == Mapper.SourceKeepMode.ARRAYS
+                && (getSourceKeepMode(context, objectMapper.sourceKeepMode()) == Mapper.SourceKeepMode.ALL
+                    || (getSourceKeepMode(context, objectMapper.sourceKeepMode()) == Mapper.SourceKeepMode.ARRAYS
                         && objectMapper instanceof NestedObjectMapper == false));
             boolean fieldWithFallbackSyntheticSource = mapper instanceof FieldMapper fieldMapper
                 && fieldMapper.syntheticSourceMode() == FieldMapper.SyntheticSourceMode.FALLBACK;
@@ -1116,15 +1116,8 @@ protected SyntheticSourceSupport syntheticSourceSupport() {
 
     private static class NoOpObjectMapper extends ObjectMapper {
         NoOpObjectMapper(String name, String fullPath) {
-            super(
-                name,
-                fullPath,
-                Explicit.IMPLICIT_TRUE,
-                Optional.empty(),
-                Explicit.IMPLICIT_FALSE,
-                Dynamic.RUNTIME,
-                Collections.emptyMap()
-            );
+            super(name, fullPath, Explicit.IMPLICIT_TRUE, Optional.empty(), Optional.empty(), Dynamic.RUNTIME, Collections.emptyMap());
+
         }
 
         @Override