Query Settings REST API
Overview
The Query Settings REST API is provided by the Query service. This API enables you to view or specify cluster-level Query settings.
The API schemes and host URLs are as follows:
-
https://node:18091/ (for secure access)
where node
is the host name or IP address of a node running the Query service.
Paths
Table of Contents
Retrieve Cluster-Level Query Settings
GET /settings/querySettings
Example HTTP request
The example below gets the current cluster-level query settings.
curl -v -u Administrator:password \
http://localhost:8091/settings/querySettings
Example HTTP response
{
"queryTmpSpaceDir": "/opt/couchbase/var/lib/couchbase/tmp",
"queryTmpSpaceSize": 5120,
"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
}
}
Update Cluster-Level Query Settings
POST /settings/querySettings
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body |
Settings |
An object specifying cluster-level query settings. |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An object giving cluster-level query settings, including the latest changes. |
|
400 |
Returns an error message if a parameter or value is incorrect. |
object |
Example HTTP request
The example below changes the temp file directory to /tmp
and the temp file size to 2048 MB.
curl -v -X POST -u Administrator:password \
http://localhost:8091/settings/querySettings \
-d 'queryTmpSpaceDir=/tmp' \
-d 'queryTmpSpaceSize=2048'
Example HTTP response
{
"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
}
}
Retrieve CURL Access List
GET /settings/querySettings/curlWhitelist
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An object determining which URLs may be accessed by the |
Update CURL Access List
POST /settings/querySettings/curlWhitelist
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body |
Settings |
An object determining which URLs may be accessed by the |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An object determining which URLs may be accessed by the |
|
400 |
Returns an error message if a parameter or value is incorrect. |
object |
Example HTTP request
The example below specifies that https://company1.com
is allowed, and https://company2.com
is disallowed.
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"]}'
Definitions
Table of Contents
Settings
Name | Description | Schema | ||
---|---|---|---|---|
queryCleanupClientAttempts |
When enabled, the Query service preferentially aims to clean up just transactions that it has created, leaving transactions for the distributed cleanup process only when it is forced to. The node-level |
boolean |
||
queryCleanupLostAttempts |
When enabled, the Query service takes part in the distributed cleanup process, and cleans up expired transactions created by any client. The node-level |
boolean |
||
queryCleanupWindow |
Specifies how frequently the Query service checks its subset of active transaction records for cleanup. Decreasing this setting causes expiration transactions to be found more swiftly, with the tradeoff of increasing the number of reads per second used for the scanning process. The value for this setting is a string.
Its format includes an amount and a mandatory unit, e.g.
The node-level |
string (duration) |
||
queryCompletedLimit |
Sets the number of requests to be logged in the completed requests catalog. As new completed requests are added, old ones are removed. Increase this when the completed request keyspace is not big enough to track the slow requests, such as when you want a larger sample of slow requests. Refer to Configure the Completed Requests for more information and examples. The node-level |
integer (int32) |
||
queryCompletedMaxPlanSize |
A plan size in bytes. Limits the size of query execution plans that can be logged in the completed requests catalog. Values larger than the maximum limit are silently treated as the maximum limit. Queries with plans larger than this are not logged. You must obtain execution plans for such queries via profiling or using the EXPLAIN statement. Refer to Configure the Completed Requests for more information. The node-level |
integer (int32) |
||
queryCompletedThreshold |
A duration in milliseconds. All completed queries lasting longer than this threshold are logged in the completed requests catalog. Specify Refer to Configure the Completed Requests for more information and examples. The node-level |
integer (int32) |
||
queryLogLevel |
Log level used in the logger. All values, in descending order of data:
The node-level |
enum (DEBUG, TRACE, INFO, WARN, ERROR, SEVERE, NONE) |
||
queryMaxParallelism |
Specifies the maximum parallelism for queries on all Query nodes in the cluster. If the value is zero or negative, the maximum parallelism is restricted to the number of allowed cores. Similarly, if the value is greater than the number of allowed cores, the maximum parallelism is restricted to the number of allowed cores. (The number of allowed cores is the same as the number of logical CPUs. In Community Edition, the number of allowed cores cannot be greater than 4. In Enterprise Edition, there is no limit to the number of allowed cores.) The node-level In addition, there is a request-level
Refer to Max Parallelism for more information. |
integer (int32) |
||
queryMemoryQuota |
Specifies the maximum amount of memory a request may use on any Query node in the cluster, in MB. This parameter enforces a ceiling on the memory used for the tracked documents required for processing a request. It does not take into account any other memory that might be used to process a request, such as the stack, the operators, or some intermediate values. Within a transaction, this setting enforces the memory quota for the transaction by tracking the delta table and the transaction log (approximately). The node-level In addition, there is a request-level |
integer (int32) |
||
queryN1qlFeatCtrl |
SQL++ feature control. This setting is provided for technical support only. The node-level |
integer (int32) |
||
queryNodeQuota |
Sets the soft memory limit for every Query node in the cluster, in MB. The garbage collector tries to keep below this target. It is not a hard, absolute limit, and memory usage may exceed this value. When set to The node-level |
integer (int32) |
||
queryNodeQuotaValPercent |
The percentage of the The node-level |
integer (int32) |
||
queryNumAtrs |
Specifies the total number of active transaction records for all Query nodes in the cluster. The node-level In addition, there is a request-level |
integer (int32) |
||
queryNumCpus |
The number of CPUs the Query service can use on any Query node in the cluster. Note that this setting requires a restart of the Query service to take effect. When set to The number of CPUs can never be greater than the number of logical CPUs. In Community Edition, the number of allowed CPUs cannot be greater than 4. In Enterprise Edition, there is no limit to the number of allowed CPUs. The node-level |
integer (int32) |
||
queryPipelineBatch |
Controls the number of items execution operators can batch for Fetch from the KV. The node-level In addition, the request-level |
integer (int32) |
||
queryPipelineCap |
Maximum number of items each execution operator can buffer between various operators. The node-level In addition, the request-level |
integer (int32) |
||
queryPreparedLimit |
Maximum number of prepared statements in the cache. When this cache reaches the limit, the least recently used prepared statements will be discarded as new prepared statements are created. The node-level |
integer (int32) |
||
queryScanCap |
Maximum buffered channel size between the indexer client and the query service for index scans. This parameter controls when to use scan backfill. Use The node-level In addition, the request-level |
integer (int32) |
||
queryTimeout |
Maximum time to spend on the request before timing out (ns). The value for this setting is an integer, representing a duration in nanoseconds. It must not be delimited by quotes, and must not include a unit. Specify The node-level In addition, the request-level |
integer (int64) |
||
queryTxTimeout |
Maximum time to spend on a transaction before timing out.
This setting only applies to requests containing the The value for this setting is a string.
Its format includes an amount and a mandatory unit, e.g.
Specify The node-level In addition, there is a request-level |
string (duration) |
||
queryTmpSpaceDir |
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 |
string |
||
queryTmpSpaceSize |
The maximum size of temporary backfill files (MB). Setting the size to The maximum size is limited only by the available disk space. |
integer (int32) |
||
queryUseCBO |
Specifies whether the cost-based optimizer is enabled. The node-level In addition, the request-level |
boolean |
||
queryUseReplica |
Specifies whether a query can fetch data from a replica vBucket if active vBuckets are inaccessible. The possible values are:
The node-level In addition, the 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. Reading from replica is only possible if the cluster uses Couchbase Server 7.6.0 or later. 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. |
enum (off, on, unset) |
||
queryCurlWhitelist |
An object which determines which URLs may be accessed by the |
Access
Name | Description | Schema |
---|---|---|
all_access |
Defines whether the user has access to all URLs, or only URLs specified by the access list. This field set must be set to Setting this field to |
boolean |
allowed_urls |
An array of strings, each of which is a URL to which you wish to grant access. Each URL is a prefix match. The CURL() function will allow any URL that starts with this value. For example, if you wish to allow access to all Google APIs, add the URL https://maps.googleapis.com to the array.
To allow complete access to Note that each URL must include the port, protocol, and all other components of the URL. |
< string > array |
disallowed_urls |
An array of strings, each of which is a URL that will be restricted for all roles. Each URL is a prefix match. The CURL() function will disallow any URL that starts with this value. If both Note that each URL must include the port, protocol, and all other components of the URL. |
< string > array |
Security
The Query Settings REST API supports HTTP basic authentication. Credentials can be passed via HTTP headers.
Default
Users must have one of the following RBAC roles:
-
Full Admin
-
Cluster Admin
Type : basic
Refer to Roles for more details.
See Also
-
For node-level settings, see the Admin REST API.
-
For request-level parameters, see the Query Service REST API.