Skip to content

Conversation

thekofimensah
Copy link
Contributor

This is a small change but I felt the previous wording was only clear to those who already understand this behavior. Someone who is unfamiliar would be scratching their head, and hopefully this is an improvement.

Copy link
Contributor

Documentation preview:

@elasticsearchmachine elasticsearchmachine added needs:triage Requires assignment of a team area label external-contributor Pull request authored by a developer outside the Elasticsearch team v8.17.2 labels Jan 16, 2025
@AI-IshanBhatt AI-IshanBhatt added the >docs General docs changes label Jan 20, 2025
@elasticsearchmachine elasticsearchmachine added Team:Docs Meta label for docs team and removed needs:triage Requires assignment of a team area label labels Jan 20, 2025
@elasticsearchmachine
Copy link
Collaborator

Pinging @elastic/es-docs (Team:Docs)

@leemthompo
Copy link
Contributor

leemthompo commented Jan 20, 2025

I would suggest renaming this note to be specific about types/behaviors.

I'd reword the note to something like this:

.Arrays with `object` field type vs `nested` type
[NOTE]
====================================================
By default, arrays of objects are <<nested-arrays-flattening-objects,flattened>> 
during indexing using the <<object,`object` field type>>. For example, if you 
have multiple objects with a "name" property, all names will be stored in a 
single field. Queries against these flattened fields might match values from different objects. 
To query each object independently, use the <<nested,`nested`>> data type instead.
====================================================

I think the link to the flattening example is the best illustration of this behavior.

@leemthompo
Copy link
Contributor

(also remember to target main :) )

@leemthompo leemthompo changed the title Updated wording for clarity for new users [DOCS] Updated wording for clarity for new users Jan 20, 2025
@thekofimensah
Copy link
Contributor Author

I would suggest renaming this note to be specific about types/behaviors.

I'd reword the note to something like this:

.Arrays with `object` field type vs `nested` type
[NOTE]
====================================================
By default, arrays of objects are <<nested-arrays-flattening-objects,flattened>> 
during indexing using the <<object,`object` field type>>. For example, if you 
have multiple objects with a "name" property, all names will be stored in a 
single field. Queries against these flattened fields might match values from different objects. 
To query each object independently, use the <<nested,`nested`>> data type instead.
====================================================

I think the link to the flattening example is the best illustration of this behavior.

I also like the example in the flattened doc. I incorporated your heading and suggestions, though adjusted the wording a bit.

@leemthompo leemthompo added auto-backport Automatically create backport pull requests when merged v8.16.0 v9.0.0 v8.18.0 labels Jan 21, 2025
@leemthompo leemthompo self-assigned this Jan 21, 2025
@leemthompo leemthompo merged commit 4ca00fe into elastic:8.17 Jan 21, 2025
6 of 7 checks passed
leemthompo added a commit to leemthompo/elasticsearch that referenced this pull request Jan 21, 2025
leemthompo added a commit to leemthompo/elasticsearch that referenced this pull request Jan 21, 2025
leemthompo added a commit to leemthompo/elasticsearch that referenced this pull request Jan 21, 2025
@elasticsearchmachine
Copy link
Collaborator

💚 Backport successful

Status Branch Result
8.16
main
8.x

@leemthompo
Copy link
Contributor

If we had time to workshop this a bit more, we could have made the "unexpected behavior" more explicit because it remains a little handwavey, but this is definitely an improvement 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

auto-backport Automatically create backport pull requests when merged >docs General docs changes external-contributor Pull request authored by a developer outside the Elasticsearch team Team:Docs Meta label for docs team v8.16.0 v8.17.2 v8.18.0 v9.0.0

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants