From 9535c31259e9fc962c82970bd7cf1d9c89877e06 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Tue, 29 Jul 2025 15:48:42 +0530 Subject: [PATCH 1/7] Add a new section for automatic re-prepare --- .../n1ql-language-reference/prepare.adoc | 28 ++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc index 110bac2ba..a76851c53 100644 --- a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc @@ -197,10 +197,36 @@ 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 Re-Prepare + +When the automatic re-prepare feature is active, a prepared statement is automatically re-prepared when the GSI metadata version changes, such as when an index is created or dropped. + +By default, a prepared statement is only re-prepared automatically if an index used in its plan is no longer available. +To enable the automatic re-prepare feature, you must set bit 23 (0x800000 or 8388608) in the xref:n1ql:n1ql-manage/query-settings.adoc#n1ql-feat-ctrl[n1ql-feat-ctrl] setting. + +When this feature is enabled, any change in index metadata triggers a flag on affected statements, indicating they should be re-prepared. +The next time such a statement is executed, a new plan is generated. +This can allow the use of newer, more efficient indexes without requiring manual intervention. + +A potential drawback of this mode is that any change to indexes, even those unrelated to the statement can cause the statement to be re-prepared. +For example, creating an unrelated secondary index or dropping an unused primary index will trigger a re-preparation. +While it will likely pick the same plan again, this can lead to additional load during index changes. +If the index changes are infrequent, the imapct may be negligible. + +You can enble or disable this mode as needed. + +In addition to enabling the automatic mode, you can manually trigger a re-prepare of a statement by updating xref:n1ql:n1ql-manage/monitoring-n1ql-query.adoc#sys-prepared[system:prepareds] and unsetting the `planPreparedTime` field for the statement. + +[source,sqlpp] +---- +UPDATE system:prepareds USE KEYS ["[1.1.1.1:8091]pstmt1"] UNSET planPreparedTime; +---- + [[auto-execute]] == Auto-Execute From 690f550dfca264f616882f62d06e70333d508af8 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Wed, 30 Jul 2025 15:40:45 +0530 Subject: [PATCH 2/7] Update content --- .../n1ql-language-reference/prepare.adoc | 39 +++++++++++++------ 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc index a76851c53..aa5fb5b21 100644 --- a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc @@ -204,29 +204,46 @@ Auto-prepare is disabled for {sqlpp} requests which contain parameters, if they [[auto-reprepare]] == Auto Re-Prepare -When the automatic re-prepare feature is active, a prepared statement is automatically re-prepared when the GSI metadata version changes, such as when an index is created or dropped. +When the automatic re-prepare feature is active, a prepared statement automatically re-prepares itself when there's a change to the GSI metadata. +This occurs when an index is created or dropped, allowing prepared statements to automatically adapt and use newer, more efficient indexes as they become available. -By default, a prepared statement is only re-prepared automatically if an index used in its plan is no longer available. -To enable the automatic re-prepare feature, you must set bit 23 (0x800000 or 8388608) in the xref:n1ql:n1ql-manage/query-settings.adoc#n1ql-feat-ctrl[n1ql-feat-ctrl] setting. +To activate this feature, set bit 23 (0x800000 or 8388608) of the `n1ql-feat-ctrl` setting. +For details on how to set this value, refer to the table in the xref:learn:services-and-indexes/indexes/query-without-index.adoc#manage-sequential-scans[Manage Sequential Scans] section. -When this feature is enabled, any change in index metadata triggers a flag on affected statements, indicating they should be re-prepared. -The next time such a statement is executed, a new plan is generated. -This can allow the use of newer, more efficient indexes without requiring manual intervention. +NOTE: By default, a prepared statement only re-prepares automatically if an index used in its existing plan is no longer available. -A potential drawback of this mode is that any change to indexes, even those unrelated to the statement can cause the statement to be re-prepared. +Consider the following scenarios: + +* *When the feature is inactive*: + - If a statement is prepared without an existing index, a plan is created using a sequential scan. + - Even if a primary index or a more efficient secondary index is created later, the prepared statement continues to use the sequential scan. + - Consequently, the prepared statement does not automatically benefit from the new or improved indexes. +* *When the feature is active*: + - When a primary index is created, the prepared statement is flagged for re-preparation. + - On its next execution, a new plan is created using the primary index. + - Similarly, if a more optimal secondary index is created later, the statement is again flagged for re-preparation, and a new plan is generated on the subsequent execution using the secondary index. + - This ensures that the prepared statement dynamically leverages the most efficient available indexes. + +A potential drawback of this feature is that any change to indexes, even those unrelated to the specific statement, can cause the statement to be re-prepared. For example, creating an unrelated secondary index or dropping an unused primary index will trigger a re-preparation. -While it will likely pick the same plan again, this can lead to additional load during index changes. -If the index changes are infrequent, the imapct may be negligible. +While the statement will likely select the same plan again, this can lead to additional load during index changes. +However, if index changes are infrequent, the imapct may be negligible. + +You can enable or disable this the feature as needed. +For instance, you can enable the feature before creating a selection of new indexes and then disable it after you have confirmedd all prepared statements have been re-prepared. -You can enble or disable this mode as needed. +=== Manual Re-Preparation -In addition to enabling the automatic mode, you can manually trigger a re-prepare of a statement by updating xref:n1ql:n1ql-manage/monitoring-n1ql-query.adoc#sys-prepared[system:prepareds] and unsetting the `planPreparedTime` field for the statement. +In addition to the automatic mode, you can manually trigger a re-preparation of a statement by updating xref:n1ql:n1ql-manage/monitoring-n1ql-query.adoc#sys-prepared[system:prepareds] and unsetting the `planPreparedTime` field for the statement. [source,sqlpp] ---- UPDATE system:prepareds USE KEYS ["[1.1.1.1:8091]pstmt1"] UNSET planPreparedTime; ---- +For a scenario like the one described, you can perform such an update for the prepared statement after each relevant index is created, if you want the plan to change. + + [[auto-execute]] == Auto-Execute From 01a1d486138723f36b216571b8f1d2b7e4036b4d Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Fri, 1 Aug 2025 17:18:51 +0530 Subject: [PATCH 3/7] Update content --- .../n1ql-language-reference/prepare.adoc | 53 ++++++++++--------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc index aa5fb5b21..188c2e2a5 100644 --- a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc @@ -202,47 +202,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. [[auto-reprepare]] -== Auto Re-Prepare +== Auto-Reprepare -When the automatic re-prepare feature is active, a prepared statement automatically re-prepares itself when there's a change to the GSI metadata. -This occurs when an index is created or dropped, allowing prepared statements to automatically adapt and use newer, more efficient indexes as they become available. +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 activate this feature, set bit 23 (0x800000 or 8388608) of the `n1ql-feat-ctrl` setting. -For details on how to set this value, refer to the table in the xref:learn:services-and-indexes/indexes/query-without-index.adoc#manage-sequential-scans[Manage Sequential Scans] section. +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. -NOTE: By default, a prepared statement only re-prepares automatically if an index used in its existing plan is no longer available. - -Consider the following scenarios: +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. * *When the feature is inactive*: - - If a statement is prepared without an existing index, a plan is created using a sequential scan. - - Even if a primary index or a more efficient secondary index is created later, the prepared statement continues to use the sequential scan. - - Consequently, the prepared statement does not automatically benefit from the new or improved indexes. -* *When the feature is active*: - - When a primary index is created, the prepared statement is flagged for re-preparation. - - On its next execution, a new plan is created using the primary index. - - Similarly, if a more optimal secondary index is created later, the statement is again flagged for re-preparation, and a new plan is generated on the subsequent execution using the secondary index. - - This ensures that the prepared statement dynamically leverages the most efficient available indexes. +A prepared statement keeps its original execution plan, even if you create new indexes later. +For example, if no indexes exist when you prepare a statement, the prepared plan uses sequential scan. +If you create a primary index or a secondary index afterwards, the statement still continues to use sequential scan, and does not automatically benefit from the new indexes. + +* *When the feature is active*: +The Query Service tracks changes to indexes. +When you create a new index or drop an existing one, the service flags the prepared statement for an update. +For example, if you create a primary index after preparing a statement, the next time the statement executes, it 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. -A potential drawback of this feature is that any change to indexes, even those unrelated to the specific statement, can cause the statement to be re-prepared. -For example, creating an unrelated secondary index or dropping an unused primary index will trigger a re-preparation. -While the statement will likely select the same plan again, this can lead to additional load during index changes. -However, if index changes are infrequent, the imapct may be negligible. +While 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 statment to be reprepared. +Although the statement will likely select the existing plan again, this can lead to additional load. +If index changes are infrequent, the impact is minimal. -You can enable or disable this the feature as needed. -For instance, you can enable the feature before creating a selection of new indexes and then disable it after you have confirmedd all prepared statements have been re-prepared. +To manage this effectively, you can enable or disable this feature as needed. +For instance, you can enable the feature before creating a selection of new indexes and then disable it after all statements have been reprepared. -=== Manual Re-Preparation +=== Manual Reprepare -In addition to the automatic mode, you can manually trigger a re-preparation of a statement by updating xref:n1ql:n1ql-manage/monitoring-n1ql-query.adoc#sys-prepared[system:prepareds] and unsetting the `planPreparedTime` field for the statement. +In addition to the automatic mode, you can also manually reprepare a prepared 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. [source,sqlpp] ---- UPDATE system:prepareds USE KEYS ["[1.1.1.1:8091]pstmt1"] UNSET planPreparedTime; ---- -For a scenario like the one described, you can perform such an update for the prepared statement after each relevant index is created, if you want the plan to change. - +You can repeat this operation after creating relevant indexes to refresh the prepared statement's plan. [[auto-execute]] == Auto-Execute From 75794dffc470579b7b74441532a0fe5ac9cac9d6 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Sun, 3 Aug 2025 12:10:53 +0530 Subject: [PATCH 4/7] Update content --- .../n1ql-language-reference/prepare.adoc | 25 ++++++++++--------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc index 188c2e2a5..2a79361f4 100644 --- a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc @@ -212,30 +212,31 @@ For information about how to set this value, see the table in the xref:learn:ser 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*: -A prepared statement keeps its original execution plan, even if you create new indexes later. -For example, if no indexes exist when you prepare a statement, the prepared plan uses sequential scan. -If you create a primary index or a secondary index afterwards, the statement still continues to use sequential scan, and does not automatically benefit from the new indexes. +//A prepared statement keeps its original execution plan, even if you create new indexes later. +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*: -The Query Service tracks changes to indexes. -When you create a new index or drop an existing one, the service flags the prepared statement for an update. -For example, if you create a primary index after preparing a statement, the next time the statement executes, it generates a new plan using the primary index. +//The Query Service tracks changes to indexes. +//When you create a new index or drop an existing one, the service flags the prepared statement for an update. +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. -While this feature improves performance, it has a potential drawback. +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 statment to be reprepared. -Although the statement will likely select the existing plan again, this can lead to additional load. +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 instance, you can enable the feature before creating a selection of new indexes and then disable it after all statements have been reprepared. +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 prepared statement. +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. [source,sqlpp] @@ -243,7 +244,7 @@ To do this, update xref:n1ql:n1ql-manage/monitoring-n1ql-query.adoc#sys-prepared UPDATE system:prepareds USE KEYS ["[1.1.1.1:8091]pstmt1"] UNSET planPreparedTime; ---- -You can repeat this operation after creating relevant indexes to refresh the prepared statement's plan. +You can repeat this operation after creating each relevant index to refresh the prepared statement's plan. [[auto-execute]] == Auto-Execute From ffbb0b89dc50578ead054f647a658d5e95c63f0f Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Sun, 3 Aug 2025 12:15:11 +0530 Subject: [PATCH 5/7] Minor fix --- modules/n1ql/pages/n1ql-language-reference/prepare.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc index 2a79361f4..f00fefea5 100644 --- a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc @@ -259,7 +259,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. From a3b301196fe50d68221d4620111106271f2dd290 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Sun, 3 Aug 2025 13:24:48 +0530 Subject: [PATCH 6/7] Add a line to explain the example --- modules/n1ql/pages/n1ql-language-reference/prepare.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc index f00fefea5..085899548 100644 --- a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc @@ -239,9 +239,11 @@ For example, you can enable the feature before creating new indexes and then dis 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 ["[1.1.1.1:8091]pstmt1"] UNSET planPreparedTime; +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. From c3dd0e3759c5e34b6adec44b0f1efde6583788c7 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Tue, 5 Aug 2025 12:05:53 +0530 Subject: [PATCH 7/7] Delete the commented out lines --- modules/n1ql/pages/n1ql-language-reference/prepare.adoc | 3 --- 1 file changed, 3 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc index 085899548..40e36a8e8 100644 --- a/modules/n1ql/pages/n1ql-language-reference/prepare.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/prepare.adoc @@ -215,13 +215,10 @@ With auto-reprepare, prepared statements can adapt to new indexes as well. For example: * *When the feature is inactive*: -//A prepared statement keeps its original execution plan, even if you create new indexes later. 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*: -//The Query Service tracks changes to indexes. -//When you create a new index or drop an existing one, the service flags the prepared statement for an update. 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.