[DOCS] Add 'update/delete docs in a data stream' tutorial (#58194)

Adds a tutorial for updating and deleting documents in the backing
indices of a data stream.

docs/reference/data-streams/data-streams-overview.asciidoc

@@ -138,6 +138,8 @@ following requests to the backing index containing the document:
 
 * A <<docs-delete,delete API>> request
 
+See <<update-delete-docs-in-a-data-stream>>.
+
 TIP: If you need to frequently update or delete existing documents across
 multiple indices, we recommend using an <<indices-add-alias,index alias>> and
 <<indices-templates,index template>> instead of a data stream. You can still

docs/reference/data-streams/use-a-data-stream.asciidoc

@@ -8,6 +8,7 @@ the following:
 * <<search-a-data-stream>>
 * <<manually-roll-over-a-data-stream>>
 * <<reindex-with-a-data-stream>>
+* <<update-delete-docs-in-a-data-stream>>
 
 ////
 [source,console]
@@ -280,6 +281,201 @@ POST /_reindex
 // TEST[continued]
 ====
 
+[discrete]
+[[update-delete-docs-in-a-data-stream]]
+=== Update or delete documents in a data stream
+
+Data streams are designed to be <<data-streams-append-only,append-only>>. This
+means you cannot send update or deletion requests for existing documents to a
+data stream. However, you can send update or deletion requests to the backing
+index containing the document.
+
+To delete or update a document in a data stream, you first need to get:
+
+* The <<mapping-id-field,document ID>>
+* The name of the backing index that contains the document
+
+If you want to update a document, you must also get its current
+<<optimistic-concurrency-control,sequence number and primary term>>.
+
+You can use a <<search-a-data-stream,search request>> to retrieve this
+information.
+
+.*Example*
+[%collapsible]
+====
+////
+[source,console]
+----
+PUT /logs/_create/bfspvnIBr7VVZlfp2lqX?refresh=wait_for
+{
+  "@timestamp": "2020-12-07T11:06:07.000Z",
+  "user": {
+    "id": "yWIumJd7"
+  },
+  "message": "Login successful"
+}
+----
+// TEST[continued]
+////
+
+The following search request retrieves documents in the `logs` data stream with
+a `user.id` of `yWIumJd7`. By default, this search returns the document ID and
+backing index for any matching documents.
+
+The request includes a `"seq_no_primary_term": true` argument. This means the
+search also returns the sequence number and primary term for any matching
+documents.
+
+[source,console]
+----
+GET /logs/_search
+{
+  "seq_no_primary_term": true,
+  "query": {
+    "match": {
+      "user.id": "yWIumJd7"
+    }
+  }
+}
+----
+// TEST[continued]
+
+The API returns the following response. The `hits.hits` property contains
+information for any documents matching the search.
+
+[source,console-result]
+----
+{
+  "took": 20,
+  "timed_out": false,
+  "_shards": {
+    "total": 2,
+    "successful": 2,
+    "skipped": 0,
+    "failed": 0
+  },
+  "hits": {
+    "total": {
+      "value": 1,
+      "relation": "eq"
+    },
+    "max_score": 0.2876821,
+    "hits": [
+      {
+        "_index": ".ds-logs-000002",                <1>
+        "_id": "bfspvnIBr7VVZlfp2lqX",              <2>
+        "_seq_no": 4,                               <3>
+        "_primary_term": 1,                         <4>
+        "_score": 0.2876821,
+        "_source": {
+          "@timestamp": "2020-12-07T11:06:07.000Z",
+          "user": {
+            "id": "yWIumJd7"
+          },
+          "message": "Login successful"
+        }
+      }
+    ]
+  }
+}
+----
+// TESTRESPONSE[s/"took": 20/"took": $body.took/]
+
+<1> Backing index containing the matching document
+<2> Document ID for the document
+<3> Current sequence number for the document
+<4> Primary term for the document
+====
+
+You can use an <<docs-index_,index API>> request to update an individual
+document. To prevent an accidental overwrite, this request must include valid
+`if_seq_no` and `if_primary_term` arguments.
+
+.*Example*
+[%collapsible]
+====
+The following index API request updates an existing document in the `logs` data
+stream. The request targets document ID `bfspvnIBr7VVZlfp2lqX` in the
+`.ds-logs-000002` backing index.
+
+The request also includes the current sequence number and primary term in the
+respective `if_seq_no` and `if_primary_term` query parameters. The request body
+contains a new JSON source for the document.
+
+[source,console]
+----
+PUT /.ds-logs-000002/_doc/bfspvnIBr7VVZlfp2lqX?if_seq_no=4&if_primary_term=1
+{
+  "@timestamp": "2020-12-07T11:06:07.000Z",
+  "user": {
+    "id": "8a4f500d"
+  },
+  "message": "Login successful"
+}
+----
+// TEST[continued]
+====
+
+You use the <<docs-delete,delete API>> to delete individual documents. Deletion
+requests do not require a sequence number or primary term.
+
+.*Example*
+[%collapsible]
+====
+The following index API request deletes an existing document in the `logs` data
+stream. The request targets document ID `bfspvnIBr7VVZlfp2lqX` in the
+`.ds-logs-000002` backing index.
+
+[source,console]
+----
+DELETE /.ds-logs-000002/_doc/bfspvnIBr7VVZlfp2lqX
+----
+// TEST[continued]
+====
+
+You can use the <<docs-bulk,bulk API>> to delete or update multiple documents in
+one request using `delete`, `index`, or `update` actions.
+
+If the action type is `index`, the action must include valid
+<<bulk-optimistic-concurrency-control,`if_seq_no` and `if_primary_term`>>
+arguments.
+
+.*Example*
+[%collapsible]
+====
+////
+[source,console]
+----
+PUT /logs/_create/bfspvnIBr7VVZlfp2lqX?refresh=wait_for
+{
+  "@timestamp": "2020-12-07T11:06:07.000Z",
+  "user": {
+    "id": "yWIumJd7"
+  },
+  "message": "Login successful"
+}
+----
+// TEST[continued]
+////
+
+The following bulk API request uses an `index` action to update an existing
+document in the `logs` data stream.
+
+The `index` action targets document ID `bfspvnIBr7VVZlfp2lqX` in the
+`.ds-logs-000002` backing index. The action also includes the current sequence
+number and primary term in the respective `if_seq_no` and `if_primary_term`
+parameters.
+
+[source,console]
+----
+PUT /_bulk?refresh
+{ "index": { "_index": ".ds-logs-000002", "_id": "bfspvnIBr7VVZlfp2lqX", "if_seq_no": 4, "if_primary_term": 1 } }
+{ "@timestamp": "2020-12-07T11:06:07.000Z", "user": { "id": "8a4f500d" }, "message": "Login successful" }
+----
+// TEST[continued]
+====
+
 ////
 [source,console]
 ----