From 292130e6af267cd69893f2f07728de6b40f75b79 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Mon, 3 Aug 2026 14:25:03 +0530 Subject: [PATCH 1/8] Update content --- modules/ROOT/nav.adoc | 1 + .../pages/manage-settings/query-settings.adoc | 70 +++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 modules/manage/pages/manage-settings/query-settings.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 19c55f1ff8..cdd9c62d35 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -134,6 +134,7 @@ include::third-party:partial$nav.adoc[] * xref:manage:manage-logging/manage-logging.adoc[Manage Logging] * xref:manage:manage-settings/manage-settings.adoc[Manage Settings] ** xref:manage:manage-settings/general-settings.adoc[General] + ** xref:manage:manage-settings/query-settings.adoc[Query] ** xref:manage:manage-settings/configure-compact-settings.adoc[Auto-Compaction] ** xref:manage:manage-settings/configure-alerts.adoc[Alerts] ** xref:manage:manage-settings/install-sample-buckets.adoc[Sample Buckets] diff --git a/modules/manage/pages/manage-settings/query-settings.adoc b/modules/manage/pages/manage-settings/query-settings.adoc new file mode 100644 index 0000000000..886e3e8efe --- /dev/null +++ b/modules/manage/pages/manage-settings/query-settings.adoc @@ -0,0 +1,70 @@ +== Query +:description: You can configure the query settings for your cluster. +:page-topic-type: guide + + +[abstract] +{description} + + +The Query tab lets you manage how queries run on your cluster. + +== Navigate to Query Settings + +To navigate to the Query Settings tab, follow these steps: + +. Log into the Couchbase Server Web Console. +. From the left navigation menu, click **Settings**. +. Click the **Query** tab. + +== Configuration Options + +The following table describes the settings available in the Query tab: + +[cols="1,1,1", options="header"] +|=== +| Setting | Description | Default Value + +| CURL() Function Access +| Set the URLs the `CURL()` function can access. + +* *Restricted*: Allows access to only URLS listed in *Allowed CURL URLs*. +* *Unrestricted*: The `CURL()` function can access any URL. + +| *Unrestricted* + +| Allowed CURL URLs +| Specify the URLs that the `CURL()` function can access when *CURL() Function Access* is set to *Restricted*. +You can specify multiple URL. + +To add a URL, click btn:[+]. + +To remove a URL, click btn:[-] next to the URL. + +| None + +| Disallowed CURL URLs + +| Specify the URLs that the `CURL()` function cannot access. +You can specify multiple URL. + +To add a URL, click btn:[+]. + +To remove a URL, click btn:[-] next to the URL. + +| None + +| Query Temp Disk Path + +| When a query has an extremely large corresponding index scan, the indexer buffers the results into a temporary directory. Since this method may cause high I/O and works differently on Windows, you can configure backfill settings for the SQL++ engine and its embedded GSI client. + +The *Query Temp Disk Path* field enables you to specify the path to which the indexer writes temporary backfill files, to store any transient data during query processing. The specified path must already exist. Only absolute paths are allowed. The default path is var/lib/couchbase/tmp within the Couchbase Server installation directory. + + + +|=== + + + + + From f3a4275a60c0f732c08679e338373f6459fab1c0 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Mon, 10 Aug 2026 16:22:58 +0530 Subject: [PATCH 2/8] Add Query Settings --- .../pages/manage-settings/query-settings.adoc | 214 ++++++++++++------ 1 file changed, 148 insertions(+), 66 deletions(-) diff --git a/modules/manage/pages/manage-settings/query-settings.adoc b/modules/manage/pages/manage-settings/query-settings.adoc index 886e3e8efe..736ae6b06d 100644 --- a/modules/manage/pages/manage-settings/query-settings.adoc +++ b/modules/manage/pages/manage-settings/query-settings.adoc @@ -1,70 +1,152 @@ -== Query -:description: You can configure the query settings for your cluster. -:page-topic-type: guide - += Query settings reference +:description: Available options on the Query settings page, including CURL() access, temporary disk usage, resource limits, logging, and transaction and optimizer settings. [abstract] {description} - -The Query tab lets you manage how queries run on your cluster. - -== Navigate to Query Settings - -To navigate to the Query Settings tab, follow these steps: - -. Log into the Couchbase Server Web Console. -. From the left navigation menu, click **Settings**. -. Click the **Query** tab. - -== Configuration Options - -The following table describes the settings available in the Query tab: - -[cols="1,1,1", options="header"] -|=== -| Setting | Description | Default Value - -| CURL() Function Access -| Set the URLs the `CURL()` function can access. - -* *Restricted*: Allows access to only URLS listed in *Allowed CURL URLs*. -* *Unrestricted*: The `CURL()` function can access any URL. - -| *Unrestricted* - -| Allowed CURL URLs -| Specify the URLs that the `CURL()` function can access when *CURL() Function Access* is set to *Restricted*. -You can specify multiple URL. - -To add a URL, click btn:[+]. - -To remove a URL, click btn:[-] next to the URL. - -| None - -| Disallowed CURL URLs - -| Specify the URLs that the `CURL()` function cannot access. -You can specify multiple URL. - -To add a URL, click btn:[+]. - -To remove a URL, click btn:[-] next to the URL. - -| None - -| Query Temp Disk Path - -| When a query has an extremely large corresponding index scan, the indexer buffers the results into a temporary directory. Since this method may cause high I/O and works differently on Windows, you can configure backfill settings for the SQL++ engine and its embedded GSI client. - -The *Query Temp Disk Path* field enables you to specify the path to which the indexer writes temporary backfill files, to store any transient data during query processing. The specified path must already exist. Only absolute paths are allowed. The default path is var/lib/couchbase/tmp within the Couchbase Server installation directory. - - - -|=== - - - - - +== Overview + +The Query settings page controls which network locations the `CURL()` function can reach, how the Query service uses disk, memory, and caching resources, and how it logs and optimizes query execution. +This page describes each option, what it controls, and its default value. + +== CURL() function access + +The `CURL()` function lets a {sqlpp} query make an HTTP request to an external endpoint. +Because the function can reach outside your cluster, two settings control where it can connect. + +*CURL() Function Access*:: +Sets whether `CURL()` can reach any URL, or only URLs that you allow. ++ +* *Restricted*: `CURL()` can access only the URLs listed in *Allowed CURL URLs*. +Use this option to limit the destinations that queries can call. +* *Unrestricted*: `CURL()` can access any URL. ++ +Default: `Unrestricted` + +*Allowed CURL URLs*:: +The URLs that `CURL()` can access when *CURL() Function Access* is set to *Restricted*. You can add multiple URLs. ++ +* To add a URL, click btn:[+]. +* To remove a URL, click btn:[-] next to it. ++ +Default: none + +*Disallowed CURL URLs*:: +The URLs that `CURL()` can never access, regardless of the *CURL() Function Access* setting. You can add multiple URLs. ++ +* To add a URL, click btn:[+]. +* To remove a URL, click btn:[-] next to it. ++ +Default: none + +== Temporary disk usage + +When a query's index scan returns more data than fits in memory, the indexer writes the excess to a temporary directory on disk. This process is called backfill. + +*Query Temp Disk Path*:: +The absolute path where the indexer writes temporary backfill files. The path must already exist on the node. ++ +Default: `/opt/couchbase/var/lib/couchbase/tmp` + +*Quota*:: +The maximum size, in mebibytes (MiB), of the temporary backfill files. ++ +* Set the value to `0` to disable backfill. +* Set the value to `-1` to allow unlimited backfill, up to the available disk space. ++ +Default: `5120` ++ +NOTE: A Global Secondary Index (GSI) doesn't perform backfill if *Quota* is `0` or lower. To enable backfill for GSIs, set *Quota* to a sufficiently large positive value, such as `102400`. + +== Resource limits + +These options bound how much memory, network buffering, and cached state a query can use. + +*Pipeline Batch*:: +The number of items the Query service batches together when it fetches data from the Data Service. ++ +Default: `16` + +*Pipeline Cap*:: +The maximum number of items the Query service buffers during a single fetch. ++ +Default: `512` + +*Scan Cap*:: +The maximum size, in items, of the buffered channel between the indexer client and the Query service during an index scan. ++ +Default: `512` + +*Timeout (ns)*:: +The maximum time, in nanoseconds, that a request can run before the Query service times it out. A value of `0` disables the timeout. ++ +Default: `0` + +*Prepared Limit*:: +The maximum number of prepared statements the Query service holds in its cache. ++ +Default: `16384` + +== Completed requests logging + +The Query service keeps a log of completed requests, called the completed requests catalog. These options control which requests it logs. + +*Completed Limit*:: +The maximum number of requests the Query service keeps in the completed requests catalog. ++ +Default: `4000` + +*Completed Threshold*:: +The minimum query duration, in milliseconds, for the Query service to log a completed query in the completed requests catalog. Queries that finish faster than this threshold aren't logged. ++ +Default: `1000` + +*Log Level*:: +The logging level for the Query service logger. ++ +Default: `Info` + +== Query execution tuning + +*Max Parallelism*:: +The maximum number of index partitions the Query service uses for parallel aggregation. ++ +Default: `1` + +*N1QL Feature Controller*:: +Enables or disables individual Query engine features. This value is a bitmask. ++ +Default: `76` ++ +NOTE: Don't change *N1QL Feature Controller* without guidance from Couchbase technical support. + +== Transactions + +*Transaction Timeout (duration)*:: +The maximum time, in milliseconds, a transaction can run before it times out. ++ +Default: `0ms` + +*Memory Quota (MB)*:: +The amount of memory, in megabytes, allocated to processing a query. ++ +Default: `0` + +== Query optimizer + +*Use Cost-Based Optimizer*:: +Sets whether the Query service uses the cost-based optimizer to plan queries. ++ +* Selected (default): the Query service uses the cost-based optimizer. +* Cleared: the Query service doesn't use the cost-based optimizer. + +*Use Replica*:: +Sets whether a query can read data from a replica vBucket when the active vBucket is unavailable. ++ +* *Unset*: Read from replica is controlled at the request level. +* *On*: Read from replica is enabled for all queries, but a request can still disable it. +* *Off*: Read from replica is disabled for all queries and can't be overridden at the request level. ++ +Default: `Unset` ++ +NOTE: Don't enable read from replica when you need consistent results. Only `SELECT` queries that aren't inside a transaction can read from a replica. Also, KV range scans can't start on a replica vBucket — if a query uses a sequential scan and a data node becomes unavailable, the query might return an error even when read from replica is enabled. From 50ec8f1c12e8259b150861425ab98486d0857f7d Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Tue, 11 Aug 2026 12:38:00 +0530 Subject: [PATCH 3/8] Add Settings --- .../pages/manage-settings/query-settings.adoc | 97 +++++++++++-------- 1 file changed, 55 insertions(+), 42 deletions(-) diff --git a/modules/manage/pages/manage-settings/query-settings.adoc b/modules/manage/pages/manage-settings/query-settings.adoc index 736ae6b06d..ff18dde9a3 100644 --- a/modules/manage/pages/manage-settings/query-settings.adoc +++ b/modules/manage/pages/manage-settings/query-settings.adoc @@ -1,124 +1,131 @@ = Query settings reference -:description: Available options on the Query settings page, including CURL() access, temporary disk usage, resource limits, logging, and transaction and optimizer settings. +:description: List of available options on the Query settings page, including CURL() access, temporary disk usage, resource limits, logging, and optimizer settings. [abstract] {description} == Overview -The Query settings page controls which network locations the `CURL()` function can reach, how the Query service uses disk, memory, and caching resources, and how it logs and optimizes query execution. -This page describes each option, what it controls, and its default value. +You can configure the Query Service using the menu:Settings[Query] tab on the Couchbase Server Web Console. -== CURL() function access +Use this tab to control the URLs the `CURL()` function can access, allocate disk and memory usage, and set query execution parameters. -The `CURL()` function lets a {sqlpp} query make an HTTP request to an external endpoint. -Because the function can reach outside your cluster, two settings control where it can connect. +== CURL() Function Access + +The `CURL()` function allows {sqlpp} queries to send HTTP requests to external endpoints. +To control which URLs the function can access, configure the following settings: *CURL() Function Access*:: -Sets whether `CURL()` can reach any URL, or only URLs that you allow. +Controls whether `CURL()` can reach any external URL or only specified URLs. + -* *Restricted*: `CURL()` can access only the URLs listed in *Allowed CURL URLs*. -Use this option to limit the destinations that queries can call. -* *Unrestricted*: `CURL()` can access any URL. +* *Restricted*: Limits access to only the URLs listed in *Allowed CURL URLs*. +* *Unrestricted*: Allows access to any URL. + Default: `Unrestricted` *Allowed CURL URLs*:: -The URLs that `CURL()` can access when *CURL() Function Access* is set to *Restricted*. You can add multiple URLs. +The URLs `CURL()` can access when *CURL() Function Access* is set to *Restricted*. + * To add a URL, click btn:[+]. +You can add multiple URLs. * To remove a URL, click btn:[-] next to it. + Default: none *Disallowed CURL URLs*:: -The URLs that `CURL()` can never access, regardless of the *CURL() Function Access* setting. You can add multiple URLs. +The URLs `CURL()` can never access, regardless of the *CURL() Function Access* setting. + * To add a URL, click btn:[+]. +You can add multiple URLs. * To remove a URL, click btn:[-] next to it. + Default: none -== Temporary disk usage +== Temporary Disk Usage -When a query's index scan returns more data than fits in memory, the indexer writes the excess to a temporary directory on disk. This process is called backfill. +When an index scan returns more data than fits in memory, the indexer writes the remaining data to a temporary directory on disk. *Query Temp Disk Path*:: -The absolute path where the indexer writes temporary backfill files. The path must already exist on the node. +The absolute path where the indexer writes temporary backfill files. +The path must already exist on the target node. + Default: `/opt/couchbase/var/lib/couchbase/tmp` *Quota*:: -The maximum size, in mebibytes (MiB), of the temporary backfill files. +The maximum size, in mebibytes (MiB), allowed for temporary backfill files. + -* Set the value to `0` to disable backfill. -* Set the value to `-1` to allow unlimited backfill, up to the available disk space. +* Set to `0` to disable backfill. +* Set to `-1` to allow unlimited backfill, up to the maximum available disk space. + Default: `5120` + -NOTE: A Global Secondary Index (GSI) doesn't perform backfill if *Quota* is `0` or lower. To enable backfill for GSIs, set *Quota* to a sufficiently large positive value, such as `102400`. +NOTE: A Global Secondary Index (GSI) does not perform backfill if *Quota* is `0` or lower. +To enable backfill for GSIs, set *Quota* to a sufficiently large positive value (for example,`102400`). -== Resource limits +== Resource Limits -These options bound how much memory, network buffering, and cached state a query can use. +Configure resource limits to control memory, network buffering, and cached state during query execution. *Pipeline Batch*:: -The number of items the Query service batches together when it fetches data from the Data Service. +The number of items the Query Service batches together when fetching data from the Data Service. + Default: `16` *Pipeline Cap*:: -The maximum number of items the Query service buffers during a single fetch. +The maximum number of items the Query Service buffers during a single fetch. + Default: `512` *Scan Cap*:: -The maximum size, in items, of the buffered channel between the indexer client and the Query service during an index scan. +The maximum size, in items, of the buffered channel between the indexer client and the Query Service during an index scan. + Default: `512` *Timeout (ns)*:: -The maximum time, in nanoseconds, that a request can run before the Query service times it out. A value of `0` disables the timeout. +The maximum time, in nanoseconds, a request can run before timing out. +Set to `0` to disable request timeouts. + Default: `0` *Prepared Limit*:: -The maximum number of prepared statements the Query service holds in its cache. +The maximum number of prepared statements the Query Service holds in its cache. + Default: `16384` -== Completed requests logging +== Completed Requests Logging -The Query service keeps a log of completed requests, called the completed requests catalog. These options control which requests it logs. +The Query Service maintains a log of completed requests. +Use the following options to control query logging: *Completed Limit*:: -The maximum number of requests the Query service keeps in the completed requests catalog. +The maximum number of requests retained in the completed requests catalog. + Default: `4000` *Completed Threshold*:: -The minimum query duration, in milliseconds, for the Query service to log a completed query in the completed requests catalog. Queries that finish faster than this threshold aren't logged. +The minimum query duration, in milliseconds, required for a completed request to be logged. +The Query Service omits queries that finish faster than this threshold. + Default: `1000` *Log Level*:: -The logging level for the Query service logger. +The logging level for the Query Service logger. + Default: `Info` -== Query execution tuning +== Query Execution *Max Parallelism*:: -The maximum number of index partitions the Query service uses for parallel aggregation. +The maximum number of index partitions the Query Service uses for parallel aggregation. + Default: `1` *N1QL Feature Controller*:: -Enables or disables individual Query engine features. This value is a bitmask. +Enables or disables individual query engine features using a bitmask value. + Default: `76` + -NOTE: Don't change *N1QL Feature Controller* without guidance from Couchbase technical support. +NOTE: Do not change *N1QL Feature Controller* without guidance from Couchbase technical support. == Transactions @@ -132,21 +139,27 @@ The amount of memory, in megabytes, allocated to processing a query. + Default: `0` -== Query optimizer +== Query Optimizer + +Controls how the Query Service plans and executes queries. *Use Cost-Based Optimizer*:: -Sets whether the Query service uses the cost-based optimizer to plan queries. +Determines whether the Query Service uses the cost-based optimizer to generate execution plans. + -* Selected (default): the Query service uses the cost-based optimizer. -* Cleared: the Query service doesn't use the cost-based optimizer. +* Selected (default): Uses the cost-based optimizer. +* Cleared: Does not use the cost-based optimizer. + +== Read from Replica *Use Replica*:: -Sets whether a query can read data from a replica vBucket when the active vBucket is unavailable. +Controls whether queries can fall back to reading data from replica buckets when the active bucket is unavailable. + * *Unset*: Read from replica is controlled at the request level. * *On*: Read from replica is enabled for all queries, but a request can still disable it. -* *Off*: Read from replica is disabled for all queries and can't be overridden at the request level. +* *Off*: Read from replica is disabled for all queries and cannot be overridden at the request level. + Default: `Unset` + -NOTE: Don't enable read from replica when you need consistent results. Only `SELECT` queries that aren't inside a transaction can read from a replica. Also, KV range scans can't start on a replica vBucket — if a query uses a sequential scan and a data node becomes unavailable, the query might return an error even when read from replica is enabled. +NOTE: Do not enable read from replica when you need consistent results. +Only `SELECT` queries that aren't inside a transaction can read from a replica. +In addition, KV range scans can't start on a replica vBucket — if a query uses a sequential scan and a data node becomes unavailable, the query might return an error even when read from replica is enabled. From a38b96490914d633c3d4499fb8d7345c7da70f42 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Tue, 11 Aug 2026 15:24:37 +0530 Subject: [PATCH 4/8] Add Settings --- .../pages/manage-settings/query-settings.adoc | 245 ++++++++++-------- 1 file changed, 134 insertions(+), 111 deletions(-) diff --git a/modules/manage/pages/manage-settings/query-settings.adoc b/modules/manage/pages/manage-settings/query-settings.adoc index ff18dde9a3..bfb5b249b0 100644 --- a/modules/manage/pages/manage-settings/query-settings.adoc +++ b/modules/manage/pages/manage-settings/query-settings.adoc @@ -1,165 +1,188 @@ = Query settings reference -:description: List of available options on the Query settings page, including CURL() access, temporary disk usage, resource limits, logging, and optimizer settings. +:description: Configure Query Service settings to manage CURL() access, disk and memory quotas, logging, and optimizer settings. [abstract] {description} == Overview -You can configure the Query Service using the menu:Settings[Query] tab on the Couchbase Server Web Console. +You can configure the Query Service for your cluster using the menu:Settings[] tab on the Couchbase Server Web Console. -Use this tab to control the URLs the `CURL()` function can access, allocate disk and memory usage, and set query execution parameters. +Use these settings to control CURL() endpoint access, set temporary disk usage limits, manage resources, and set query execution and logging parameters. -== CURL() Function Access +To configure the Query Service settings: + +. In the Couchbase Server Web Console, click menu:Settings[]. +. Select the *Query* tab. +. Update the required settings and click btn:[Save]. + +== CURL Function Access The `CURL()` function allows {sqlpp} queries to send HTTP requests to external endpoints. -To control which URLs the function can access, configure the following settings: -*CURL() Function Access*:: -Controls whether `CURL()` can reach any external URL or only specified URLs. -+ +[cols="1,2,1",options="header"] +|=== +| Setting | Description | Default Value + +| *CURL() Function Access* +a| Controls whether `CURL()` can access any external URL or only specified URLs. + +Select one of the following options: + * *Restricted*: Limits access to only the URLs listed in *Allowed CURL URLs*. * *Unrestricted*: Allows access to any URL. -+ -Default: `Unrestricted` +| Unrestricted + +| *Allowed CURL URLs* +a| The URLs `CURL()` can access when *CURL() Function Access* is set to *Restricted*. -*Allowed CURL URLs*:: -The URLs `CURL()` can access when *CURL() Function Access* is set to *Restricted*. -+ * To add a URL, click btn:[+]. You can add multiple URLs. * To remove a URL, click btn:[-] next to it. -+ -Default: none +| None + +| *Disallowed CURL URLs* +a| The URLs `CURL()` can never access, regardless of the *CURL() Function Access* setting. -*Disallowed CURL URLs*:: -The URLs `CURL()` can never access, regardless of the *CURL() Function Access* setting. -+ * To add a URL, click btn:[+]. You can add multiple URLs. * To remove a URL, click btn:[-] next to it. -+ -Default: none +| None +|=== == Temporary Disk Usage -When an index scan returns more data than fits in memory, the indexer writes the remaining data to a temporary directory on disk. +When an index scan returns more data than fits in memory, the indexer writes the remaining data to temporary backfill files on disk. + +[cols="1,2,1",options="header"] +|=== +| Setting | Description | Default Value -*Query Temp Disk Path*:: -The absolute path where the indexer writes temporary backfill files. +| *Query Temp Disk Path* +| The absolute path where the indexer writes temporary backfill files. The path must already exist on the target node. -+ -Default: `/opt/couchbase/var/lib/couchbase/tmp` - -*Quota*:: -The maximum size, in mebibytes (MiB), allowed for temporary backfill files. -+ -* Set to `0` to disable backfill. -* Set to `-1` to allow unlimited backfill, up to the maximum available disk space. -+ -Default: `5120` -+ -NOTE: A Global Secondary Index (GSI) does not perform backfill if *Quota* is `0` or lower. -To enable backfill for GSIs, set *Quota* to a sufficiently large positive value (for example,`102400`). +|`/opt/couchbase/var/lib/couchbase/tmp` + +| *Quota* +a| The maximum size, in mebibytes (MiB), allowed for temporary backfill files. + +* To turn off backfill, set the value to `0`. +* To allow unlimited backfill, up to the maximum available disk space, set the value to `-1`. +|`5120` + +|=== + +NOTE: Global Secondary Indexes (GSIs) do not perform backfill operations if *Quota* is set to `0` or lower. +To enable backfill for GSIs, set *Quota* to a large positive value (such as `102400`). == Resource Limits -Configure resource limits to control memory, network buffering, and cached state during query execution. +Configure parameters to manage memory, execution limits, and query timeouts. + +[cols="1,2,1",options="header"] +|=== +| Setting | Description | Default Value + +| *Pipeline Batch* +| Number of items the Query Service batches together when fetching data from the Data Service. +| `16` + +| *Pipeline Cap* +| Maximum number of items the Query Service buffers during a single fetch. +| `512` + +| *Scan Cap* +| Maximum size, in items, of the buffered channel between the indexer client and the Query Service during an index scan. +| `512` + +| *Timeout (ns)* +| Maximum request execution time in nanoseconds before timing out. -*Pipeline Batch*:: -The number of items the Query Service batches together when fetching data from the Data Service. -+ -Default: `16` +To turn off timeouts, set the value to `0`. +| `0` -*Pipeline Cap*:: -The maximum number of items the Query Service buffers during a single fetch. -+ -Default: `512` +| *Prepared Limit* +| Maximum number of prepared statements retained in the Query Service cache. +| `16384` -*Scan Cap*:: -The maximum size, in items, of the buffered channel between the indexer client and the Query Service during an index scan. -+ -Default: `512` +| *Max Parallelism* +| Maximum number of index partitions the Query Service uses for parallel aggregation. +| `1` -*Timeout (ns)*:: -The maximum time, in nanoseconds, a request can run before timing out. -Set to `0` to disable request timeouts. -+ -Default: `0` +| *N1QL Feature Controller* +| Bitmask value used to enable or disable specific query engine features and controls. -*Prepared Limit*:: -The maximum number of prepared statements the Query Service holds in its cache. -+ -Default: `16384` +WARNING: Do not change *N1QL Feature Controller* without guidance from Couchbase technical support. +| `76` -== Completed Requests Logging +| *Transaction Timeout (duration)*:: +| Maximum duration (in milliseconds) allowed for a transaction before timing out. +| `0ms` + +| *Memory Quota (MB)* +| Maximum amount of memory (in megabytes) allocated to processing a query. +| `0` +|=== + +== Logging and Completed Requests The Query Service maintains a log of completed requests. -Use the following options to control query logging: +Use the following options to control query logging. + +[cols="1,2,1",options="header"] +|=== +| Setting | Description | Default Value -*Completed Limit*:: -The maximum number of requests retained in the completed requests catalog. -+ -Default: `4000` +| *Completed Limit* +| Maximum number of requests retained in the completed requests catalog. +| `4000` -*Completed Threshold*:: -The minimum query duration, in milliseconds, required for a completed request to be logged. +| *Completed Threshold* +| Minimum query duration (in milliseconds) required for a completed request to be logged. The Query Service omits queries that finish faster than this threshold. -+ -Default: `1000` +| `1000` -*Log Level*:: -The logging level for the Query Service logger. -+ -Default: `Info` +| *Log Level* +| The logging level for the Query Service logger. +| `Info` +|=== -== Query Execution +== Query Optimization and Planning -*Max Parallelism*:: -The maximum number of index partitions the Query Service uses for parallel aggregation. -+ -Default: `1` +Configure rules for cost optimizer behavior and replica usage. -*N1QL Feature Controller*:: -Enables or disables individual query engine features using a bitmask value. -+ -Default: `76` -+ -NOTE: Do not change *N1QL Feature Controller* without guidance from Couchbase technical support. +[cols="1,2,1",options="header"] +|=== +| Setting | Description | Default Value -== Transactions +| *Use Cost-Based Optimizer* +| Determines whether to use the xref:n1ql:n1ql-language-reference/cost-based-optimizer.adoc[cost-based optimizer] for execution planning. -*Transaction Timeout (duration)*:: -The maximum time, in milliseconds, a transaction can run before it times out. -+ -Default: `0ms` +* To enable the optimizer, select the checkbox. +* To disable the optimizer, clear the checkbox. -*Memory Quota (MB)*:: -The amount of memory, in megabytes, allocated to processing a query. -+ -Default: `0` +| Selected/Enabled +|=== -== Query Optimizer +== Replica Usage -Controls how the Query Service plans and executes queries. +Configure read options for high availability and failover scenarios. -*Use Cost-Based Optimizer*:: -Determines whether the Query Service uses the cost-based optimizer to generate execution plans. -+ -* Selected (default): Uses the cost-based optimizer. -* Cleared: Does not use the cost-based optimizer. +[cols="1,2,1",options="header"] +|=== +| Setting | Description | Default Value -== Read from Replica +| *Use Replica* +a| Controls whether queries can fall back to reading data from replica buckets when the active bucket is unavailable. -*Use Replica*:: -Controls whether queries can fall back to reading data from replica buckets when the active bucket is unavailable. -+ * *Unset*: Read from replica is controlled at the request level. -* *On*: Read from replica is enabled for all queries, but a request can still disable it. -* *Off*: Read from replica is disabled for all queries and cannot be overridden at the request level. -+ -Default: `Unset` -+ -NOTE: Do not enable read from replica when you need consistent results. -Only `SELECT` queries that aren't inside a transaction can read from a replica. -In addition, KV range scans can't start on a replica vBucket — if a query uses a sequential scan and a data node becomes unavailable, the query might return an error even when read from replica is enabled. +* *On*: Read from replica is enabled for all queries, but a request can still turn it off. +* *Off*: Read from replica is turned off for all queries and cannot be overridden at the request level. + +NOTE: Do not enable *Use Replica* if your workload requires consistent results. +Only `SELECT` outside of a transaction can read from a replica. +In addition, KV range scans cannot start on a replica vBucket. +If a query uses a sequential scan and a data node becomes unavailable, the query might return an error even when read from replica is enabled. + +|`Unset` +|=== From 890a6dabf25f3344717dc3d139ce3dfe990eea9d Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Tue, 11 Aug 2026 16:18:40 +0530 Subject: [PATCH 5/8] Change file name --- modules/ROOT/nav.adoc | 2 +- .../{query-settings.adoc => query-ui-settings.adoc} | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) rename modules/manage/pages/manage-settings/{query-settings.adoc => query-ui-settings.adoc} (96%) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index cdd9c62d35..ab859df693 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -134,7 +134,7 @@ include::third-party:partial$nav.adoc[] * xref:manage:manage-logging/manage-logging.adoc[Manage Logging] * xref:manage:manage-settings/manage-settings.adoc[Manage Settings] ** xref:manage:manage-settings/general-settings.adoc[General] - ** xref:manage:manage-settings/query-settings.adoc[Query] + ** xref:manage:manage-settings/query-ui-settings.adoc[Query] ** xref:manage:manage-settings/configure-compact-settings.adoc[Auto-Compaction] ** xref:manage:manage-settings/configure-alerts.adoc[Alerts] ** xref:manage:manage-settings/install-sample-buckets.adoc[Sample Buckets] diff --git a/modules/manage/pages/manage-settings/query-settings.adoc b/modules/manage/pages/manage-settings/query-ui-settings.adoc similarity index 96% rename from modules/manage/pages/manage-settings/query-settings.adoc rename to modules/manage/pages/manage-settings/query-ui-settings.adoc index bfb5b249b0..adce751e71 100644 --- a/modules/manage/pages/manage-settings/query-settings.adoc +++ b/modules/manage/pages/manage-settings/query-ui-settings.adoc @@ -27,7 +27,7 @@ The `CURL()` function allows {sqlpp} queries to send HTTP requests to external e | *CURL() Function Access* a| Controls whether `CURL()` can access any external URL or only specified URLs. -Select one of the following options: +Select 1 of the following options: * *Restricted*: Limits access to only the URLs listed in *Allowed CURL URLs*. * *Unrestricted*: Allows access to any URL. @@ -158,10 +158,10 @@ Configure rules for cost optimizer behavior and replica usage. | *Use Cost-Based Optimizer* | Determines whether to use the xref:n1ql:n1ql-language-reference/cost-based-optimizer.adoc[cost-based optimizer] for execution planning. -* To enable the optimizer, select the checkbox. -* To disable the optimizer, clear the checkbox. +* To enable the optimizer, select *Use Cost-Based Optimizer*. +* To disable the optimizer, clear *Use Cost-Based Optimizer*. -| Selected/Enabled +| Selected (Enabled) |=== == Replica Usage From a6281267a4924e6f5d673c6519c0c50a2df9bb7c Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Tue, 11 Aug 2026 16:24:31 +0530 Subject: [PATCH 6/8] Add Settings --- modules/manage/pages/manage-settings/query-ui-settings.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/manage/pages/manage-settings/query-ui-settings.adoc b/modules/manage/pages/manage-settings/query-ui-settings.adoc index adce751e71..3b0a5f9af8 100644 --- a/modules/manage/pages/manage-settings/query-ui-settings.adoc +++ b/modules/manage/pages/manage-settings/query-ui-settings.adoc @@ -156,7 +156,7 @@ Configure rules for cost optimizer behavior and replica usage. | Setting | Description | Default Value | *Use Cost-Based Optimizer* -| Determines whether to use the xref:n1ql:n1ql-language-reference/cost-based-optimizer.adoc[cost-based optimizer] for execution planning. +a| Determines whether to use the xref:n1ql:n1ql-language-reference/cost-based-optimizer.adoc[cost-based optimizer] for execution planning. * To enable the optimizer, select *Use Cost-Based Optimizer*. * To disable the optimizer, clear *Use Cost-Based Optimizer*. @@ -178,11 +178,11 @@ a| Controls whether queries can fall back to reading data from replica buckets w * *Unset*: Read from replica is controlled at the request level. * *On*: Read from replica is enabled for all queries, but a request can still turn it off. * *Off*: Read from replica is turned off for all queries and cannot be overridden at the request level. +|`Unset` +|=== NOTE: Do not enable *Use Replica* if your workload requires consistent results. Only `SELECT` outside of a transaction can read from a replica. In addition, KV range scans cannot start on a replica vBucket. If a query uses a sequential scan and a data node becomes unavailable, the query might return an error even when read from replica is enabled. -|`Unset` -|=== From 1aecda77f7c9beb81934a86253619bc0ad481332 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Tue, 11 Aug 2026 16:31:06 +0530 Subject: [PATCH 7/8] Minor edit --- modules/manage/pages/manage-settings/query-ui-settings.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/manage-settings/query-ui-settings.adoc b/modules/manage/pages/manage-settings/query-ui-settings.adoc index 3b0a5f9af8..2da4b314b3 100644 --- a/modules/manage/pages/manage-settings/query-ui-settings.adoc +++ b/modules/manage/pages/manage-settings/query-ui-settings.adoc @@ -1,4 +1,4 @@ -= Query settings reference += Query :description: Configure Query Service settings to manage CURL() access, disk and memory quotas, logging, and optimizer settings. [abstract] From e9624db77795f08f0752d0c2a4ab9c12935caf72 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Tue, 11 Aug 2026 16:34:32 +0530 Subject: [PATCH 8/8] Minor edit --- .../manage-settings/query-ui-settings.adoc | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/modules/manage/pages/manage-settings/query-ui-settings.adoc b/modules/manage/pages/manage-settings/query-ui-settings.adoc index 2da4b314b3..83130d9474 100644 --- a/modules/manage/pages/manage-settings/query-ui-settings.adoc +++ b/modules/manage/pages/manage-settings/query-ui-settings.adoc @@ -147,23 +147,6 @@ The Query Service omits queries that finish faster than this threshold. | `Info` |=== -== Query Optimization and Planning - -Configure rules for cost optimizer behavior and replica usage. - -[cols="1,2,1",options="header"] -|=== -| Setting | Description | Default Value - -| *Use Cost-Based Optimizer* -a| Determines whether to use the xref:n1ql:n1ql-language-reference/cost-based-optimizer.adoc[cost-based optimizer] for execution planning. - -* To enable the optimizer, select *Use Cost-Based Optimizer*. -* To disable the optimizer, clear *Use Cost-Based Optimizer*. - -| Selected (Enabled) -|=== - == Replica Usage Configure read options for high availability and failover scenarios. @@ -186,3 +169,20 @@ Only `SELECT` outside of a transaction can read from a replica. In addition, KV range scans cannot start on a replica vBucket. If a query uses a sequential scan and a data node becomes unavailable, the query might return an error even when read from replica is enabled. +== Query Optimization + +Configure rules for cost optimizer behavior and replica usage. + +[cols="1,2,1",options="header"] +|=== +| Setting | Description | Default Value + +| *Use Cost-Based Optimizer* +a| Determines whether to use the xref:n1ql:n1ql-language-reference/cost-based-optimizer.adoc[cost-based optimizer] for execution planning. + +* To enable the optimizer, select *Use Cost-Based Optimizer*. +* To disable the optimizer, clear *Use Cost-Based Optimizer*. + +| Selected (Enabled) +|=== +