diff --git a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc index 110bac2ba..40e36a8e8 100644 --- a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc +++ b/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 <> feature are not executed by the auto-execute feature.