docs

Author: lkts

docs/reference/elasticsearch/mapping-reference/keyword.md

@@ -232,6 +232,42 @@ Will become:
 }
 ```
 
+If `null_value` is configured, `null` values are replaced with the `null_value` in synthetic source:
+
+$$$synthetic-source-keyword-example-null-value$$$
+
+```console
+PUT idx
+{
+  "settings": {
+    "index": {
+      "mapping": {
+        "source": {
+          "mode": "synthetic"
+        }
+      }
+    }
+  },
+  "mappings": {
+    "properties": {
+      "kwd": { "type": "keyword", "null_value": "NA" }
+    }
+  }
+}
+PUT idx/_doc/1
+{
+  "kwd": ["foo", null, "bar"]
+}
+```
+
+Will become:
+
+```console-result
+{
+  "kwd": ["bar", "foo", "NA"]
+}
+```
+
 
 ## Constant keyword field type [constant-keyword-field-type]
 

docs/reference/elasticsearch/mapping-reference/text.md

@@ -104,11 +104,20 @@ Synthetic `_source` is Generally Available only for TSDB indices (indices that h
 ::::
 
 
-`text` fields support [synthetic `_source`](/reference/elasticsearch/mapping-reference/mapping-source-field.md#synthetic-source) if they have a [`keyword`](/reference/elasticsearch/mapping-reference/keyword.md#keyword-synthetic-source) sub-field that supports synthetic `_source` or if the `text` field sets `store` to `true`. Either way, it may not have [`copy_to`](/reference/elasticsearch/mapping-reference/copy-to.md).
+`text` fields may use a [`keyword`](/reference/elasticsearch/mapping-reference/keyword.md#keyword-synthetic-source) sub-field to support [synthetic `_source`](/reference/elasticsearch/mapping-reference/mapping-source-field.md#synthetic-source) without storing values of the text field itself.
+
+::::{note}
+Synthetic source of the `text` field will have the same [modifications](/reference/elasticsearch/mapping-reference/mapping-source-field.md#synthetic-source) as a `keyword` field in this case.
+
+These modifications can impact usage of `text` fields:
+* Reordering text fields can have an effect on [phrase](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) and [span](/reference/query-languages/query-dsl/span-queries.md) queries. See the discussion about [`position_increment_gap`](/reference/elasticsearch/mapping-reference/position-increment-gap.md) for more detail. You can avoid this by making sure the `slop` parameter on the phrase queries is lower than the `position_increment_gap`. This is the default.
+* Handling of `null` values is different. `text` fields ignore `null` values but `keyword` fields support replacing `null`s with a value specified in the `null_value` parameter. This replacement will be represented in synthetic source.
+::::
 
-If using a sub-`keyword` field, then the values are sorted in the same way as a `keyword` field’s values are sorted. By default, that means sorted with duplicates removed. So:
 
-$$$synthetic-source-text-example-default$$$
+If the `text` field sets `store` to `true` then the sub-field is not used and modifications mentioned above do not apply.
+
+$$$synthetic-source-text-example-stored$$$
 
 ```console
 PUT idx
@@ -126,6 +135,7 @@ PUT idx
     "properties": {
       "text": {
         "type": "text",
+        "store": true,
         "fields": {
           "raw": {
             "type": "keyword"
@@ -147,54 +157,6 @@ PUT idx/_doc/1
 
 Will become:
 
-```console-result
-{
-  "text": [
-    "jumped over the lazy dog",
-    "the quick brown fox"
-  ]
-}
-```
-
-::::{note}
-Reordering text fields can have an effect on [phrase](/reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) and [span](/reference/query-languages/query-dsl/span-queries.md) queries. See the discussion about [`position_increment_gap`](/reference/elasticsearch/mapping-reference/position-increment-gap.md) for more detail. You can avoid this by making sure the `slop` parameter on the phrase queries is lower than the `position_increment_gap`. This is the default.
-::::
-
-
-If the `text` field sets `store` to true then order and duplicates are preserved.
-
-$$$synthetic-source-text-example-stored$$$
-
-```console
-PUT idx
-{
-  "settings": {
-    "index": {
-      "mapping": {
-        "source": {
-          "mode": "synthetic"
-        }
-      }
-    }
-  },
-  "mappings": {
-    "properties": {
-      "text": { "type": "text", "store": true }
-    }
-  }
-}
-PUT idx/_doc/1
-{
-  "text": [
-    "the quick brown fox",
-    "the quick brown fox",
-    "jumped over the lazy dog"
-  ]
-}
-```
-
-Will become:
-
 ```console-result
 {
   "text": [

server/src/main/java/org/elasticsearch/index/mapper/TextFieldMapper.java

@@ -1093,6 +1093,7 @@ private BlockSourceReader.LeafIteratorLookup blockReaderDisiLookup(BlockLoaderCo
                 // between text and keyword).
                 return BlockSourceReader.lookupMatchingAll();
             }
+
             if (isIndexed()) {
                 if (getTextSearchInfo().hasNorms()) {
                     return BlockSourceReader.lookupFromNorms(name());