diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc
index 5c3a7df0aa3..3f89571ae58 100644
--- a/docs/reference/mapping.asciidoc
+++ b/docs/reference/mapping.asciidoc
@@ -80,6 +80,17 @@ causing a mapping explosion:
 `index.mapping.total_fields.limit`::
     The maximum number of fields in an index. Field and object mappings, as well as
     field aliases count towards this limit. The default value is `1000`.
++
+[IMPORTANT]
+====
+The limit is in place to prevent mappings and searches from becoming too
+large. Higher values can lead to performance degradations and memory issues,
+especially in clusters with a high load or few resources.
+
+If you increase this setting, we recommend you also increase the
+<<search-settings,`indices.query.bool.max_clause_count`>> setting, which
+limits the maximum number of <<query-dsl-bool-query,boolean clauses>> in a query.
+====
 
 `index.mapping.depth.limit`::
     The maximum depth for a field, which is measured as the number of inner