[DOC-13962] Automatic Reprepare - Capella (#626)

Author: rakhi-prathap

modules/n1ql/pages/n1ql-language-reference/execute.adoc

@@ -67,7 +67,7 @@ Once retrieved, the query engine creates a local cached copy of the prepared sta
 An error is returned if the name does not identify a prepared statement.
 
 [[auto-reprepare]]
-== Auto-Reprepare
+== Automatic Reprepare for Invalid Plans
 
 Before execution, the query engine checks whether the statement plan is still valid -- i.e. that all the indexes and keyspaces to which the plan refers are unchanged.
 If any indexes or keyspaces have changed, the statement is automatically prepared again, so that the plan matches the new set of resources.
@@ -76,6 +76,10 @@ If this automatic reprepare succeeds, the statement simply executes as expected.
 However, if any required resources are found to be missing, execution of the affected prepared statement fails until those resources are created again.
 Once the resources are available again, execution proceeds without any further intervention.
 
+NOTE: The Query Service also provides an opt-in feature that extends this behavior.
+When enabled, the service monitors GSI metadata version changes (such as when you create or drop indexes) and reprepares affected statements. 
+For more information, see xref:n1ql-language-reference/prepare.adoc#auto-reprepare-index[Automatic Reprepare on Index Changes].
+
 [[parameters]]
 == Parameters
 

modules/n1ql/pages/n1ql-language-reference/prepare.adoc

@@ -214,13 +214,48 @@ For more details, refer to xref:n1ql:n1ql-manage/query-settings.adoc#auto-prepar
 Auto-prepare is disabled for {sqlpp} requests which contain parameters, if they do not use the PREPARE statement.
 endif::flag-devex-rest-api[]
 
-[[auto-reprepare]]
-== Manual Reprepare
+[[auto-reprepare-index]]
+== Automatic Reprepare on Index Changes
+
+The Query Service validates a statement's prepared plan before executing it.
+If the plan is invalid—for example, if any indexes or keyspaces become unavailable—the service automatically reprepares the statement.
+This is the xref:n1ql-language-reference/execute.adoc#auto-reprepare[default behavior].
+
+The Query Service also provides an opt-in feature that extends this behavior.
+When enabled, the service monitors GSI metadata version changes (such as when you create or drop indexes) and flags affected statements for repreparation.
+The next time a flagged statement runs, the service generates a new plan to match the updated index set.
+This ensures statements automatically use newer, more efficient indexes as they become available. 
+
+The following example shows how the feature works when it's active: 
+
+. You prepare a statement and no suitable indexes exist to support it;
+the Query Service creates a plan that uses a sequential scan.
+
+. You then create a primary index that better supports the statement;
+the service flags the statement, and on the next run generates a new plan that uses the primary index.
+
+. You later create a secondary index that is an even better choice for the statement;
+the service flags the statement again, and on the next run generates a new plan that uses the secondary index.
 
-[.status]#Couchbase Server 8.0#
+If the feature is inactive, the statement continues to use the original plan (such as a sequential scan) even after you create new indexes.
 
-If no indexes exist when you prepare a statement, then the prepared plan uses a sequential scan.
-If you create a primary index or a secondary index later, the statement still continues to use the sequential scan and does not automatically benefit from the new indexes.
+To enable the feature, contact xref:support:manage-support.adoc[Couchbase Support]. 
+
+You can also manually reprepare statements at any time. 
+For more information, see <<manual-reprepare>>.
+
+[IMPORTANT]
+====
+This feature can increase the load on the Query Service. 
+Any index change, even one unrelated to a given statement, can trigger a repreparation.
+For example, creating or dropping an index that a statement does not use can still flag it for repreparation.
+In such cases, the statement reprepares only to select the same plan again, resulting in redundant work.
+
+To reduce this overhead, enable the feature temporarily when you create or drop indexes, and disable it after all statements are reprepared.
+If index changes are infrequent, the effect is minimal.
+====
+
+== Manual Reprepare
 
 To manually reprepare a statement, update xref:n1ql:n1ql-manage/monitoring-n1ql-query.adoc#sys-prepared[system:prepareds] and unset the `planPreparedTime` field for the statement.