[DOCS] Upsert documentation clarification

[thekofimensah]

• Added explanation to explain what an upsert is

• Used a more simple example as to prevent confusion with a more dense example. Also added the explanation of what behavior we can expect

[github-actions]

Documentation preview:

• ✨ Changed pages

[elasticsearchmachine]

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

[lcawl]

Hi! These API docs will be removed imminently so it's fine to backport this PR if it's only intended for V8 but for V9+ I've copied your suggested changes to elastic/elasticsearch-specification#3591

That's where we'll be generating docs like https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-update from going forward.

NOTE: I didn't update the /test/... since it worked as-is when I did a quick test. If you have any other clarifications you want to add to that PR or want more information about the new process, I'm happy to provide more info!

[leemthompo]

I like the idea of clarifying introduction.

But I think the flow of examples could be improved, from simplest to most complex. The base case would be to have the same value for update and upsert, so I think that should be the first example.

Something like this in terms of flow:

1. The simplest approach uses doc_as_upsert:

POST /test/_update/1
{
  "doc": {
    "price": 100
  },
  "doc_as_upsert": true
}

2. If you need different behavior for new documents, specify an upsert value:

POST /test/_update/1
{
  "doc": {
    "price": 100
  },
  "upsert": {
    "price": 100,
    "created_at": "2024-01-24"
  }
}

3. For complex update logic, use scripted_upsert...

[georgewallace]

@leemthompo are you good if we don't update the order of the examples in this version and tackle it in a future PR?

[elasticsearchmachine]

💚 Backport successful

Status	Branch	Result
✅	8.x
✅	8.17