Refactor coerce mapping parameter documentation (#11020)

* Refactor coerce maping parameter documentation

Signed-off-by: Fanit Kolchina <[email protected]>

* Clarify intro sentences

Signed-off-by: Fanit Kolchina <[email protected]>

* Update _field-types/mapping-parameters/coerce.md

Signed-off-by: kolchfa-aws <[email protected]>

---------

Signed-off-by: Fanit Kolchina <[email protected]>
Signed-off-by: kolchfa-aws <[email protected]>

Author: kolchfa-aws

_field-types/mapping-parameters/coerce.md

@@ -2,99 +2,120 @@
 layout: default
 title: Coerce
 parent: Mapping parameters
-
 nav_order: 15
 has_children: false
 has_toc: false
 ---
 
 # Coerce
 
-The `coerce` mapping parameter controls how values are converted to the expected field data type during indexing. This parameter lets you verify that your data is formatted and indexed properly, following the expected field types. This improves the accuracy of your search results.
+The `coerce` mapping parameter controls whether OpenSearch attempts to normalize and convert values to match the field's data type during indexing.
 
----
+Data is not always consistent. Depending on how it's produced, a number might be rendered as a true JSON number like 10, but it might also be rendered as a string like "10". Similarly, a number that should be an integer might be rendered as a floating point like 10.0 or even as a string like "10.0".
+
+Coercion attempts to transform these inconsistencies to fit the field's data type:
+
+- **Strings are coerced to numbers**: `"10"` becomes `10`.
+- **Floating-point numbers are coerced to integers by truncating**: `10.0` becomes `10`.
+
+The `coerce` parameter can be updated on existing fields using the Update Mapping API.
+{: .tip}
 
 ## Examples
 
 The following examples demonstrate how to use the `coerce` mapping parameter.
 
-#### Indexing a document with `coerce` enabled
+### Field-level coercion
+
+Create an index with different coercion settings for comparison. Coercion is enabled by default:
 
 ```json
-PUT products
+PUT /data_quality_demo
 {
   "mappings": {
     "properties": {
-      "price": {
+      "price_with_coercion": {
+        "type": "integer"
+      },
+      "price_without_coercion": {
         "type": "integer",
-        "coerce": true
+        "coerce": false
       }
     }
   }
 }
+```
+{% include copy-curl.html %}
+
+Index a document with coercion enabled:
 
-PUT products/_doc/1
+```json
+PUT /data_quality_demo/_doc/1
 {
-  "name": "Product A",
-  "price": "19.99"
+  "price_with_coercion": "10"
 }
 ```
 {% include copy-curl.html %}
 
-In this example, the `price` field is defined as an `integer` type with `coerce` set to `true`. When indexing the document, the string value `19.99` is coerced to the integer `19`.
+To match the integer field type, the string `"10"` is is successfully converted to the integer `10`.
 
-#### Indexing a document with `coerce` disabled
+Attempt to index a document with coercion disabled:
 
 ```json
-PUT orders
-{
-  "mappings": {
-    "properties": {
-      "quantity": {
-        "type": "integer",
-        "coerce": false
-      }
-    }
-  }
-}
-
-PUT orders/_doc/1
+PUT /data_quality_demo/_doc/2
 {
-  "item": "Widget",
-  "quantity": "10"
+  "price_without_coercion": "10"
 }
 ```
 {% include copy-curl.html %}
 
-In this example, the `quantity` field is defined as an `integer` type with `coerce` set to `false`. When indexing the document, the string value `10` is not coerced, and the document is rejected because of the type mismatch. 
+This document is rejected because coercion is disabled and the string `"10"` doesn't match the expected integer type.
 
-#### Setting the index-level coercion setting
+### Index-level coercion setting
+
+You can set a default coercion policy for the entire index as follows:
 
 ```json
-PUT inventory
+PUT /strict_data_index
 {
   "settings": {
     "index.mapping.coerce": false
   },
   "mappings": {
     "properties": {
-      "stock_count": {
+      "flexible_field": {
         "type": "integer",
         "coerce": true
       },
-      "sku": {
-        "type": "keyword"
+      "strict_field": {
+        "type": "integer"
       }
     }
   }
 }
+```
+{% include copy-curl.html %}
+
+Index a document containing a `flexible_field`:
+
+```json
+PUT /strict_data_index/_doc/1
+{
+  "flexible_field": "10"
+}
+```
+{% include copy-curl.html %}
+
+The `flexible_field` overrides the index-level setting and enables coercion, so the string `"10"` is successfully converted to the integer `10`.
 
-PUT inventory/_doc/1
+Index another document containing a `strict_field`:
+
+```json
+PUT /strict_data_index/_doc/2
 {
-  "sku": "ABC123",
-  "stock_count": "50"
+  "strict_field": "10"
 }
 ```
 {% include copy-curl.html %}
 
-In this example, the index-level `index.mapping.coerce` setting is set to `false`, which disables coercion for the index. However, the `stock_count` field overrides this setting and enables coercion for this specific field.
+This document is rejected because the `strict_field` inherits the index-level coercion setting (`false`), and the string `"10"` cannot be stored in an integer field without coercion.