From 95038844725baee7d6c082fc945e7c45d13bd5be Mon Sep 17 00:00:00 2001
From: Dominik Schmidt <dev@dominik-schmidt.de>
Date: Mon, 31 Aug 2026 13:11:36 +0200
Subject: [PATCH] docs(search): migration notes for schema v4

Also make the reindex copy safe to run after the service already indexed (op_type create, conflicts proceed).
---
 services/search/MIGRATION.md | 17 ++++++++++-------
 services/search/README.md    |  5 ++++-
 2 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/services/search/MIGRATION.md b/services/search/MIGRATION.md
index a0cb646e61..17c51e693b 100644
--- a/services/search/MIGRATION.md
+++ b/services/search/MIGRATION.md
@@ -9,9 +9,11 @@ until you remove it.
 
 ### OpenSearch
 
-The new index is `opencloud-resource-v3`. Fill it in one of two ways:
+The new index is `opencloud-resource-v4`. Fill it in one of two ways:
 
-- copy the old index, fast and keeps the extracted file contents, or
+- copy the old index, fast and keeps the extracted file contents; run it soon
+  after the upgrade, documents the service has indexed since win over copied
+  ones (`op_type: create`), or
 - index all spaces again, slower since every file is read once more, but drops
   documents that no longer have a resource.
 
@@ -21,12 +23,13 @@ The address below is the one from `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_ADDRESSES`,
 
 ```shell
 # either copy the old index
-curl -X POST "https://opensearch.example.com:9200/_reindex?wait_for_completion=false" \
+curl -X POST "https://os.example.com:9200/_reindex?wait_for_completion=false" \
   -H 'Content-Type: application/json' -d '
-  {"source":{"index":"opencloud-resource"},"dest":{"index":"opencloud-resource-v3"}}'
+  {"source":{"index":"opencloud-resource","conflicts":"proceed"},
+   "dest":{"index":"opencloud-resource-v4","op_type":"create"}}'
 
 # the answer carries a task id, watch it while it runs
-curl "https://opensearch.example.com:9200/_tasks/<task-id>"
+curl "https://os.example.com:9200/_tasks/<task-id>"
 
 # or index all spaces again, the service keeps running while it happens
 opencloud search index --all-spaces
@@ -35,12 +38,12 @@ opencloud search index --all-spaces
 Once the new index is filled, remove the old one:
 
 ```shell
-curl -X DELETE "https://opensearch.example.com:9200/opencloud-resource"
+curl -X DELETE "https://os.example.com:9200/opencloud-resource"
 ```
 
 ### bleve
 
-The new index is the `bleve-v2` directory next to the old `bleve` one, both in
+The new index is the `bleve-v4` directory next to the old `bleve` one, both in
 `$OC_BASE_DATA_PATH/search` by default (`SEARCH_ENGINE_BLEVE_DATA_PATH`). A
 bleve index cannot be copied, index all spaces again:
 
diff --git a/services/search/README.md b/services/search/README.md
index f0938d14e9..984684ab3c 100644
--- a/services/search/README.md
+++ b/services/search/README.md
@@ -39,7 +39,10 @@ To enable OpenSearch as a backend, the following settings must be set:
 
 Additionally, the following optional settings can be set:
 
-*   `SEARCH_ENGINE_OPEN_SEARCH_RESOURCE_INDEX_NAME=val` (default: `opencloud-resource`): Base name of the OpenSearch index. The running index is suffixed with the schema version (e.g. `opencloud-resource-v3`); a breaking schema change targets a fresh index and leaves the old one in place.
+*   `SEARCH_ENGINE_OPEN_SEARCH_RESOURCE_INDEX_NAME=val` (default:
+    `opencloud-resource`): base name of the OpenSearch index. The running
+    index is suffixed with the schema version (`opencloud-resource-v4`); a
+    breaking schema change targets a fresh index, the old one stays in place.
 *   `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_USERNAME=val`: Username for HTTP Basic Authentication.
 *   `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_PASSWORD=val`: Password for HTTP Basic Authentication.
 *   `SEARCH_ENGINE_OPEN_SEARCH_CLIENT_HEADER=val`: HTTP headers to include in requests.