[DOC-12632] Auto Reprepare for PREPARE Statements

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

@@ -197,10 +197,54 @@ The process is similar to creating a prepared statement without a local name:
 
 The auto-prepare feature is inactive by default.
 You can turn the auto-prepare feature on or off using the `auto-prepare` service-level query setting.
-For more details, refer to xref:n1ql:n1ql-manage/query-settings.adoc#auto-prepare[].
+For more details, refer to xref:n1ql:n1ql-manage/query-settings.adoc#auto-prepare[Query Settings].
 
 Auto-prepare is disabled for {sqlpp} requests which contain parameters, if they do not use the PREPARE statement.
 
+[[auto-reprepare]]
+== Auto-Reprepare
+
+When the auto-reprepare feature is active, a prepared statement automatically updates (reprepares) its plan whenever the GSI metadata version changes. 
+This happens when you create or drop an index, allowing prepared statements to use newer, more efficient indexes as they become available.
+
+To enable this feature, you must set bit 23 (0×800000 or 8388608) of the `n1ql-feat-ctrl` setting. 
+For information about how to set this value, see the table in the xref:learn:services-and-indexes/indexes/query-without-index.adoc#manage-sequential-scans[Manage Sequential Scans] section. 
+
+By default, a prepared statement is only reprepared if an index in its current plan becomes unavailable.
+With auto-reprepare, prepared statements can adapt to new indexes as well. 
+For example: 
+
+* *When the feature is inactive*: 
+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.
+
+* *When the feature is active*: 
+If you create a primary index after preparing a statement, the next time the statement executes, the Query Service generates a new plan using the primary index.
+Similarly, if a more optimal secondary index becomes available, the service flags the statement again and generates a new plan on the next execution using the new index.
+
+Although this feature improves performance, it has a potential drawback. 
+Any change to indexes, even those unrelated to a specific statement, can trigger an update. 
+For example, creating an unrelated secondary index or dropping an unused primary index can cause a statement to be reprepared. 
+While the statement may select the existing plan again, this can lead to additional load.
+If index changes are infrequent, the impact is minimal.
+
+To manage this effectively, you can enable or disable this feature as needed. 
+For example, you can enable the feature before creating new indexes and then disable it after all statements are reprepared.
+
+=== Manual Reprepare
+
+In addition to the automatic mode, you can also manually reprepare a statement. 
+To do this, update xref:n1ql:n1ql-manage/monitoring-n1ql-query.adoc#sys-prepared[system:prepareds] and unset the `planPreparedTime` field for the statement.
+
+For example, to reprepare a prepared statement named `NumParam` on a node with the IP address `127.0.0.1` and port `8091`, use the following query:
+
+[source,sqlpp]
+----
+UPDATE system:prepareds USE KEYS ["[127.0.0.1:8091]NumParam"] UNSET planPreparedTime;
+----
+
+You can repeat this operation after creating each relevant index to refresh the prepared statement's plan.
+
 [[auto-execute]]
 == Auto-Execute
 
@@ -214,7 +258,7 @@ You can use this when you need to execute the prepared statement again.
 
 The auto-execute feature is inactive by default.
 You can turn the auto-execute feature on or off using the `auto_execute` request-level query setting.
-For more details, refer to xref:n1ql:n1ql-manage/query-settings.adoc#auto_execute[].
+For more details, refer to xref:n1ql:n1ql-manage/query-settings.adoc#auto_execute[Query Settings].
 
 The auto-execute feature only works for {sqlpp} requests which actually contain the PREPARE statement.
 Prepared statements created by the <<auto-prepare,auto-prepare>> feature are not executed by the auto-execute feature.