From 02761f5fe00085a5af76a4c321b467fb7d7bcb54 Mon Sep 17 00:00:00 2001
From: Nik Everett <nik9000@gmail.com>
Date: Tue, 21 Jun 2016 15:33:25 -0400
Subject: [PATCH] Docs: migration notes for _timestamp and _ttl

We aren't able to actually create an index with _timestamp enabled
to test the migration, or, at least, we won't be able to after #18980
is re-merged. But the docs are still ok.

Closes #19007
---
 .../migration/migrate_5_0/mapping.asciidoc    | 105 ++++++++++++++++++
 1 file changed, 105 insertions(+)

diff --git a/docs/reference/migration/migrate_5_0/mapping.asciidoc b/docs/reference/migration/migrate_5_0/mapping.asciidoc
index 2d0ca4b9fb6b5..fa5411cf4269d 100644
--- a/docs/reference/migration/migrate_5_0/mapping.asciidoc
+++ b/docs/reference/migration/migrate_5_0/mapping.asciidoc
@@ -157,3 +157,108 @@ Per-field boosts on the `_all` are now compressed into a single byte instead
 of the 4 bytes used previously. While this will make the index much more
 space-efficient, it also means that index time boosts will be less accurately
 encoded.
+
+==== `_ttl` and `_timestamp` cannot be created
+
+You can no longer create indexes with `_ttl` or `_timestamp` enabled. Indexes
+with them enabled created before 5.0 will continue to work.
+
+You should replace `_timestamp` in new indexes by adding a field to your source
+either in the application producing the data or with an ingest pipline like
+this one:
+
+[source,js]
+---------------
+PUT _ingest/pipeline/timestamp
+{
+  "description" : "Adds a timestamp field at the current time",
+  "processors" : [ {
+    "set" : {
+      "field": "timestamp",
+      "value": "{{_ingest.timestamp}}"
+    }
+  } ]
+}
+
+PUT newindex/type/1?pipeline=timestamp
+{
+  "example": "data"
+}
+
+GET newindex/type/1
+---------------
+// CONSOLE
+
+Which produces
+[source,js]
+---------------
+{
+  "_source": {
+    "example": "data",
+    "timestamp": "2016-06-21T18:48:55.560+0000"
+  },
+  ...
+}
+---------------
+// TESTRESPONSE[s/\.\.\./"found": true, "_id": "1", "_index": "newindex", "_type": "type", "_version": 1/]
+// TESTRESPONSE[s/"2016-06-21T18:48:55.560\+0000"/"$body._source.timestamp"/]
+
+If you have an old index created with 2.x that has `_timestamp` enabled then
+you can migrate it to a new index with the a `timestamp` field in the source
+with reindex:
+
+[source,js]
+---------------
+POST _reindex
+{
+  "source": {
+    "index": "oldindex"
+  },
+  "dest": {
+    "index": "newindex"
+  },
+  "script": {
+    "lang": "painless",
+    "inline": "ctx._source.timestamp = ctx._timestamp; ctx._timestamp = null"
+  }
+}
+---------------
+// CONSOLE
+// TEST[s/^/PUT oldindex\nGET _cluster\/health?wait_for_status=yellow\n/]
+
+You can replace `_ttl` with time based index names (preferred) or by adding a
+cron job which runs a delete-by-query on a timestamp field in the source
+document. If you had documents like this:
+
+[source,js]
+---------------
+POST index/type/_bulk
+{"index":{"_id":1}}
+{"example": "data", "timestamp": "2016-06-21T18:48:55.560+0000" }
+{"index":{"_id":2}}
+{"example": "data", "timestamp": "2016-04-21T18:48:55.560+0000" }
+---------------
+// CONSOLE
+
+Then you could delete all of the documents from before June 1st with:
+
+[source,js]
+---------------
+POST index/type/_delete_by_query
+{
+  "query": {
+    "range" : {
+      "timestamp" : {
+        "lt" : "2016-05-01"
+      }
+    }
+  }
+}
+---------------
+// CONSOLE
+// TEST[continued]
+
+IMPORTANT: Keep in mind that deleting documents from an index is very expensive
+compared to deleting whole indexes. That is why time based indexes are
+recommended over this sort of thing and why `_ttl` was deprecated in the first
+place.