|
@@ -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]
|
|
|
----
|