Consilify get-field-mapping docs (#22936)

This change also removes the reference to the difference bewteen full name and index name.
They are always the same since 2.x and `name` does not refer anymore to `author.name` automatically.
A simple pattern must be used instead.
Remove redundant code that checks the field name twice.

core/src/main/java/org/elasticsearch/action/admin/indices/mapping/get/TransportGetFieldMappingsIndexAction.java

@@ -50,12 +50,10 @@ import org.elasticsearch.transport.TransportService;
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Collection;
-import java.util.Iterator;
 import java.util.Map;
 import java.util.stream.Collectors;
 
 import static java.util.Collections.singletonMap;
-import static org.elasticsearch.common.util.CollectionUtils.newLinkedList;
 
 /**
  * Transport action used to retrieve the mappings related to fields that belong to a specific index
@@ -174,24 +172,12 @@ public class TransportGetFieldMappingsIndexAction extends TransportSingleShardAc
                     addFieldMapper(fieldMapper.fieldType().name(), fieldMapper, fieldMappings, request.includeDefaults());
                 }
             } else if (Regex.isSimpleMatchPattern(field)) {
-                // go through the field mappers 3 times, to make sure we give preference to the resolve order: full name, index name, name.
+                for (FieldMapper fieldMapper : allFieldMappers) {
-                // also make sure we only store each mapper once.
-                Collection<FieldMapper> remainingFieldMappers = newLinkedList(allFieldMappers);
-                for (Iterator<FieldMapper> it = remainingFieldMappers.iterator(); it.hasNext(); ) {
-                    final FieldMapper fieldMapper = it.next();
                     if (Regex.simpleMatch(field, fieldMapper.fieldType().name())) {
-                        addFieldMapper(fieldMapper.fieldType().name(), fieldMapper, fieldMappings, request.includeDefaults());
+                        addFieldMapper(fieldMapper.fieldType().name(), fieldMapper, fieldMappings,
-                        it.remove();
+                            request.includeDefaults());
                     }
                 }
-                for (Iterator<FieldMapper> it = remainingFieldMappers.iterator(); it.hasNext(); ) {
-                    final FieldMapper fieldMapper = it.next();
-                    if (Regex.simpleMatch(field, fieldMapper.fieldType().name())) {
-                        addFieldMapper(fieldMapper.fieldType().name(), fieldMapper, fieldMappings, request.includeDefaults());
-                        it.remove();
-                    }
-                }
-
             } else {
                 // not a pattern
                 FieldMapper fieldMapper = allFieldMappers.smartNameFieldMapper(field);

core/src/main/java/org/elasticsearch/index/mapper/DocumentFieldMappers.java

@@ -75,8 +75,6 @@ public final class DocumentFieldMappers implements Iterable<FieldMapper> {
         for (FieldMapper fieldMapper : this) {
             if (Regex.simpleMatch(pattern, fieldMapper.fieldType().name())) {
                 fields.add(fieldMapper.fieldType().name());
-            } else if (Regex.simpleMatch(pattern, fieldMapper.fieldType().name())) {
-                fields.add(fieldMapper.fieldType().name());
             }
         }
         return fields;

docs/build.gradle

@@ -113,7 +113,6 @@ buildRestTests.expectedUnconvertedCandidates = [
   'reference/index-modules/translog.asciidoc',
   'reference/indices/analyze.asciidoc',
   'reference/indices/flush.asciidoc',
-  'reference/indices/get-field-mapping.asciidoc',
   'reference/indices/get-settings.asciidoc',
   'reference/indices/put-mapping.asciidoc',
   'reference/indices/recovery.asciidoc',

docs/reference/indices/get-field-mapping.asciidoc

@@ -5,34 +5,53 @@ The get field mapping API allows you to retrieve mapping definitions for one or
 This is useful when you do not need the complete type mapping returned by
 the <<indices-get-mapping>> API.
 
-The following returns the mapping of the field `text` only:
+For example, consider the following mapping:
 
 [source,js]
 --------------------------------------------------
-GET /twitter/_mapping/tweet/field/message
+PUT publications
+{
+    "mappings": {
+        "article": {
+            "properties": {
+                "id": { "type": "text" },
+                "title":  { "type": "text"},
+                "abstract": { "type": "text"},
+                "author": {
+                    "properties": {
+                        "id": { "type": "text" },
+                        "name": { "type": "text" }
+                    }
+                }
+            }
+        }
+    }
+}
+--------------------------------------------------
+// TESTSETUP
+// CONSOLE
+
+The following returns the mapping of the field `title` only:
+
+[source,js]
+--------------------------------------------------
+GET publications/_mapping/article/field/title
 --------------------------------------------------
 // CONSOLE
-// TEST[setup:twitter]
 
-For which the response is (assuming `text` is a default string field):
+For which the response is:
 
 [source,js]
 --------------------------------------------------
 {
-   "twitter": {
+   "publications": {
       "mappings": {
-         "tweet": {
+         "article": {
-            "message": {
+            "title": {
-               "full_name": "message",
+               "full_name": "title",
                "mapping": {
-                  "message": {
+                  "title": {
-                     "type": "text",
+                     "type": "text"
-                     "fields": {
-                        "keyword": {
-                           "type": "keyword",
-                           "ignore_above": 256
-                        }
-                     }
                   }
                }
             }
@@ -43,7 +62,6 @@ For which the response is (assuming `text` is a default string field):
 --------------------------------------------------
 // TESTRESPONSE
 
-
 [float]
 === Multiple Indices, Types and Fields
 
@@ -69,46 +87,15 @@ GET /_all/_mapping/tw*/field/*.id
 [float]
 === Specifying fields
 
-The get mapping api allows you to specify one or more fields separated with by a comma.
+The get mapping api allows you to specify a comma-separated list of fields.
-You can also use wildcards. The field names can be any of the following:
 
-[horizontal]
+For instance to select the `id` of the `author` field, you must use its full name `author.id`.
-Full names:: the full path, including any parent object name the field is
-   part of (ex. `user.id`).
-Field names:: the name of the field without the path to it (ex. `id` for `{ "user" : { "id" : 1 } }`).
-
-The above options are specified in the order the `field` parameter is resolved.
-The first field found which matches is returned. This is especially important
-if index names or field names are used as those can be ambiguous.
-
-For example, consider the following mapping:
 
 [source,js]
 --------------------------------------------------
- {
+GET publications/_mapping/article/field/author.id,abstract,name
-     "article": {
-         "properties": {
-             "id": { "type": "text" },
-             "title":  { "type": "text"},
-             "abstract": { "type": "text"},
-             "author": {
-                 "properties": {
-                     "id": { "type": "text" },
-                     "name": { "type": "text" }
-                 }
-             }
-         }
-     }
- }
---------------------------------------------------
-
-To select the `id` of the `author` field, you can use its full name `author.id`. `name` will return
-the field `author.name`:
-
-[source,js]
---------------------------------------------------
-curl -XGET "http://localhost:9200/publications/_mapping/article/field/author.id,abstract,name"
 --------------------------------------------------
+// CONSOLE
 
 returns:
 
@@ -116,33 +103,77 @@ returns:
 --------------------------------------------------
 {
    "publications": {
-      "article": {
+      "mappings": {
-         "abstract": {
+         "article": {
-            "full_name": "abstract",
+            "author.id": {
-            "mapping": {
+               "full_name": "author.id",
-               "abstract": { "type": "text" }
+               "mapping": {
-            }
+                  "id": {
-         },
+                     "type": "text"
-         "author.id": {
+                  }
-            "full_name": "author.id",
+               }
-            "mapping": {
+            },
-               "id": { "type": "text" }
+            "abstract": {
-            }
+               "full_name": "abstract",
-         },
+               "mapping": {
-         "name": {
+                  "abstract": {
-            "full_name": "author.name",
+                     "type": "text"
-            "mapping": {
+                  }
-               "name": { "type": "text" }
+               }
             }
          }
       }
    }
 }
 --------------------------------------------------
+// TESTRESPONSE
 
-Note how the response always use the same fields specified in the request as keys.
+The get field mapping API also supports wildcard notation.
-The `full_name` in every entry contains the full name of the field whose mapping were returned.
+
-This is useful when the request can refer to to multiple fields.
+[source,js]
+--------------------------------------------------
+GET publications/_mapping/article/field/a*
+--------------------------------------------------
+// CONSOLE
+
+returns:
+
+[source,js]
+--------------------------------------------------
+{
+   "publications": {
+      "mappings": {
+         "article": {
+            "author.name": {
+               "full_name": "author.name",
+               "mapping": {
+                  "name": {
+                     "type": "text"
+                  }
+               }
+            },
+            "abstract": {
+               "full_name": "abstract",
+               "mapping": {
+                  "abstract": {
+                     "type": "text"
+                  }
+               }
+            },
+            "author.id": {
+               "full_name": "author.id",
+               "mapping": {
+                  "id": {
+                     "type": "text"
+                  }
+               }
+            }
+         }
+      }
+   }
+}
+--------------------------------------------------
+// TESTRESPONSE
 
 [float]
 === Other options