diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 19c55f1ff8..ab859df693 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-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/general-settings.adoc b/modules/manage/pages/manage-settings/general-settings.adoc index cd5b2601f4..10599fe677 100644 --- a/modules/manage/pages/manage-settings/general-settings.adoc +++ b/modules/manage/pages/manage-settings/general-settings.adoc @@ -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 @@ -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] -=== 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 @@ -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 <>, 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 @@ -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 @@ -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 diff --git a/modules/manage/pages/manage-settings/query-ui-settings.adoc b/modules/manage/pages/manage-settings/query-ui-settings.adoc new file mode 100644 index 0000000000..ddecd5fbb8 --- /dev/null +++ b/modules/manage/pages/manage-settings/query-ui-settings.adoc @@ -0,0 +1,301 @@ += Query +:description: Configure Query Service settings to manage CURL() access, disk and memory quotas, logging, and optimizer settings. +:page-topic-type: guide +:page-toclevels: 2 + +[abstract] +{description} + +== Overview + +You can configure the Query Service for your cluster using the menu:Settings[] tab on the Couchbase Server Web Console. + +Use these settings to control CURL() endpoint access, set temporary disk usage limits, manage resources, and set query execution and logging parameters. + +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. + +[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 1 of the following options: + +* *Restricted*: Limits access to only the URLs listed in *Allowed CURL URLs*. +* *Unrestricted*: Allows access to any URL. +| Unrestricted + +| *Allowed CURL URLs* +a| 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. +| None + +| *Disallowed CURL URLs* +a| 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. +| None +|=== + +== Temporary Disk Usage + +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. +The path must already exist on the target node. +|`/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 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. + +To turn off timeouts, set the value to `0`. +| `0` + +| *Prepared Limit* +| Maximum number of prepared statements retained in the Query Service cache. +| `16384` + +| *Max Parallelism* +| Maximum number of index partitions the Query Service uses for parallel aggregation. +| `1` + +| *N1QL Feature Controller* +| Bitmask value used to enable or disable specific query engine features and controls. + +WARNING: Do not change *N1QL Feature Controller* without guidance from Couchbase technical support. +| `76` + +| *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. + +[cols="1,2,1",options="header"] +|=== +| Setting | Description | Default Value + +| *Completed Limit* +| Maximum number of requests retained in the completed requests catalog. +| `4000` + +| *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. +| `1000` + +| *Log Level* +| The logging level for the Query Service logger. +| `Info` +|=== + +== Replica Usage + +Configure read options for high availability and failover scenarios. + +[cols="1,2,1",options="header"] +|=== +| Setting | Description | Default Value + +| *Use Replica* +a| 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 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. + +== 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) +|=== + +== 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,sh] +---- +/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,sh] +---- +/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 more information about the cluster-level query settings, see xref:n1ql:n1ql-manage/query-settings.adoc[Settings and Parameters]. + +== Query Settings via REST + +To set the directory for temporary backfill data, and establish its size-limit, use the `/settings/querySettings` method. + +[source,sh] +---- +curl -v -X POST -u Administrator:password \ +http://localhost:8091/settings/querySettings \ +-d 'queryTmpSpaceDir=/tmp' \ +-d 'queryTmpSpaceSize=2048' +---- + +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] +---- +{ + "queryTmpSpaceDir": "/tmp", + "queryTmpSpaceSize": 2048, + "queryPipelineBatch": 16, + "queryPipelineCap": 512, + "queryScanCap": 512, + "queryTimeout": 0, + "queryPreparedLimit": 16384, + "queryCompletedLimit": 4000, + "queryCompletedThreshold": 1000, + "queryLogLevel": "info", + "queryMaxParallelism": 1, + "queryTxTimeout": "0ms", + "queryMemoryQuota": 0, + "queryUseCBO": true, + "queryCleanupClientAttempts": true, + "queryCleanupLostAttempts": true, + "queryCleanupWindow": "60s", + "queryNumAtrs": 1024, + "queryNodeQuota": 0, + "queryUseReplica": "unset", + "queryNodeQuotaValPercent": 67, + "queryNumCpus": 0, + "queryCompletedMaxPlanSize": 262144, + "queryN1QLFeatCtrl": 76, + "queryCurlWhitelist": { + "all_access": false + } +} +---- + +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,sh] +---- +curl -v -X POST -u Administrator:password \ +http://localhost:8091/settings/querySettings/curlWhitelist \ +-d '{"all_access": false, + "allowed_urls": ["https://company1.com"], + "disallowed_urls": ["https://company2.com"]}' +---- + +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] +---- +{ + "all_access": false, + "allowed_urls": [ + "https://company1.com" + ], + "disallowed_urls": [ + "https://company2.com" + ] +} +---- + +For more information, see xref:n1ql-rest-settings:index.adoc[]. \ No newline at end of file