Deprecate allowing `fields` in scenarios where its ignored (#106031)

closes: https://github.com/elastic/elasticsearch/issues/106026

docs/changelog/106031.yaml

@@ -0,0 +1,13 @@
+pr: 106031
+summary: Deprecate allowing `fields` in scenarios where it is ignored
+area: Mapping
+type: deprecation
+issues: []
+deprecation:
+  title: Deprecate allowing `fields` in scenarios where it is ignored
+  area: Mapping
+  details: The following mapped types have always ignored `fields` when using multi-fields.
+    This deprecation makes this clearer and we will completely disallow `fields` for
+    these mapped types in the future.
+  impact: "In the future, `join`, `aggregate_metric_double`, and `constant_keyword`,\
+    \ will all disallow supplying `fields` as a parameter in the mapping."

modules/parent-join/src/main/java/org/elasticsearch/join/mapper/ParentJoinFieldMapper.java

@@ -12,6 +12,8 @@ import org.apache.lucene.document.Field;
 import org.apache.lucene.document.SortedDocValuesField;
 import org.apache.lucene.document.StringField;
 import org.apache.lucene.util.BytesRef;
+import org.elasticsearch.common.logging.DeprecationCategory;
+import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.common.lucene.Lucene;
 import org.elasticsearch.index.IndexSettings;
 import org.elasticsearch.index.analysis.NamedAnalyzer;
@@ -52,6 +54,8 @@ import java.util.Set;
  */
 public final class ParentJoinFieldMapper extends FieldMapper {
 
+    private static final DeprecationLogger DEPRECATION_LOGGER = DeprecationLogger.getLogger(ParentJoinFieldMapper.class);
+
     public static final String NAME = "join";
     public static final String CONTENT_TYPE = "join";
 
@@ -112,6 +116,13 @@ public final class ParentJoinFieldMapper extends FieldMapper {
 
         @Override
         public ParentJoinFieldMapper build(MapperBuilderContext context) {
+            if (multiFieldsBuilder.hasMultiFields()) {
+                DEPRECATION_LOGGER.warn(
+                    DeprecationCategory.MAPPINGS,
+                    CONTENT_TYPE + "_multifields",
+                    "Adding multifields to [" + CONTENT_TYPE + "] mappers has no effect and will be forbidden in future"
+                );
+            }
             checkObjectOrNested(context, name());
             final Map<String, ParentIdFieldMapper> parentIdFields = new HashMap<>();
             relations.get()

modules/parent-join/src/yamlRestTest/resources/rest-api-spec/test/20_parent_join.yml

@@ -144,3 +144,20 @@ teardown:
             parent_id:
               type: child
               id: "1"
+
+---
+"deprecated use of multi-fields":
+  - skip:
+      version: " - 8.13.99"
+      reason: "deprecation added in 8.14"
+      features: warnings
+
+  - do:
+      warnings:
+        - "Adding multifields to [join] mappers has no effect and will be forbidden in future"
+      indices.create:
+        index: join-multi-field
+        body:
+          mappings:
+            properties:
+              join_field: { "type": "join", "relations": { "parent": "child", "child": "grand_child" }, "fields": {"keyword": {"type": "keyword"}} }

x-pack/plugin/mapper-aggregate-metric/src/main/java/org/elasticsearch/xpack/aggregatemetric/mapper/AggregateDoubleMetricFieldMapper.java

@@ -15,6 +15,8 @@ import org.apache.lucene.search.Query;
 import org.apache.lucene.search.SortField;
 import org.apache.lucene.search.SortedNumericSortField;
 import org.apache.lucene.util.NumericUtils;
+import org.elasticsearch.common.logging.DeprecationCategory;
+import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.common.time.DateMathParser;
 import org.elasticsearch.common.util.BigArrays;
 import org.elasticsearch.index.IndexMode;
@@ -74,6 +76,8 @@ import static org.elasticsearch.common.xcontent.XContentParserUtils.ensureExpect
 /** A {@link FieldMapper} for a field containing aggregate metrics such as min/max/value_count etc. */
 public class AggregateDoubleMetricFieldMapper extends FieldMapper {
 
+    private static final DeprecationLogger DEPRECATION_LOGGER = DeprecationLogger.getLogger(AggregateDoubleMetricFieldMapper.class);
+
     public static final String CONTENT_TYPE = "aggregate_metric_double";
     public static final String SUBFIELD_SEPARATOR = ".";
 
@@ -187,6 +191,13 @@ public class AggregateDoubleMetricFieldMapper extends FieldMapper {
 
         @Override
         public AggregateDoubleMetricFieldMapper build(MapperBuilderContext context) {
+            if (multiFieldsBuilder.hasMultiFields()) {
+                DEPRECATION_LOGGER.warn(
+                    DeprecationCategory.MAPPINGS,
+                    CONTENT_TYPE + "_multifields",
+                    "Adding multifields to [" + CONTENT_TYPE + "] mappers has no effect and will be forbidden in future"
+                );
+            }
             if (defaultMetric.isConfigured() == false) {
                 // If a single metric is contained, this should be the default
                 if (metrics.getValue().size() == 1) {

x-pack/plugin/mapper-constant-keyword/src/main/java/org/elasticsearch/xpack/constantkeyword/mapper/ConstantKeywordFieldMapper.java

@@ -21,6 +21,8 @@ import org.apache.lucene.util.automaton.CharacterRunAutomaton;
 import org.apache.lucene.util.automaton.LevenshteinAutomata;
 import org.apache.lucene.util.automaton.RegExp;
 import org.elasticsearch.common.geo.ShapeRelation;
+import org.elasticsearch.common.logging.DeprecationCategory;
+import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.common.lucene.BytesRefs;
 import org.elasticsearch.common.regex.Regex;
 import org.elasticsearch.common.time.DateMathParser;
@@ -62,6 +64,8 @@ import java.util.stream.Stream;
  */
 public class ConstantKeywordFieldMapper extends FieldMapper {
 
+    private static final DeprecationLogger DEPRECATION_LOGGER = DeprecationLogger.getLogger(ConstantKeywordFieldMapper.class);
+
     public static final String CONTENT_TYPE = "constant_keyword";
 
     private static ConstantKeywordFieldMapper toType(FieldMapper in) {
@@ -98,6 +102,13 @@ public class ConstantKeywordFieldMapper extends FieldMapper {
 
         @Override
         public ConstantKeywordFieldMapper build(MapperBuilderContext context) {
+            if (multiFieldsBuilder.hasMultiFields()) {
+                DEPRECATION_LOGGER.warn(
+                    DeprecationCategory.MAPPINGS,
+                    CONTENT_TYPE + "_multifields",
+                    "Adding multifields to [" + CONTENT_TYPE + "] mappers has no effect and will be forbidden in future"
+                );
+            }
             return new ConstantKeywordFieldMapper(
                 name(),
                 new ConstantKeywordFieldType(context.buildFullName(name()), value.getValue(), meta.getValue())

x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/aggregate-metrics/10_basic.yml

@@ -350,3 +350,20 @@
   - match: { hits.hits.1.fields.metric.0.max: 1000 }
   - match: { hits.hits.1.fields.metric.0.sum: 5000 }
   - match: { hits.hits.1.fields.metric.0.value_count: 10 }
+---
+"deprecated use of multi-fields":
+  - skip:
+      version: " - 8.13.99"
+      reason: "deprecation added in 8.14"
+      features: warnings
+
+  - do:
+      warnings:
+        - "Adding multifields to [aggregate_metric_double] mappers has no effect and will be forbidden in future"
+      indices.create:
+        index: aggregate_metric_double-multi-field
+        body:
+          mappings:
+            properties:
+              aggregated: { "type": "aggregate_metric_double", "metrics": ["max"], "default_metric": "max", "fields": {"keyword": {"type": "keyword"}} }
+

x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/constant_keyword/10_basic.yml

@@ -450,3 +450,20 @@ Cardinality agg:
                 field: test
 
   - match: { aggregations.card.value: 1 }
+---
+"deprecated use of multi-fields":
+  - skip:
+      version: " - 8.13.99"
+      reason: "deprecation added in 8.14"
+      features: warnings
+
+  - do:
+      warnings:
+        - "Adding multifields to [constant_keyword] mappers has no effect and will be forbidden in future"
+      indices.create:
+        index: constant_keyword-multi-field
+        body:
+          mappings:
+            properties:
+              keyword: { "type": "constant_keyword", "fields": {"keyword": {"type": "keyword"}} }
+