How do Elasticsearch's "include_in_parent" / "include_in_root" work? Should it show in '_source'?

Question

In a simple Elasticsearch mapping like this:

{
    "personal_document": {
        "analyzer": "standard",
        "_timestamp": {
            "enabled": true
        },
        "properties": {
            "description": {
                "type": "multi_field",
                "fields": {
                    "sort": {
                        "type": "string",
                        "index": "not_analyzed"
                    },
                    "description": {
                        "type": "string",
                        "include_in_root": true
                    }
                }
            },
            "my_nested": {
                "type": "nested",
                "include_in_root": true,
                "properties": {
                    "description": {
                        "type": "string"
                    }
                }
            }
        }
    }
}

.... isn't "include_in_root": true supposed to add the field my_nested.description to the root document?

And during a query am I not supposed to see THAT field into the _source field?

and

Specifying an highlight directive on the field 'my_nested.description' would automatically retrieve the _included_in_root value_ instead of the nested field?

(something like this) "highlight": { "fields": { "description": {}, "my_nested.description": {} } }

---

Or do I have some misunderstanding of the official nested type documentation? (that is not really clear)

Answer 1

If the include_in_parent or include_in_root options are enabled on the nested documents then Elasticsearch internally indexes the data with nested fields flattened on the parent document. However, this is just internal for Elasticsearch and you'll never see them in the _source field.

If the user field is of type object, this document would be indexed internally something like this...

as it is refered here.

Thus, you continue to perform actions (like the highlights that you mention) by referring to the nested document's fields. The highlight syntax that you refer to should look like this

"highlight": {
    "fields": {
      "my_nested.description": {}
    }
}

and not

"highlight": {
    "fields": {
      "description": {}
    }
}