[DOCS] Add links to flattened datatype

[lockewritesdocs]

This PR adds notes that link to the flattened datatype page from the KV Ingest Processor page and the Nested datatype page.

Also clarifies some descriptions about how Elasticsearch flattens objects and fixes minor typos.

Resolves #52239

Backports:

• [DOCS] Add links to flattened datatype (#56794) #56959 (7.8)
• [DOCS] Add links to flattened datatype (#56794) #56962 (7.7)
• [DOCS] Add links to flattened datatype (#56794) #56963 (7.x)

[elasticmachine]

Pinging @elastic/es-docs (>docs)

[elasticmachine]

Pinging @elastic/es-search (:Search/Search)

[jtibshirani]

This looks like a good start, thank you @lockewritesdocs for addressing it!

I left some suggestions, and also thought of one other place where we could mention flattened. In the 'mappings explosion' section, we could add a tip under "index.mapping.total_fields.limit" saying that if your mappings contain a large, arbitrary set of keys, it could be worth looking into the 'flattened' data type.

[jtibshirani]

To me the phrase "While a flattened object provides only a single field to search on" could be confusing -- it could suggest that you can only search the root field. What would you think of this tweak: "Using the KV Processor can create a large number of field names that you don't control. Consider using the flattened datatype instead, which maps an entire object as a single field and allows for simple searches over its contents."

[lockewritesdocs]

Agreed! I like your edit, which focuses on the positive (what the user can do) of the flattened object, rather than its limitations.

[jtibshirani]

Maybe we could move this tip to the end of the section? I think it comes right in the middle of an important explanation and breaks the continuity.

[lockewritesdocs]

I'm considering a new section for Interacted with nested documents that contains the ways users can interact with these documents, this new tip, and the Important note that exists. For example:

[jtibshirani]

A suggestion for how to restructure this tip:

• We could first give some context, saying that when ingesting key-value pairs with a large arbitrary set of keys, one technique is to model each pair as its own nested document with key and value fields.
• Instead we'd suggest the using flattened datatype, "which maps an entire object as a single field and allows for simple searches over its contents."

One other comment -- instead of describing the downside as "only be accessed within the scope of the nested query", I think it'd be clearer to mention that nested documents and queries are generally expensive, and that the flattened datatype is a better fit for this use case.

[lockewritesdocs]

Thanks @jtibshirani -- I made several changes to this Tip that incorporates your feedback. See my latest commit for specific changes.

[jtibshirani]

I think we either need to keep 'under the hood', or say 'a separate Lucene document'. Otherwise it this could be interpreted as each nested object corresponding to a new Elasticsearch document.

[lockewritesdocs]

I think that "indexed as a separate Lucene document" is more descriptive than "indexed as a separate document under the hood".

[jtibshirani]

For me this tip doesn't really fall under the topic 'interacting with nested documents'. It's actually a suggestion to avoid using nested documents, so I think it'd be good to keep it in the previous section where we introduce what nested objects are.

Alternatively, we could move it to the top of this page right after the initial description so it catches a user's attention. I don't think it would be too distracting, since it's a short tip.

[lockewritesdocs]

Good point. I think that moving this tip after the initial description makes sense. That way, users can read it and potentially say, "Ah, looks like I should be using flattened!" instead of having to read deep into the page to discover that information.

[jtibshirani]

Looks good to me!

[lockewritesdocs]

Thanks @jtibshirani! Adding @jrodewig for a review.

[jrodewig]

LGTM. I left some minor, non-blocking suggestions.

As a note, line width for docs is inconsistent, but we try to wrap documentation lines at 80 characters. This is sometimes impossible with links, but I think several of these new lines can be wrapped.