Update supported field level documents for derived source (#10994)

* Update supported field level documents for derived source

Signed-off-by: Tanik Pansuriya <[email protected]>

* Doc review

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

* Small rewording

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

* Apply suggestions from code review

Signed-off-by: Nathan Bower <[email protected]>

* Apply suggestions from code review

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

---------

Signed-off-by: Tanik Pansuriya <[email protected]>
Signed-off-by: Fanit Kolchina <[email protected]>
Signed-off-by: Nathan Bower <[email protected]>
Signed-off-by: kolchfa-aws <[email protected]>
Co-authored-by: Fanit Kolchina <[email protected]>
Co-authored-by: Nathan Bower <[email protected]>
Co-authored-by: kolchfa-aws <[email protected]>

Author: 3 people

_mappings/supported-field-types/boolean.md

@@ -158,3 +158,83 @@ The script returns the value of `a` as `true`, `key` returns the value of `a` as
   }
 }
 ```
+
+## Derived source
+
+When an index uses [derived source]({{site.url}}{{site.baseurl}}/field-types/metadata-fields/source/#derived-source), OpenSearch may sort values in a multi-value `boolean` field during source reconstruction. The following example shows how OpenSearch processes mixed `boolean` inputs.
+
+Create an index that enables derived source and configures a `boolean` field named `a`:
+
+```json
+PUT /sample-index1
+{
+  "settings": {
+    "index": {
+      "derived_source": {
+        "enabled": true
+      }
+    }
+  },
+  "mappings": {
+    "properties": {
+      "a":  {"type": "boolean"}
+    }
+  }
+}
+```
+
+Index a document into the index:
+
+```json
+PUT sample-index1/_doc/1
+{
+  "a": [false, "true", "false", true, ""]
+}
+```
+
+After OpenSearch reconstructs `_source`, the derived `_source` is as follows:
+
+```json
+{
+  "a": [false, false, false, true, true]
+}
+```
+
+If the field mapping defines a [`null_value`]({{site.url}}{{site.baseurl}}/field-types/mapping-parameters/null-value/), any ingested null values are replaced with that value during reconstruction. The following example demonstrates how `null_value` affects derived source output.
+
+Create an index that enables derived source and configures a `null_value` for the `boolean` field `a`:
+
+```json
+PUT sample-index2
+{
+  "settings": {
+    "index": {
+      "derived_source": {
+        "enabled": true
+      }
+    }
+  },
+  "mappings": {
+    "properties": {
+      "a":  {"type": "boolean", "null_value": true}
+    }
+  }
+}
+```
+
+Index a document into the index:
+
+```json
+PUT sample-index2/_doc/1
+{
+  "a": [null, true, "false"]
+}
+```
+
+After OpenSearch reconstructs `_source`, the derived `_source` is as follows:
+
+```json
+{
+  "a": [false, true, true]
+}
+```

_mappings/supported-field-types/date-nanos.md

@@ -290,4 +290,48 @@ The response contains only the nanosecond parts of the fields:
     ]
   }
 }
-```
+```
+
+## Derived source
+
+When an index uses [derived source]({{site.url}}{{site.baseurl}}/field-types/metadata-fields/source/#derived-source), OpenSearch may sort values in multi-value date fields during source reconstruction. When configuring multiple date formats separated by `||` under the `format` mapping parameter, derived source returns results in the first provided format.
+
+Create an index that enables derived source and configures a `date_nanos` field with multiple formats:
+
+```json
+PUT sample-index1
+{
+  "settings": {
+    "index": {
+      "derived_source": {
+        "enabled": true
+      }
+    }
+  },
+  "mappings": {
+    "properties": {
+      "date_nanos": {
+        "type": "date_nanos",
+        "format": "strict_date_optional_time_nanos||strict_date_optional_time||epoch_millis"
+      }
+    }
+  }
+}
+```
+
+Index a document with mixed date formats into the index:
+
+```json
+PUT sample-index1/_doc/1
+{
+  "date_nanos": [1758504860, "2025-09-22T00:34", "2025-09-22T01:34:20Z"]
+}
+```
+
+After OpenSearch reconstructs `_source`, the derived `_source` is as follows:
+
+```json
+{
+  "date_nanos": ["2025-09-22T00:34:00.000000000Z", "2025-09-22T01:34:00.000000000Z", "2025-09-22T01:34:00.000000000Z"]
+}
+```

_mappings/supported-field-types/date.md

@@ -361,3 +361,47 @@ The response contains both documents:
   }
 }
 ```
+
+## Derived source
+
+When an index uses [derived source]({{site.url}}{{site.baseurl}}/field-types/metadata-fields/source/#derived-source), OpenSearch may sort values in multi-value date fields during source reconstruction. When configuring multiple date formats separated by `||` under the `format` mapping parameter, derived source returns results in the first provided format.
+
+Create an index that enables derived source and configures a `date` field with multiple formats:
+
+```json
+PUT sample-index1
+{
+  "settings": {
+    "index": {
+      "derived_source": {
+        "enabled": true
+      }
+    }
+  },
+  "mappings": {
+    "properties": {
+      "date": {
+        "type": "date",
+        "format": "strict_date_time_no_millis||strict_date_optional_time||epoch_millis"
+      }
+    }
+  }
+}
+```
+
+Index a document with mixed date formats into the index:
+
+```json
+PUT sample-index1/_doc/1
+{
+  "date": [1758504860, "2025-09-22T00:34", "2025-09-22T01:34:20Z"]
+}
+```
+
+After OpenSearch reconstructs `_source`, all dates are in the `strict_date_time_no_millis` format:
+
+```json
+{
+  "date": ["2025-09-22T00:34:00.000Z", "2025-09-22T01:34:00.000Z", "2025-09-22T01:34:00.000Z"]
+}
+```

_mappings/supported-field-types/geo-point.md

@@ -113,4 +113,93 @@ Parameter | Description
 :--- | :--- 
 `ignore_malformed` | A Boolean value that specifies to ignore malformed values and not to throw an exception. Valid values for latitude are [-90, 90]. Valid values for longitude are [-180, 180]. Default is `false`.
 `ignore_z_value` | Specific to points with three coordinates. If `ignore_z_value` is `true`, the third coordinate is not indexed but is still stored in the _source field. If `ignore_z_value` is `false`, an exception is thrown.
-[`null_value`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/index#null-value) | A  value to be used in place of `null`. Must be of the same type as the field. If this parameter is not specified, the field is treated as missing when its value is `null`. Default is `null`.
+[`null_value`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/index#null-value) | A  value to be used in place of `null`. Must be of the same type as the field. If this parameter is not specified, the field is treated as missing when its value is `null`. Default is `null`.
+
+## Derived source
+
+When an index uses [derived source]({{site.url}}{{site.baseurl}}/field-types/metadata-fields/source/#derived-source), OpenSearch normalizes geopoint values to a consistent latitude/longitude object format during source reconstruction, regardless of the original input format. OpenSearch may also sort multi-value geopoint fields, and precision loss can occur during the conversion process.
+
+Create an index that enables derived source and configures a `geo_point` field:
+
+```json
+PUT sample-index1
+{
+  "settings": {
+    "index": {
+      "derived_source": {
+        "enabled": true
+      }
+    }
+  },
+  "mappings": {
+    "properties": {
+      "geo_point": {
+        "type": "geo_point"
+      }
+    }
+  }
+}
+```
+
+Index a document with a geohash format into the index:
+
+```json
+PUT sample-index1/_doc/1
+{
+  "geo_point": "txhxegj0uyp3"
+}
+```
+
+After OpenSearch reconstructs `_source`, the derived `_source` is as follows:
+
+```json
+{
+  "geo_point": {"lat": 40.71, "lon": 74.00}
+}
+```
+
+Index another document with a Well-Known Text format into the index:
+
+```json
+PUT sample-index1/_doc/2
+{
+  "geo_point": "POINT (74.00 40.71)"
+}
+```
+
+After OpenSearch reconstructs `_source`, the derived `_source` is as follows:
+
+```json
+{
+  "geo_point": {"lat": 40.71, "lon": 74.00}
+}
+```
+
+Index a document with multiple geopoints into the index:
+
+```json
+PUT sample-index1/_doc/3
+{
+  "geo_point": [
+    {"lat": 75.98, "lon": 40.34},
+    {"lat": -90, "lon": -80}
+  ]
+}
+```
+
+After OpenSearch reconstructs `_source`, the derived `_source` shows sorted values with potential precision changes:
+
+```json
+{
+  "geo_point": [
+    {
+      "lat": -90.0,
+      "lon": -80.00000000931323
+    },
+    {
+      "lat": 75.97999997902662,
+      "lon": 40.339999962598085
+    }
+  ]
+}
+```

_mappings/supported-field-types/ip.md

@@ -120,4 +120,45 @@ Parameter | Description
 [`null_value`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/index#null-value) | A  value to be used in place of `null`. Must be of the same type as the field. If this parameter is not specified, the field is treated as missing when its value is `null`. Default is `null`.
 `store` | A Boolean value that specifies whether the field value should be stored and can be retrieved separately from the _source field. Default is `false`. 
 
+## Derived source
 
+When an index uses [derived source]({{site.url}}{{site.baseurl}}/field-types/metadata-fields/source/#derived-source), OpenSearch may sort IP address values and remove duplicates in multi-value IP fields during source reconstruction.
+
+Create an index that enables derived source and configures an `ip` field:
+
+```json
+PUT sample-index1
+{
+  "settings": {
+    "index": {
+      "derived_source": {
+        "enabled": true
+      }
+    }
+  },
+  "mappings": {
+    "properties": {
+      "ip": {
+        "type": "ip"
+      }
+    }
+  }
+}
+```
+
+Index a document with multiple IP addresses, including duplicates, into the index:
+
+```json
+PUT sample-index1/_doc/1
+{
+  "ip": ["10.16.0.1", "192.168.0.1", "10.16.0.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]
+}
+```
+
+After OpenSearch reconstructs `_source`, the derived `_source` removes duplicates and sorts the values:
+
+```json
+{
+  "ip": ["10.16.0.1", "192.168.0.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]
+}
+```