Improve guidance on removing default mappings. (#54915)

In 7.x, an index template will fail to apply if it contains a `_default_`
mapping. Several users have expressed confusion over the fact that loading the
template doesn't show any default mappings. This docs change clarifies that in
order to see all mappings in the template, you must pass `include_type_name`.
This commit is contained in:
Julie Tibshirani 2020-04-07 15:18:13 -07:00 committed by GitHub
parent de381271f1
commit 475b210eec
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 21 additions and 7 deletions

View File

@ -31,6 +31,20 @@ of `_id`.
The `_default_` mapping has been deprecated in 6.0 and is now no longer allowed
in 7.0. Trying to configure a `_default_` mapping on 7.x indices will result in
an error.
If an index template contains a `_default_` mapping, it will fail to create new
indices. To resolve this issue, the `_default_` mapping should be removed from
the template. Note that in 7.x, the <<indices-get-template, get template API>>
does not show the `_default_` mapping by default, even when it is defined in
the mapping. To see all mappings in the template, the `include_type_name`
parameter must be supplied:
```
GET /_template/my_template?include_type_name
```
For more details on the `include_type_name` parameter and other types-related
API changes, please see <<removal-of-types>>.
//end::notable-breaking-changes[]
[float]

View File

@ -130,6 +130,9 @@ public class MapperService extends AbstractIndexComponent implements Closeable {
private static final ObjectHashSet<String> META_FIELDS = ObjectHashSet.from(SORTED_META_FIELDS);
private static final DeprecationLogger deprecationLogger = new DeprecationLogger(LogManager.getLogger(MapperService.class));
static final String DEFAULT_MAPPING_ERROR_MESSAGE = "[_default_] mappings are not allowed on new indices and should no " +
"longer be used. See [https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking-changes-7.0.html" +
"#default-mapping-not-allowed] for more information.";
private final IndexAnalyzers indexAnalyzers;
@ -449,11 +452,9 @@ public class MapperService extends AbstractIndexComponent implements Closeable {
if (defaultMapper != null) {
if (indexSettings.getIndexVersionCreated().onOrAfter(Version.V_7_0_0)) {
throw new IllegalArgumentException("The [default] mapping cannot be updated on index [" + index().getName() +
"]: defaults mappings are not useful anymore now that indices can have at most one type.");
throw new IllegalArgumentException(DEFAULT_MAPPING_ERROR_MESSAGE);
} else if (reason == MergeReason.MAPPING_UPDATE) { // only log in case of explicit mapping updates
deprecationLogger.deprecated("[_default_] mapping is deprecated since it is not useful anymore now that indexes " +
"cannot have more than one type");
deprecationLogger.deprecated(DEFAULT_MAPPING_ERROR_MESSAGE);
}
assert defaultMapper.type().equals(DEFAULT_MAPPING);
results.put(DEFAULT_MAPPING, defaultMapper);

View File

@ -86,7 +86,7 @@ public class LegacyMapperServiceTests extends ESSingleNodeTestCase {
}
final MapperService mapperService = createIndex("test", settings).mapperService();
mapperService.merge("_default_", new CompressedXContent(mapping), MapperService.MergeReason.MAPPING_UPDATE);
assertWarnings("[_default_] mapping is deprecated since it is not useful anymore now that indexes cannot have more than one type");
assertWarnings(MapperService.DEFAULT_MAPPING_ERROR_MESSAGE);
}
}

View File

@ -313,8 +313,7 @@ public class MapperServiceTests extends ESSingleNodeTestCase {
MapperService mapperService = createIndex("test").mapperService();
IllegalArgumentException e = expectThrows(IllegalArgumentException.class,
() -> mapperService.merge("_default_", new CompressedXContent(mapping), MergeReason.MAPPING_UPDATE));
assertEquals("The [default] mapping cannot be updated on index [test]: defaults mappings are not useful anymore now"
+ " that indices can have at most one type.", e.getMessage());
assertEquals(MapperService.DEFAULT_MAPPING_ERROR_MESSAGE, e.getMessage());
}
public void testFieldNameLengthLimit() throws Throwable {