Skip to content

[DOC-14507] Create a new page for Query Settings #4145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rakhi-prathap wants to merge 12 commits into
base: release/8.1
Choose a base branch
from
+303 −162
Open

[DOC-14507] Create a new page for Query Settings #4145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
292130e
Update content
rakhi-prathap Aug 3, 2026
f3a4275
Add Query Settings
rakhi-prathap Aug 10, 2026
50ec8f1
Add Settings
rakhi-prathap Aug 11, 2026
a38b964
Add Settings
rakhi-prathap Aug 11, 2026
890a6da
Change file name
rakhi-prathap Aug 11, 2026
a628126
Add Settings
rakhi-prathap Aug 11, 2026
1aecda7
Minor edit
rakhi-prathap Aug 11, 2026
e9624db
Minor edit
rakhi-prathap Aug 11, 2026
9e70162
Update General Settings
rakhi-prathap Aug 17, 2026
37149f4
Add REST API examples
rakhi-prathap Aug 17, 2026
93aa55d
Add REST API examples
rakhi-prathap Aug 17, 2026
d543f0c
Adding a few page attributes
rakhi-prathap Aug 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions modules/ROOT/nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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-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]
Expand Down
163 changes: 1 addition & 162 deletions modules/manage/pages/manage-settings/general-settings.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
= General
:description: pass:q[_General_ settings allow configuration of _cluster name_, _memory quotas_, _storage modes_, and _node availability_ for the cluster; and of _advanced settings_ for the Index and Query Services.]
:description: pass:q[_General_ settings allow configuration of _cluster name_, _memory quotas_, _storage modes_, and _node availability_ for the cluster; and of _advanced settings_ for the Index Service.]
:page-aliases: settings:cluster-settings, settings:change-failover-settings, manage:manage-settings/cluster-settings, manage:manage-settings/change-failover-settings, manage:manage-settings/update-notification, n1ql:n1ql-language-reference/backfill, settings:backfill
:keywords: backfill
:imagesdir: ../../assets/images
Expand Down Expand Up @@ -247,93 +247,6 @@ For best performance, benchmark different settings and choose the one that meets

See xref:learn:buckets-memory-and-storage/storage-settings.adoc#threading[Threading] for more information about reader and writer threads.

[#query-settings]

@rakhi-prathap rakhi-prathap Aug 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This may break existing links to this anchor/topic header.
So I'm wondering if adding a :page-alias on the new page help?

(Likewise for other sections that I've deleted from General Settings.)

=== Query Settings

Left-clicking on *Advanced Query Settings* displays interactive fields with which you can configure the Query Service.
The top section of the panel appears as follows:

image::manage-settings/query-settings-top.png["The top half of the Query Settings panel",548,align=center]

Under *CURL() Function Access*, specify either *Unrestricted* or *Restricted*, to determine which URLs the CURL() function can access.

* If you specify *Unrestricted* (the default), the CURL() function can access all URLs.

* If you specify *Restricted*, the UI expands, to display configurable fields into which you can enter the allowed and disallowed URLs.

(((backfill)))
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 {sqlpp} 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.

* The *Quota* field enables you to specify the maximum size of temporary backfill files, in megabytes.
Setting the size to `0` disables backfill.
Setting the size to `-1` means the size is unlimited.
The maximum size is limited only by the available disk space.
+
NOTE: While queries support unlimited backfill when the quota is `-1`, GSIs do not perform backfill if the quota is `0` or less.
To enable backfill for GSIs, configure the quota to a sufficiently large positive value, such as `102400` or higher.
You can set this value higher than the available disk space to effectively allow unlimited backfill.
However, the actual usage remains within the limits of the available disk space.

Additional Query settings are provided in the lower section of the panel:

image::manage-settings/query-settings-bottom.png["The bottom half of the Query Settings panel",548,align=center]

// NOTE: The N1QL Feature Controller still contains the word N1QL in the UI

* *Pipeline Batch*: The number of items that can be batched for fetches from the Data Service.

* *Pipeline Cap*: The maximum number of items that can be buffered in a fetch.

* *Scan Cap*: The maximum buffered channel size between the indexer client and the Query Service, for index scans.

* *Timeout*: The maximum time (in nanoseconds) to spend on a request before timing out.

* *Prepared Limit*: The maximum number of prepared statements to be held in the cache.

* *Completed Limit*: The number of requests to be logged in the completed requests catalog.

* *Completed Threshold*: The completed-query duration (in milliseconds) beyond which the query is logged in the completed requests catalog.

* *Log Level*: The log level used in the logger.

* *Max Parallelism*: The maximum number of index partitions for parallel aggregation-computing.

* *N1QL Feature Controller*: Enables or disables features in the Query engine.
+
WARNING: Do not change the *N1QL Feature Controller* setting without guidance from technical support.

* *Transaction Timeout*: The number of milliseconds to elapse before a transaction times out.

* *Memory Quota*: The amount of memory, in megabytes, allocated to the processing of a query.

* *Use Cost-Based Optimizer*: when checked (as it is by default), specifies that the cost-based optimizer is used for queries: when the checkbox is unchecked, the optimizer is _not_ used.

* *Use Replica*: specifies whether a query can fetch data from a replica vBucket if active vBuckets are inaccessible.
The possible values are:

** *Unset* -- read from replica is enabled or disabled at request level.

** *On* -- read from replica is enabled for all queries, but can be disabled at request level.

** *Off* -- read from replica is disabled for all queries and cannot be overridden at request level.

+
--
Do not enable read from replica when you require consistent results.
Only SELECT queries that are not within a transaction can read from replica.

Note that KV range scans cannot currently be started on a replica vBucket.
If a query uses sequential scan and a data node becomes unavailable, the query might return an error, even if read from replica is enabled for the request.
--

For additional details on all the Query settings in the lower section of the panel, refer to xref:n1ql:n1ql-manage/query-settings.adoc[].

[#index-storage-mode]
=== Index Storage Mode

Expand Down Expand Up @@ -428,9 +341,6 @@ Alternatively, cancel recently entered values, and thereby reset to previous val
== Configure General Settings with the CLI

To configure _name and memory_, _index storage_, and _auto-failover_ via CLI, use the appropriate CLI command; as described below.
Note that no CLI support is provided for configuring _query settings_.
As an alternative, see <<configure-general-settings-with-the-rest-api,Configure General Settings with the REST API>>, below.
Additionally, for information on URL access lists via the {sqlpp} `CURL()` function, see xref:n1ql:n1ql-language-reference/curl.adoc[CURL Function].

[#name-and-memory-settings-via-cli]
=== Name and Memory Settings via CLI
Expand Down Expand Up @@ -553,37 +463,6 @@ SUCCESS: Auto-failover settings modified

For a detailed description of auto-failover settings, policy, and constraints, see xref:learn:clusters-and-availability/automatic-failover.adoc[Automatic Failover].

[#query-settings-via-cli]
=== Query Settings via CLI

You can set all of the cluster-level query settings, except for the CURL access control settings, using the xref:cli:cbcli/couchbase-cli-setting-query.adoc[setting-query] command.

To get the current cluster-level query settings, use the `--get` option:

[source,shell]
----
/opt/couchbase/bin/couchbase-cli setting-query \
-c 10.143.192.101:8091 \
-u Administrator \
-p password \
--get
----

To set cluster-level query settings, for example the log level and the maximum parallelism, use the `--set` option:

[source,shell]
----
/opt/couchbase/bin/couchbase-cli setting-query \
-c 10.143.192.101:8091 \
-u Administrator \
-p password \
--set \
--log-level debug \
--max-parallelism 4
----

For additional details on the cluster-level query settings, refer to xref:n1ql:n1ql-manage/query-settings.adoc[Settings and Parameters].

[#rebalance-settings-via-cli]
=== Rebalance Settings via CLI

Expand Down Expand Up @@ -828,46 +707,6 @@ If successful, the call returns an object whose values confirm the settings that
See xref:learn:buckets-memory-and-storage/storage.adoc#threading[Threading] for an overview of reader and writer threads.
Also see the REST API reference page, xref:rest-api:rest-reader-writer-thread-config.adoc[].

[#query-settings-via-rest]
=== Query Settings via REST

To set the directory for temporary backfill data, and establish its size-limit, use the `/settings/querySettings` method.

[source,shell]
----
include::n1ql-rest-settings:example$query-settings-post-settings.sh[]
----

This specifies that the directory for temporary backfill data should be `/tmp`; and that the maximum size should be 2048 megabytes.

If successful, this call returns a JSON document featuring all the current query-related settings, including access-control:

[source,json]
----
include::n1ql-rest-settings:example$query-settings-post-settings.json[]
----

The document's values indicate that the specified values for directory and size have been established; and that the current setting for access-control restricts access to all, with no exceptions.

To specify particular URLs as allowed and disallowed, use the `/settings/querySettings/curlWhitelist` method:

[source,shell]
----
include::n1ql-rest-settings:example$query-settings-post-access.sh[]
----

A JSON document is specified as the payload for the method.
The document's values indicate that `+https://company1.com+` is allowed, and `+https://company2.com+` is disallowed.

If successful, the call returns a JSON document that confirms the modified settings:

[source,json]
----
include::n1ql-rest-settings:example$query-settings-post-access.json[]
----

For additional information, refer to xref:n1ql-rest-settings:index.adoc[].

[#rebalance-settings-via-rest]
=== Rebalance Settings via REST

Expand Down
Loading