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.

@github-actions
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