--- title: Configure Queries description: You can configure the Query Service using cluster-level query settings, node-level query settings, and request-level query parameters. pubDate: 2026-08-17T09:53:44.266Z antora: editUrl: https://github.com/couchbaselabs/docs-devex/edit/release/7.6/modules/n1ql/pages/n1ql-manage/query-settings.adoc xref: xref:7.6@server:n1ql:n1ql-manage/query-settings.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/server/7.6/n1ql/n1ql-manage/query-settings.html) # Configure Queries > You can configure the Query Service using cluster-level query settings, node-level query settings, and request-level query parameters. ## [](#overview)Overview You can configure the Query Service in the following ways: * Specify cluster-level settings for all nodes running the Query Service in the cluster. * Specify node-level settings for a single node running the Query Service. * Specify parameters for individual requests. You must set and use cluster-level query settings, node-level query settings, and request-level parameters in different ways. __Table 1\. Comparison of Query Settings and Parameters__ | | Set Per | Set By | Set On | Set Via | | ----------------------------------------------------------- | ------------------- | -------------------- | ----------- | --------------------------------------------------------- | | **Cluster-level query settings \[[note](#service-level)\]** | Cluster | System administrator | Server side | The CLI, curl statements, or the UI | | **Node-level query settings \[[note](#service-level)\]** | Service Node | System administrator | Server side | curl statements | | **Request-level parameters** | Request (statement) | Each user | Client side | cbq shell, curl statements, client programming, or the UI | > [!NOTE] > Cluster-level settings and node-level settings are collectively referred to as service-level settings. ## [](#query-setting-levels-and-equivalents)How Setting Levels Interact Some query settings are cluster-level, node-level, or request-level only. Other query settings apply to more than one level with slightly different names. ### [](#cluster-level-and-node-level)How Cluster-Level Settings Affect Node-Level Settings If a cluster-level setting has an equivalent node-level setting, then changing the cluster-level setting overwrites the node-level setting for all Query nodes in the cluster. You can change a node-level setting for a single node to be different to the equivalent cluster-level setting. Changing the node-level setting does not affect the equivalent cluster-level setting. However, be aware that subsequent changes at the cluster-level may overwrite the node-level setting. In particular, specifying query settings via the CLI or the UI makes changes at the cluster-level. ### [](#node-level-and-request-level)How Node-Level Settings Affect Request-Level Parameters If a request-level parameter has an equivalent node-level setting, the node-level setting usually acts as the default for the request-level parameter, as described in the tables below. Setting a request-level parameter overrides the equivalent node-level setting. Furthermore, for numeric values, if a request-level parameter has an equivalent node-level setting, the node-level setting dictates the upper-bound value of the request-level parameter. For example, if the node-level `timeout` is set to 500, then the request-level parameter cannot be set to 501 or any value higher. ## [](#all-query-settings)All Query Settings __Table 2\. Single-Level Settings — Not Equivalent__ | Cluster-Level Only Settings | Node-Level Only Settings | Request-Level Only Parameters | | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [queryTmpSpaceDir](#queryTmpSpaceDir) [queryTmpSpaceSize](#queryTmpSpaceSize) [queryCurlWhitelist](#queryCurlWhitelist) | [auto-prepare](#auto-prepare) [completed](#completed) [completed-stream-size](#completed-stream-size) [cpuprofile](#cpuprofile) [debug](#debug) [distribute](#distribute) [functions-limit](#functions-limit) [keep-alive-length](#keep-alive-length) [max-index-api](#max-index-api) [memprofile](#memprofile) [mutexprofile](#mutexprofile) [plus-servicers](#plus-servicers) [request-size-cap](#request-size-cap) [servicers](#servicers) | [args](#args) [auto\_execute](#auto%5Fexecute) [client\_context\_id](#client%5Fcontext%5Fid) [compression](#compression) [creds](#creds) [durability\_level](#durability%5Flevel) [encoded\_plan](#encoded%5Fplan) (deprecated) [encoding](#encoding) [format](#format) [kvtimeout](#kvtimeout) [metrics](#metrics) [namespace](#namespace) [prepared](#prepared) [preserve\_expiry](#preserve%5Fexpiry) [query\_context](#query%5Fcontext) [readonly](#readonly) [scan\_consistency](#scan%5Fconsistency) [scan\_vector](#scan%5Fvector) [scan\_vectors](#scan%5Fvectors) [scan\_wait](#scan%5Fwait) [signature](#signature) [sort\_projection](#sort%5Fprojection) [statement](#statement) [txid](#txid) [txstmtnum](#txstmtnum) [tximplicit](#tximplicit) [txdata](#txdata) [use\_fts](#use%5Ffts) [$identifier](#identifier) | __Table 3\. Equivalent Settings for Cluster-Level and Node-Level__ | Cluster-Level Name | Node-Level Name | Request-Level Name | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | [queryCleanupClientAttempts](#queryCleanupClientAttempts) [queryCleanupLostAttempts](#queryCleanupLostAttempts) [queryCleanupWindow](#queryCleanupWindow) [queryCompletedLimit](#queryCompletedLimit) [queryCompletedMaxPlanSize](#queryCompletedMaxPlanSize) [queryCompletedThreshold](#queryCompletedThreshold) [queryLogLevel](#queryLogLevel) [queryN1QLFeatCtrl](#queryN1QLFeatCtrl) [queryNodeQuota](#queryNodeQuota) [queryNodeQuotaValPercent](#queryNodeQuotaValPercent) [queryNumCpus](#queryNumCpus) [queryPreparedLimit](#queryPreparedLimit) | [cleanupclientattempts](#cleanupclientattempts) [cleanuplostattempts](#cleanuplostattempts) [cleanupwindow](#cleanupwindow) [completed-limit](#completed-limit) [completed-max-plan-size](#completed-max-plan-size) [completed-threshold](#completed-threshold) [loglevel](#loglevel) [n1ql-feat-ctrl](#n1ql-feat-ctrl) [node-quota](#node-quota) [node-quota-val-percent](#node-quota-val-percent) [num-cpus](#num-cpus) [prepared-limit](#prepared-limit) | N/A | __Table 4\. Equivalent Settings for Node-Level and Request-Level__ | Cluster-Level Name | Node-Level Name | Request-Level Name | | ------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | N/A | [atrcollection](#atrcollection-srv) [controls](#controls-srv) [pretty](#pretty-srv) [profile](#profile-srv) | [atrcollection](#atrcollection%5Freq) [controls](#controls%5Freq) [pretty](#pretty%5Freq) [profile](#profile%5Freq) | __Table 5\. Equivalent Settings for Cluster-Level, Node-Level, and Request-Level__ | Cluster-Level Name | Node-Level Name | Request-Level Name | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [queryMaxParallelism](#queryMaxParallelism) [queryMemoryQuota](#queryMemoryQuota) [queryNumAtrs](#queryNumAtrs) [queryPipelineBatch](#queryPipelineBatch) [queryPipelineCap](#queryPipelineCap) [queryScanCap](#queryScanCap) [queryTimeout](#queryTimeout) [queryTxTimeout](#queryTxTimeout) [queryUseCBO](#queryUseCBO) [queryUseReplica](#queryUseReplica) | [max-parallelism](#max-parallelism-srv) [memory-quota](#memory-quota-srv) [numatrs](#numatrs-srv) [pipeline-batch](#pipeline-batch-srv) [pipeline-cap](#pipeline-cap-srv) [scan-cap](#scan-cap-srv) [timeout](#timeout-srv) [txtimeout](#txtimeout-srv) [use-cbo](#use-cbo-srv) [use-replica](#use-replica-srv) | [max\_parallelism](#max%5Fparallelism%5Freq) [memory\_quota](#memory%5Fquota%5Freq) [numatrs](#numatrs%5Freq) (for future use) [pipeline\_batch](#pipeline%5Fbatch%5Freq) [pipeline\_cap](#pipeline%5Fcap%5Freq) [scan\_cap](#scan%5Fcap%5Freq) [timeout](#timeout%5Freq) [txtimeout](#txtimeout%5Freq) [use\_cbo](#use%5Fcbo%5Freq) [use\_replica](#use%5Freplica%5Freq) | ## [](#cluster-level-query-settings)Cluster-Level Query Settings To set a cluster-level query setting, do one of the following: * Use the [Advanced Query Settings](../../manage/manage-settings/general-settings.md#query-settings) in the Couchbase Web Console. * Use the [setting-query](../../cli/cbcli/couchbase-cli-setting-query.md) command at the command line. * Make a REST API call to the [Query Settings REST API](../../n1ql-rest-settings/index.md) (`/settings/querySettings` endpoint). * Web Console * Command Line * REST API To set cluster-level settings in the Web Console: 1. Go to **Settings** **General** and click **Advanced Query Settings** to display the settings. 2. Specify the settings and click **Save**. ![The top of the Advanced Query Settings](../../manage/_images/manage-settings/query-settings-top.png) To set cluster-level settings at the command line, use the `couchbase-cli setting-query` command. --- The following example retrieves the current cluster-level settings: ```sh couchbase-cli setting-query -c http://localhost:8091 -u Administrator \ -p password --get ``` The following example sets the cluster-level maximum parallelism and log level settings: ```sh couchbase-cli setting-query -c http://localhost:8091 -u Administrator \ -p password --set --log-level debug --max-parallelism 4 ``` To set cluster-level settings with the REST API, specify the parameters in the request body. --- The following example retrieves the current cluster-level settings: ```sh curl -v -u Administrator:password \ http://localhost:8091/settings/querySettings ``` The following example sets the cluster-level maximum parallelism and log level settings: ```sh curl -v -X POST -u Administrator:password \ http://localhost:8091/settings/querySettings \ -d 'queryLogLevel=debug' \ -d 'queryMaxParallelism=4' ``` The table below contains details of all cluster-level query settings. __Table 6\. Cluster-Level Query Settings__ | Property | | Schema | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | **queryCleanupClientAttempts**optional | 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's forced to. The [node-level](#cleanupclientattempts) cleanupclientattempts setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** true **Example:** false | Boolean | | **queryCleanupLostAttempts**optional | When enabled, the Query Service takes part in the distributed cleanup process, and cleans up expired transactions created by any client. The [node-level](#cleanuplostattempts) cleanuplostattempts setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** true **Example:** false | Boolean | | **queryCleanupWindow**optional | Specifies how frequently the Query Service checks its subset of [active transaction records](/server/7.6/learn/data/transactions.html#active-transaction-record-entries) 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. 10ms (10 milliseconds) or 0.5s (half a second). Valid units are: ns (nanoseconds) us (microseconds) ms (milliseconds) s (seconds) m (minutes) h (hours) The [node-level](#cleanupwindow) cleanupwindow setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** "60s" **Example:** "30s" | String (duration) | | **queryCompletedLimit**optional | 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. For more information and examples, see [Configure the Completed Requests](monitoring-n1ql-query.html#sys-completed-config). The [node-level](#completed-limit) completed-limit setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 4000 **Example:** 7000 | Integer (int32) | | **queryCompletedMaxPlanSize**optional | 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. For more information, see [Configure the Completed Requests](monitoring-n1ql-query.html#sys-completed-config). The [node-level](#completed-max-plan-size) completed-max-plan-size setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 262144 **Minimum:** 0 **Maximum:** 20840448 | Integer (int32) | | **queryCompletedThreshold**optional | A duration in milliseconds. All completed queries lasting longer than this threshold are logged in the completed requests catalog. Specify 0 to track all requests, independent of duration. Specify any negative number to track none. For more information and examples, see [Configure the Completed Requests](monitoring-n1ql-query.html#sys-completed-config). The [node-level](#completed-threshold) completed-threshold setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 1000 **Example:** 7000 | Integer (int32) | | **queryLogLevel**optional | Log level used in the logger. All values, in descending order of data: DEBUG — For developers. Writes everything. TRACE — For developers. Less info than DEBUG. INFO — For admin & customers. Lists warnings & errors. WARN — For admin. Only abnormal items. ERROR — For admin. Only errors to be fixed. SEVERE — For admin. Major items, like crashes. NONE — Does not write anything. The [node-level](#loglevel) loglevel setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Values:** "DEBUG", "TRACE", "INFO", "WARN", "ERROR", "SEVERE", "NONE" **Default:** "INFO" **Example:** "DEBUG" | String | | **queryMaxParallelism**optional | 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 Couchbase Server Community Edition, the number of allowed cores cannot be greater than 4\. In Couchbase Server Enterprise Edition, there is no limit to the number of allowed cores.) For more information, see [Max Parallelism](../n1ql-language-reference/index-partitioning.html#max-parallelism). The [node-level](#max-parallelism-srv) max-parallelism setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, there is a [request-level](#max%5Fparallelism%5Freq) max\_parallelism parameter. If a request includes this parameter, it will be capped by the node-level max-parallelism setting. NOTE: To enable queries to run in parallel, you must specify the cluster-level queryMaxParallelism parameter, or specify the node-level max-parallelism parameter on all Query nodes. **Default:** 1 **Example:** 0 | Integer (int32) | | **queryMemoryQuota**optional | 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](#memory-quota-srv) memory-quota setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, there is a [request-level](#memory%5Fquota%5Freq) memory\_quota parameter. If a request includes this parameter, it will be capped by the node-level memory-quota setting. **Default:** 0 **Example:** 4 | Integer (int32) | | **queryN1QLFeatCtrl**optional | SQL++ feature control. This setting is provided for technical support only. The [node-level](#n1ql-feat-ctrl) n1ql-feat-ctrl setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. | Integer (int32) | | **queryNodeQuota**optional | Sets the soft memory limit for the Query Service on every Query node in the cluster, in MB. The garbage collector tries to keep below this target. It's not a hard, absolute limit, and memory usage may exceed this value. When set to 0 (the default), the Query Service sets a default soft memory limit for every node. To do this, the Query Service calculates the difference between the total system RAM and 90% of the total system RAM: Total System RAM - (0.9 \* Total System RAM) If the difference is greater than 8 GiB, the default soft memory limit is set to the total system RAM minus 8 GiB. If the difference is 8 GiB or less, the default soft memory limit is set to 90% of the total system RAM. The [node-level](#node-quota) node-quota setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 0 | Integer (int32) | | **queryNodeQuotaValPercent**optional | The percentage of the queryNodeQuota that's dedicated to tracked value content memory across all active requests for every Query node in the cluster. (The queryMemoryQuota setting specifies the maximum amount of document memory an individual request may use on any Query node in the cluster.) The [node-level](#node-quota-val-percent) node-quota-val-percent setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 67 **Minimum:** 0 **Maximum:** 100 | Integer (int32) | | **queryNumAtrs**optional | Specifies the total number of [active transaction records](/server/7.6/learn/data/transactions.html#active-transaction-record-entries) for all Query nodes in the cluster. The [node-level](#numatrs-srv) numatrs setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 1024 **Minimum:** 0 (exclusive) **Example:** 512 | Integer (int32) | | **queryNumCpus**optional | The number of CPUs the Query Service can use on any Query node in the cluster. This setting requires a restart of the Query Service to take effect. When set to 0 (the default), the Query Service can use all available CPUs, up to the limits described below. The number of CPUs can never be greater than the number of logical CPUs. In Couchbase Server Community Edition, the number of allowed CPUs cannot be greater than 4\. In Couchbase Server Enterprise Edition, there is no limit to the number of allowed CPUs. The [node-level](#num-cpus) num-cpus setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 0 | Integer (int32) | | **queryPipelineBatch**optional | Controls the number of items execution operators can batch for Fetch from the KV. The [node-level](#pipeline-batch-srv) pipeline-batch setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, the [request-level](#pipeline%5Fbatch%5Freq) pipeline\_batch parameter specifies this property per request. The minimum of that and the node-level pipeline-batch setting is applied. **Default:** 16 **Example:** 64 | Integer (int32) | | **queryPipelineCap**optional | Maximum number of items each execution operator can buffer between various operators. The [node-level](#pipeline-cap-srv) pipeline-cap setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, the [request-level](#pipeline%5Fcap%5Freq) pipeline\_cap parameter specifies this property per request. The minimum of that and the node-level pipeline-cap setting is applied. **Default:** 512 **Example:** 1024 | Integer (int32) | | **queryPreparedLimit**optional | 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](#prepared-limit) prepared-limit setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 16384 **Example:** 65536 | Integer (int32) | | **queryScanCap**optional | Maximum buffered channel size between the indexer client and the Query Service for index scans. This parameter controls when to use scan backfill. Use 0 or a negative number to disable. Smaller values reduce GC, while larger values reduce indexer backfill. The [node-level](#scan-cap-srv) scan-cap setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, the [request-level](#scan%5Fcap%5Freq) scan\_cap parameter specifies this property per request. The minimum of that and the node-level scan-cap setting is applied. **Default:** 512 **Example:** 1024 | Integer (int32) | | **queryTimeout**optional | 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 0 (the default value) or a negative integer to disable. When disabled, no timeout is applied and the request runs for however long it takes. The [node-level](#timeout-srv) timeout setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, the [request-level](#timeout%5Freq) timeout parameter specifies this property per request. The minimum of that and the node-level timeout setting is applied. **Default:** 0 **Example:** 500000000 | Long (int64) | | **queryTxTimeout**optional | Maximum time to spend on a transaction before timing out. This setting only applies to requests containing the BEGIN TRANSACTION statement, or to requests where the [tximplicit](#tximplicit) parameter is set. For all other requests, it's ignored. The value for this setting is a string. Its format includes an amount and a mandatory unit, e.g. 10ms (10 milliseconds) or 0.5s (half a second). Valid units are: ns (nanoseconds) us (microseconds) ms (milliseconds) s (seconds) m (minutes) h (hours) Specify 0ms (the default value) to disable. When disabled, no timeout is applied and the transaction runs for however long it takes. The [node-level](#txtimeout-srv) txtimeout setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, there is a [request-level](#txtimeout%5Freq) txtimeout parameter. If a request includes this parameter, it will be capped by the node-level txtimeout setting. **Default:** "0ms" **Example:** "0.5s" | String (duration) | | **queryTmpSpaceDir**optional | 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. **Example:** "/opt/couchbase/var/lib/couchbase/tmp" | String | | **queryTmpSpaceSize**optional | The maximum size of temporary backfill files (MB). 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. **Default:** 5120 **Example:** 2048 | Integer (int32) | | **queryUseCBO**optional | Specifies whether the cost-based optimizer is enabled. The [node-level](#use-cbo-srv) use-cbo setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, the [request-level](#use%5Fcbo%5Freq) use\_cbo parameter specifies this property per request. If a request does not include this parameter, the node-level setting is used, which defaults to true. **Default:** true **Example:** false | Boolean | | **queryUseReplica**optional | Specifies whether a query can fetch data from a replica vBucket if active vBuckets are inaccessible. The possible values are: off — read from replica is disabled for all queries and cannot be overridden at request level. on — read from replica is enabled for all queries, but can be disabled at request level. unset — read from replica is enabled or disabled 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. Reading from replica is only possible if the cluster uses Couchbase Server 7.6.0 or later. You cannot currently start KV range scans 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. The [node-level](#use-replica-srv) use-replica setting specifies this property for a single node. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, the [request-level](#use%5Freplica%5Freq) use\_replica parameter specifies this property per request. If a request does not include this parameter, or if the request-level parameter is unset, the node-level setting is used. If the request-level parameter and the node-level setting are both unset, read from replica is disabled for that request. **Values:** "off", "on", "unset" **Default:** "unset" **Example:** "on" | String | | **queryCurlWhitelist**optional | An object which determines which URLs may be accessed by the CURL() function. | [Access](#Access) | **Access** | Property | | Schema | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | | **all\_access**required | Defines whether the user has access to all URLs, or only URLs specified by the access list. This field set must be set to false to enable the allowed\_urls and disallowed\_urls fields. Setting this field to true enables access to all endpoints. | Boolean | | **allowed\_urls**optional | 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 localhost, use http://localhost. Each URL must include the port, protocol, and all other components of the URL. | String array | | **disallowed\_urls**optional | 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 allowed\_urls and disallowed\_urls fields are populated, the disallowed\_urls field takes precedence over allowed\_urls. Each URL must include the port, protocol, and all other components of the URL. | String array | ## [](#service-level-query-settings)Node-Level Query Settings To set a node-level query setting: * Make a REST API call to the [Admin REST API](../../n1ql-rest-admin/index.md) (`/admin/settings` endpoint). You cannot set a query setting for an individual node using the Couchbase Web Console or the command line. * REST API To set node-level settings with the REST API, specify the parameters in the request body. --- The following example retrieves the current node-level settings: ```sh curl $BASE_URL/admin/settings -u $USER:$PASSWORD ``` The following example sets the node-level profile parameter: ```sh curl $BASE_URL/admin/settings -u $USER:$PASSWORD \ -H 'Content-Type: application/json' \ -d '{"profile": "phases"}' ``` For more examples, see [Manage and Monitor Queries](monitoring-n1ql-query.md). The table below contains details of all node-level query settings. __Table 7\. Node-Level Query Settings__ | Property | | Schema | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- | | **atrcollection**optional | Specifies the collection where [active transaction records](/server/7.6/learn/data/transactions.html#active-transaction-record-entries) are stored. The collection must be present. If not specified, the active transaction record is stored in the default collection in the default scope in the bucket containing the first mutated document within the transaction. The value must be a string in the form "bucket.scope.collection" or "namespace:bucket.scope.collection". If any part of the path contains a special character, that part of the path must be delimited in backticks \`\`. The [request-level](#atrcollection%5Freq) atrcollection parameter specifies this property per request. If a request does not include this parameter, the node-level atrcollection setting will be used. **Default:** "" **Example:** "default:\`travel-sample\`.transaction.test" | String | | **auto-prepare**optional | Specifies whether the query engine should create a prepared statement every time a SQL++ request is submitted, whether the PREPARE statement is included or not. For more information, see [Auto-Prepare](../n1ql-language-reference/prepare.html#auto-prepare). **Default:** false **Example:** true | Boolean | | **cleanupclientattempts**optional | 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's forced to. The [cluster-level](#queryCleanupClientAttempts) queryCleanupClientAttempts setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** true **Example:** false | Boolean | | **cleanuplostattempts**optional | When enabled, the Query Service takes part in the distributed cleanup process, and cleans up expired transactions created by any client. The [cluster-level](#queryCleanupLostAttempts) queryCleanupLostAttempts setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** true **Example:** false | Boolean | | **cleanupwindow**optional | Specifies how frequently the Query Service checks its subset of [active transaction records](/server/7.6/learn/data/transactions.html#active-transaction-record-entries) 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. 10ms (10 milliseconds) or 0.5s (half a second). Valid units are: ns (nanoseconds) us (microseconds) ms (milliseconds) s (seconds) m (minutes) h (hours) The [cluster-level](#queryCleanupWindow) queryCleanupWindow setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** "60s" **Example:** "30s" | String (duration) | | **completed**optional | A nested object that sets the parameters for the completed requests catalog. All completed requests that match these parameters are tracked in the completed requests catalog. For more information and examples, see [Configure Completed Requests](monitoring-n1ql-query.html#sys-completed-config). | [Logging Parameters](#Logging%5FParameters) | | **completed-limit**optional | 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. For more information and examples, see [Configure Completed Requests](monitoring-n1ql-query.html#sys-completed-config). The [cluster-level](#queryCompletedLimit) queryCompletedLimit setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 4000 **Example:** 7000 | Integer (int32) | | **completed-max-plan-size**optional | 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. For more information, see [Configure Completed Requests](monitoring-n1ql-query.html#sys-completed-config). The [cluster-level](#queryCompletedMaxPlanSize) queryCompletedMaxPlanSize setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 262144 **Minimum:** 0 **Maximum:** 20840448 | Integer (int32) | | **completed-stream-size**optional | Couchbase Server 7.6.4 A file size in MiB. When specified, completed requests are saved to the Couchbase Server logs directory. Completed requests are saved to GZIP archives with the prefix local\_request\_log. The value of this property determines the size of the data to retain, per node. Specify 0 (the default) to disable completed request streaming. Completed request streaming is available in Couchbase Server 7.6.4 and later. For more information and examples, see [Stream Completed Requests](monitoring-n1ql-query.html#sys-history). | Integer (int32) | | **completed-threshold**optional | A duration in milliseconds. All completed queries lasting longer than this threshold are logged in the completed requests catalog. Specify 0 to track all requests, independent of duration. Specify any negative number to track none. For more information and examples, see [Configure Completed Requests](monitoring-n1ql-query.html#sys-completed-config). The [cluster-level](#queryCompletedThreshold) queryCompletedThreshold setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 1000 **Example:** 7000 | Integer (int32) | | **controls**optional | Specifies if there should be a controls section returned with the request results. When set to true, the query response document includes a controls section with runtime information provided along with the request, such as positional and named parameters or settings. NOTE: If the request qualifies for caching, these values will also be cached in the completed\_requests system keyspace. The [request-level](#controls%5Freq) controls parameter specifies this property per request. If a request does not include this parameter, the node-level controls setting will be used. **Default:** false **Example:** true | Boolean | | **cpuprofile**optional | The absolute path and filename to write the CPU profile to a local file. The output file includes a controls section and performance measurements, such as memory allocation and garbage collection, to pinpoint bottlenecks and ways to improve your code execution. NOTE: If cpuprofile is left running too long, it can slow the system down as its file size increases. To stop cpuprofile, run with the empty setting of "". **Default:** "" **Example:** "/tmp/info.txt" | String | | **debug**optional | Use debug mode. When set to true, extra logging is provided. **Default:** false **Example:** true | Boolean | | **distribute**optional | This field is only available with the POST method. When specified alongside other settings, this field instructs the node that's processing the request to cascade those settings to all other query nodes. The actual value of this field is ignored. **Example:** true | Boolean | | **functions-limit**optional | Maximum number of user-defined functions. **Default:** 16384 **Example:** 7000 | Integer (int32) | | **keep-alive-length**optional | Maximum size of buffered result. **Default:** 16384 **Example:** 7000 | Integer (int32) | | **loglevel**optional | Log level used in the logger. All values, in descending order of data: DEBUG — For developers. Writes everything. TRACE — For developers. Less info than DEBUG. INFO — For admin & customers. Lists warnings & errors. WARN — For admin. Only abnormal items. ERROR — For admin. Only errors to be fixed. SEVERE — For admin. Major items, like crashes. NONE — Does not write anything. The [cluster-level](#queryLogLevel) queryLogLevel setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Values:** "DEBUG", "TRACE", "INFO", "WARN", "ERROR", "SEVERE", "NONE" **Default:** "INFO" **Example:** "DEBUG" | String | | **max-index-api**optional | Max index API. This setting is provided for technical support only. | Integer (int32) | | **max-parallelism**optional | Specifies the maximum parallelism for queries on this node. 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 Couchbase Server Community Edition, the number of allowed cores cannot be greater than 4\. In Couchbase Server Enterprise Edition, there is no limit to the number of allowed cores.) For more information, see [Max Parallelism](../n1ql-language-reference/index-partitioning.html#max-parallelism). The [cluster-level](#queryMaxParallelism) queryMaxParallelism setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, there is a [request-level](#max%5Fparallelism%5Freq) max\_parallelism parameter. If a request includes this parameter, it will be capped by the node-level max-parallelism setting. NOTE: To enable queries to run in parallel, you must specify the cluster-level queryMaxParallelism parameter, or specify the node-level max-parallelism parameter on all Query nodes. **Default:** 1 **Example:** 0 | Integer (int32) | | **memory-quota**optional | Specifies the maximum amount of memory a request may use on this node, in MB. Specify 0 (the default value) to disable. When disabled, there is no quota. 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 [cluster-level](#queryMemoryQuota) queryMemoryQuota setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, the [request-level](#memory%5Fquota%5Freq) memory\_quota parameter specifies this property per request. If a request includes this parameter, it will be capped by the node-level memory-quota setting. **Default:** 0 **Example:** 4 | Integer (int32) | | **memprofile**optional | Filename to write the diagnostic memory usage log. NOTE: If memprofile is left running too long, it can slow the system down as its file size increases. To stop memprofile, run with the empty setting of "". **Default:** "" **Example:** "/tmp/memory-usage.log" | String | | **mutexprofile**optional | Mutex profile. This setting is provided for technical support only. **Default:** false | Boolean | | **n1ql-feat-ctrl**optional | SQL++ feature control. This setting is provided for technical support only. The value may be an integer, or a string representing a hexadecimal number. The [cluster-level](#queryN1QLFeatCtrl) queryN1QLFeatCtrl setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 76 **Example:** 16460 | Integer (int32) | | **node-quota**optional | Sets the soft memory limit for the Query Service on this node, in MB. The garbage collector tries to keep below this target. It's not a hard, absolute limit, and memory usage may exceed this value. When set to 0 (the default), the Query Service sets a default soft memory limit for the node. To do this, the Query Service calculates the difference between the total system RAM and 90% of the total system RAM: Total System RAM - (0.9 \* Total System RAM) If the difference is greater than 8 GiB, the default soft memory limit is set to the total system RAM minus 8 GiB. If the difference is 8 GiB or less, the default soft memory limit is set to 90% of the total system RAM. The [cluster-level](#queryNodeQuota) queryNodeQuota setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 0 | Integer (int32) | | **node-quota-val-percent**optional | The percentage of the node-quota that's dedicated to tracked value content memory across all active requests on this node. (The memory-quota setting specifies the maximum amount of document memory an individual request may use on this node.) The [cluster-level](#queryNodeQuotaValPercent) queryNodeQuotaValPercent setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 67 **Minimum:** 0 **Maximum:** 100 | Integer (int32) | | **num-cpus**optional | The number of CPUs the Query Service can use on this node. This setting requires a restart of the Query Service to take effect. When set to 0 (the default), the Query Service can use all available CPUs, up to the limits described below. The number of CPUs can never be greater than the number of logical CPUs. In Couchbase Server Community Edition, the number of allowed CPUs cannot be greater than 4\. In Couchbase Server Enterprise Edition, there is no limit to the number of allowed CPUs. The [cluster-level](#queryNumCpus) queryNumCpus setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 0 | Integer (int32) | | **numatrs**optional | Specifies the total number of [active transaction records](/server/7.6/learn/data/transactions.html#active-transaction-record-entries). The [cluster-level](#queryNumAtrs) queryNumAtrs setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. | String | | **pipeline-batch**optional | Controls the number of items execution operators can batch for Fetch from the KV. The [cluster-level](#queryPipelineBatch) queryPipelineBatch setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, the [request-level](#pipeline%5Fbatch%5Freq) pipeline\_batch parameter specifies this property per request. The minimum of that and the node-level pipeline-batch setting is applied. **Default:** 16 **Example:** 64 | Integer (int32) | | **pipeline-cap**optional | Maximum number of items each execution operator can buffer between various operators. The [cluster-level](#queryPipelineCap) queryPipelineCap setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, the [request-level](#pipeline%5Fcap%5Freq) pipeline\_cap parameter specifies this property per request. The minimum of that and the node-level pipeline-cap setting is applied. **Default:** 512 **Example:** 1024 | Integer (int32) | | **plus-servicers**optional | The number of service threads for transactions where the scan consistency is request\_plus or at\_plus. The default is 16 times the number of logical cores. **Example:** 16 | Integer (int32) | | **prepared-limit**optional | 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 [cluster-level](#queryPreparedLimit) queryPreparedLimit setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. **Default:** 16384 **Example:** 65536 | Integer (int32) | | **pretty**optional | Specifies whether query results are returned in pretty format. The [request-level](#pretty%5Freq) pretty parameter specifies this property per request. If a request does not include this parameter, the node-level setting is used, which defaults to false. **Default:** false **Example:** true | Boolean | | **profile**optional | Specifies if there should be a profile section returned with the request results. The valid values are: off — No profiling information is added to the query response. phases — The query response includes a profile section with stats and details about various phases of the query plan and execution. Three phase times will be included in the system:active\_requests and system:completed\_requests monitoring keyspaces. timings — Besides the phase times, the profile section of the query response document will include a full query plan with timing and information about the number of processed documents at each phase. This information will be included in the system:active\_requests and system:completed\_requests keyspaces. NOTE: If profile is not set as one of the above values, then the profile setting does not change. For more information and examples, see [Monitoring and Profiling Details](monitoring-n1ql-query.html#monitor-profile-details). The [request-level](#profile%5Freq) profile parameter specifies this property per request. If a request does not include this parameter, the node-level profile setting will be used. **Values:** "off", "phases", "timings" **Default:** "off" **Example:** "phases" | String | | **request-size-cap**optional | Maximum size of a request. **Default:** 67108864 **Example:** 70000 | Integer (int32) | | **scan-cap**optional | Maximum buffered channel size between the indexer client and the Query Service for index scans. This parameter controls when to use scan backfill. Use 0 or a negative number to disable. Smaller values reduce GC, while larger values reduce indexer backfill. The [cluster-level](#queryScanCap) queryScanCap setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, the [request-level](#scan%5Fcap%5Freq) scan\_cap parameter specifies this property per request. The minimum of that and the node-level scan-cap setting is applied. **Default:** 512 **Example:** 1024 | Integer (int32) | | **servicers**optional | The number of service threads for the query. The default is 4 times the number of cores on the query node. **Default:** 32 **Example:** 8 | Integer (int32) | | **timeout**optional | 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 0 (the default value) or a negative integer to disable. When disabled, no timeout is applied and the request runs for however long it takes. The [cluster-level](#queryTimeout) queryTimeout setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, the [request-level](#timeout%5Freq) timeout parameter specifies this property per request. The minimum of that and the node-level timeout setting is applied. **Default:** 0 **Example:** 500000000 | Long (int64) | | **txtimeout**optional | Maximum time to spend on a transaction before timing out (ns). This setting only applies to requests containing the BEGIN TRANSACTION statement, or to requests where the [tximplicit](#tximplicit) parameter is set. For all other requests, it's ignored. 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 0 (the default value) to disable. When disabled, no timeout is applied and the transaction runs for however long it takes. The [cluster-level](#queryTxTimeout) queryTxTimeout setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, the [request-level](#txtimeout%5Freq) txtimeout parameter specifies this property per request. The minimum of that and the node-level txtimeout setting is applied. **Default:** 0 **Example:** 500000000 | Long (int64) | | **use-cbo**optional | Specifies whether the cost-based optimizer is enabled. The [cluster-level](#queryUseCBO) queryUseCBO setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster. In addition, the [request-level](#use%5Fcbo%5Freq) use\_cbo parameter specifies this property per request. If a request does not include this parameter, the node-level setting is used, which defaults to true. **Default:** true **Example:** false | Boolean | | **use-replica**optional | Specifies whether a query can fetch data from a replica vBucket if active vBuckets are inaccessible. The possible values are: off — read from replica is disabled for all queries and cannot be overridden at request level. on — read from replica is enabled for all queries, but can be disabled at request level. unset — read from replica is enabled or disabled 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. Reading from replica is only possible if the cluster uses Couchbase Server 7.6.0 or later. You cannot currently start KV range scans 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. The [cluster-level](#queryUseReplica) queryUseReplica setting specifies the default for this property for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster. In addition, the [request-level](#use%5Freplica%5Freq) use\_replica parameter specifies this property per request. If a request does not include this parameter, or if the request-level parameter is unset, the node-level setting is used. If the request-level parameter and the node-level setting are both unset, read from replica is disabled for that request. **Values:** "off", "on", "unset" **Default:** "unset" **Example:** "on" | String | **Logging Parameters** | Property | | Schema | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | **aborted**optional | If true, all requests that generate a panic are logged. **Default:** null **Nullable:** yes **Example:** true | Boolean | | **client**optional | The IP address of the client. If specified, all completed requests from this IP address are logged. **Default:** "" **Example:** "172.1.2.3" | String | | **context**optional | The opaque ID or context provided by the client. If specified, all completed requests with this client context ID are logged. For more information, see the [request-level](#client%5Fcontext%5Fid) client\_context\_id parameter. | String | | **error**optional | An error number. If specified, all completed queries returning this error number are logged. **Default:** null **Nullable:** yes **Example:** 12003 | Integer (int32) | | **tag**optional | A unique string which tags a set of qualifiers. For more information, see [Configure Completed Requests](monitoring-n1ql-query.html#sys-completed-config). **Default:** "" **Example:** "both\_user\_and\_error" | String | | **threshold**optional | A duration in milliseconds. If specified, all completed queries lasting longer than this threshold are logged. This is another way of specifying the completed-threshold setting. **Default:** 1000 **Example:** 7000 | Integer (int32) | | **user**optional | A user name, as given in the request credentials. If specified, all completed queries with this user name are logged. **Default:** "" **Example:** "marco" | String | | **errors**optional | The number of errors. If specified, all completed queries that return at least this many errors are logged. Queries with fewer errors are not logged. **Example:** 5 | Integer (int32) | ## [](#section%5Fnnj%5Fsjk%5Fk1b)Request-Level Parameters To set a request-level parameter, do one of the following: * Use the [Run-Time Preferences](../../tools/query-workbench.md#query-preferences) window in the Query Workbench. * Use the [cbq](../n1ql-intro/cbq.md) shell at the command line. * Make a REST API call to the [Query Service REST API](../../n1ql-rest-query/index.md) (`/query/service` endpoint). * Use an SDK client program. Generally, use the `cbq` shell or the Query Workbench as a sandbox to test queries on your local machine. Use a REST API call or an SDK client program for your production queries. * Web Console * Command Line * REST API To set request-level preferences in the Query Workbench: 1. Go to **Query** **Workbench** and click the cog icon to display the Run-Time Preferences window. 2. Specify the preferences — if a preference is not explicitly listed, click **+** next to **Named Parameters** and add its name and value. 3. Click **Save Preferences**. ![The Run-Time Preferences window](../../tools/_images/query-workbench-preferences.png) For more examples, see the [Couchbase Transactions](../../guides/transactions.md#settings) guide. To set request-level parameters in `cbq`, use the `\SET` command. The parameter name must be prefixed by a hyphen. --- The following example sets the request-level timeout, pretty-print, and max parallelism parameters, and runs a query: ```sqlpp \SET -timeout "30m"; \SET -pretty true; \SET -max_parallelism 3; SELECT * FROM "world" AS hello; ``` For more examples, see [Parameter Manipulation](../n1ql-intro/cbq.md#cbq-parameter-manipulation) in the cbq documentation. To set request-level parameters with the REST API, specify the parameters in the request body or the query URI. --- The following example sets the request-level timeout, pretty-print, and max parallelism parameters, and runs a query: ```sh curl http://localhost:8093/query/service -u Administrator:password \ -d 'statement=SELECT * FROM "world" AS hello; & timeout=30m & pretty=true & max_parallelism=3' ``` For more examples, see the [Query Service REST API examples](../n1ql-rest-api/examplesrest.md). The table below contains details of all request-level parameters, along with examples. __Table 8\. Request-Level Parameters__ | Property | | Schema | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | **args**optional | Supplies the values for positional parameters in the statement. Applicable if the statement or prepared statement contains 1 or more positional parameters. The value is an array of JSON values, one for each positional parameter in the statement. For more information, see [Named Parameters and Positional Parameters](#section%5Fsrh%5Ftlm%5Fn1b). **Example:** \["LAX",6\] | Any Type array | | **atrcollection**optional | Specifies the collection where the [active transaction record](/server/7.6/learn/data/transactions.html#active-transaction-record-entries) (ATR) is stored. The collection must be present. If not specified, the ATR is stored in the default collection in the default scope in the bucket containing the first mutated document within the transaction. The value must be a string in the form "bucket.scope.collection" or "namespace:bucket.scope.collection". If any part of the path contains a special character, that part of the path must be delimited in backticks \`\`. The [node-level](#atrcollection-srv) atrcollection setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting. **Example:** "default:\`travel-sample\`.transaction.test" | String | | **auto\_execute**optional | Specifies that prepared statements should be executed automatically as soon as they're created. This saves you from having to make two separate requests in cases where you want to prepare a statement and execute it immediately. For more information, see [Auto-Execute](../n1ql-language-reference/prepare.html#auto-execute). **Default:** false **Example:** true | Boolean | | **client\_context\_id**optional | A piece of data supplied by the client that's echoed in the response, if present. SQL++ is agnostic about the content of this parameter; it's just echoed in the response. Maximum allowed size is 64 characters; all others will be cut. If it contains an escape character / or quote ", it will be rejected as error code 1110. | String | | **compression**optional | Compression format to use for response data on the wire. Values are case-insensitive. **Values:** "ZIP", "RLE", "LZMA", "LZO", "NONE" **Default:** "NONE" **Example:** "zip" | String | | **controls**optional | Specifies if there should be a controls section returned with the request results. When set to true, the query response document includes a controls section with runtime information provided along with the request, such as positional and named parameters or settings. If the request qualifies for caching, these values will also be cached in the completed\_requests system keyspace. The [node-level](#controls-srv) controls setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting. **Example:** true | Boolean | | **creds**optional | Specifies the login credentials. The Query API supports two types of identity: local (or bucket) and admin. The format is an identity and password. You can specify credentials for multiple identities. If credentials are supplied in the request header, then HTTP Basic Authentication takes precedence and creds is ignored. **Example:** \[{"user":"local:bucket-name","pass":"password"},{"user":"admin:admin-name","pass":"password"}\] | [Credentials](#RequestCredentials) array | | **durability\_level**optional | The level of [durability](/server/7.6/learn/data/durability.html) for mutations produced by the request. If the request contains a BEGIN TRANSACTION statement, or a DML statement with the tximplicit parameter set to true, the durability level is specified for all mutations within that transaction. Durability is also supported for non-transactional DML statements. In this case, the kvtimeout parameter is used as the durability timeout. If not specified, the default durability level is "majority". Set the durability level to "none" or "" to specify no durability. **Values:** "", "none", "majority", "majorityAndPersistActive", "persistToMajority" **Default:** "majority" **Example:** "none" | String | | **encoded\_plan**optional | In Couchbase Server 6.5 and later, this parameter is ignored and has no effect. It's included for compatibility with previous versions of Couchbase Server. | String | | **encoding**optional | Desired character encoding for the query results. Only possible value is UTF-8 and is case-insensitive. **Default:** "UTF-8" | String | | **format**optional | Desired format for the query results. Values are case-insensitive. **Values:** "JSON", "XML", "CSV", "TSV" **Default:** "JSON" **Example:** "XML" | String | | **kvtimeout**optional | The approximate time to wait for a KV get operation before timing out. This applies to statements within a transaction, and to non-transactional statements, whether durability\_level is set or not. If use\_replica is enabled for a query, then this parameter also specifies the approximate time to wait before fetching data from a replica vBucket when the active vBucket is inaccessible. The value for this parameter is a string. Its format includes an amount and a mandatory unit, e.g. 10ms (10 milliseconds) or 0.5s (half a second). Valid units are: ns (nanoseconds) us (microseconds) ms (milliseconds) s (seconds) m (minutes) h (hours) Specify a duration of 0 or a negative duration to disable. When disabled, no timeout is applied and the KV operation runs for however long it takes. **Default:** "2.5s" **Example:** "10ms" | String | | **max\_parallelism**optional | Specifies the maximum parallelism for the query. The default value is the same as the number of partitions of the index selected for the query. The [node-level](#max-parallelism-srv) max-parallelism setting specifies the ceiling for this parameter for a single node. If the request-level parameter is zero or negative, the parallelism for the query is set to the node-level setting. If the request-level parameter is greater than zero and less than the node-level setting, the request-level parameter overrides the node-level setting. If the request-level parameter is greater than the node-level setting, the parallelism for the query is set to the node-level setting. In addition, the [cluster-level](#queryMaxParallelism) queryMaxParallelism setting specifies the ceiling for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster. To enable queries to run in parallel, you must specify the cluster-level queryMaxParallelism parameter, or specify the node-level max-parallelism parameter on all Query nodes. **Example:** 3 | Integer (int32) | | **memory\_quota**optional | Specifies the maximum amount of memory the request may use, in MB. Specify 0 (the default value) to disable. When disabled, there is no quota. 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](#memory-quota-srv) memory-quota setting specifies the ceiling for this parameter for a single node. If the node-level setting is zero (the default), the request-level parameter overrides the node-level setting. If the node-level setting is greater than zero, the request-level parameter is capped by the node-level setting. In addition, the [cluster-level](#queryMemoryQuota) queryMemoryQuota setting specifies the ceiling for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster. **Default:** 0 **Example:** 4 | Integer (int32) | | **metrics**optional | Specifies that metrics should be returned with query results. **Default:** true **Example:** false | Boolean | | **namespace**optional | Specifies the namespace to use. Currently, only the default namespace is available. **Example:** "default" | String | | **numatrs**optional | Reserved for future use. This parameter is ignored and has no effect. | Integer (int32) | | **pipeline\_batch**optional | Controls the number of items execution operators can batch for Fetch from the KV. The [node-level](#pipeline-batch-srv) pipeline-batch setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting, but only if it is lower than the node-level setting. In addition, the [cluster-level](#queryPipelineBatch) queryPipelineBatch setting specifies the default for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster. **Example:** 64 | Integer (int32) | | **pipeline\_cap**optional | Maximum number of items each execution operator can buffer between various operators. The [node-level](#pipeline-cap-srv) pipeline-cap setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting, but only if it is lower than the node-level setting. In addition, the [cluster-level](#queryPipelineCap) queryPipelineCap setting specifies the default for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster. **Example:** 1024 | Integer (int32) | | **prepared**optional | Required if statement not provided. The name of the prepared SQL++ statement to be executed. For examples, see [EXECUTE](../n1ql-language-reference/execute.html). If both prepared and statement are present and non-empty, an error is returned. **Example:** "\[127.0.0.1:8091\]pricy\_hotel" | String | | **preserve\_expiry**optional | Specifies whether documents should keep their current expiration setting when modified by a DML statement. If true, documents will keep any existing expiration setting when modified by a DML statement. If the DML statement explicitly specifies the document expiration, the statement overrides this parameter, and the expiration is changed. If false, document expiration is set to 0 when modified by a DML statement, unless the DML statement explicitly specifies the document expiration. Not supported for statements in a transaction. **Default:** false **Example:** true | Boolean | | **pretty**optional | Specifies the query results returned in pretty format. The [node-level](#pretty-srv) pretty setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting. **Example:** false | Boolean | | **profile**optional | Specifies if there should be a profile section returned with the request results. The valid values are: off — No profiling information is added to the query response. phases — The query response includes a profile section with stats and details about various phases of the query plan and execution. Three phase times will be included in the system:active\_requests and system:completed\_requests monitoring keyspaces. timings — Besides the phase times, the profile section of the query response document will include a full query plan with timing and information about the number of processed documents at each phase. This information will be included in the system:active\_requests and system:completed\_requests keyspaces. If profile is not set as one of the above values, then the profile setting does not change. The [node-level](#profile-srv) profile setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting. **Values:** "off", "phases", "timings" **Example:** "phases" | String | | **query\_context**optional | Specifies the namespace, bucket, and scope used to resolve partial keyspace references within the request. The query context may be a full path, containing namespace, bucket, and scope; or a relative path, containing just the bucket and scope. Currently, only the default namespace is available. If the namespace name is omitted, the default namespace in the current session is used. **Default:** "default:" **Example:** "default:travel-sample.inventory" | String | | **readonly**optional | Controls whether a query can change a resulting recordset. If readonly is true, then the following statements are not allowed: CREATE INDEX DROP INDEX INSERT MERGE UPDATE UPSERT When using GET requests, it's best to set readonly to true. **Default:** false **Example:** true | Boolean | | **scan\_cap**optional | Maximum buffered channel size between the indexer client and the Query Service for index scans. This parameter controls when to use scan backfill. Use 0 or a negative number to disable. Smaller values reduce GC, while larger values reduce indexer backfill. The [node-level](#scan-cap-srv) scan-cap setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting, but only if it is lower than the node-level setting. In addition, the [cluster-level](#queryScanCap) queryScanCap setting specifies the default for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster. **Example:** 1024 | Integer (int32) | | **scan\_consistency**optional | Specifies the consistency guarantee or constraint for index scanning. The valid values are: not\_bounded — No timestamp vector is used in the index scan. This is the fastest mode, because it avoids the costs of obtaining the vector and waiting for the index to catch up to the vector. at\_plus — This implements bounded consistency. When scan consistency is set to at\_plus, you must also specify the scan\_vector parameter for queries using a single keyspace, or the scan\_vectors parameter for queries using multiple keyspaces. This is used as a lower bound for the statements in the request. You can use this setting to implement read-your-own-writes (RYOW). request\_plus — This implements strong consistency per request. Before processing the request, a current vector is obtained. The vector is used as a lower bound for the statements in the request. If there are DML statements in the request, RYOW is also applied within the request. (If request\_plus is specified in a query that runs during a failover of an index node, the query waits until the rebalance operation completes and the index data has rebalanced before returning a result.) statement\_plus — This implements strong consistency per statement. Before processing each statement, a current vector is obtained and used as a lower bound for that statement. Values are case-insensitive. If the request contains a BEGIN TRANSACTION statement, or a DML statement with the tximplicit parameter set to true, then this parameter sets the transactional scan consistency. For more information, see [Transactional Scan Consistency](#transactional-scan-consistency). The default transactional scan consistency is RYOW for each statement within the transaction. If you want to disable RYOW for a statement within the transaction, set scan\_consistency for that statement to not\_bounded. **Values:** "not\_bounded", "at\_plus", "request\_plus", "statement\_plus" **Default:** "not\_bounded" **Example:** "at\_plus" | String | | **scan\_vector**optional | Specifies the lower bound vector timestamp for a single keyspace when using at\_plus scan consistency. The scan vector may be full or sparse. A full scan vector is an array of \[value, guard\] entries, giving an entry for every vBucket in the system. A sparse scan vector is an object mapping \[value, guard\] entries to specific vBuckets. The name of each property in the object is a vBucket number (a string). | [Scan Vector](#RequestScanVector) | | **scan\_vectors**optional | Specifies the lower bound vector timestamps for multiple keyspaces when using at\_plus scan consistency. An object mapping scan vectors to keyspaces. The name of each property in the object is a keyspace name. | [Scan Vectors](#RequestScanVectors) | | **scan\_wait**optional | Can be supplied with scan\_consistency values of request\_plus, statement\_plus and at\_plus. Specifies the maximum time the client is willing to wait for an index to catch up to the vector timestamp in the request. Specifies how much time the client is willing to wait for the indexer to satisfy the required scan\_consistency and scan\_vector criteria. After receiving the scan request, if the indexer is unable to catch up within the scan\_wait time and start the scan, the indexer aborts with an error and the scan fails. Its format includes an amount and a mandatory unit, e.g. 10ms (10 milliseconds) or 0.5s (half a second). Valid units are: ns (nanoseconds) us (microseconds) ms (milliseconds) s (seconds) m (minutes) h (hours) Specify 0 or a negative integer to disable. **Default:** "" **Example:** "30m" | String (duration) | | **signature**optional | Include a header for the results schema in the response. **Default:** true **Example:** false | Boolean | | **sort\_projection**optional | If true, causes statement projection terms to be sorted alphabetically. If false (the default), statement projection terms are returned in the order specified by the query. **Default:** false **Example:** true | Boolean | | **statement**optional | Required if prepared not provided. Any valid SQL++ statement for a POST request, or a read-only SQL++ statement (SELECT, EXPLAIN) for a GET request. If both prepared and statement are present and non-empty, an error is returned. When specifying the request parameters as form data, the statement may not contain an unescaped semicolon (;). If it does, the Query Service responds with error 1040\. To avoid this, either URL-encode the semicolon as %3B, or just omit the semicolon if possible. This restriction does not apply when specifying the request parameters in JSON format. **Example:** "SELECT \* FROM \`travel-sample\`.inventory.hotel LIMIT 1" | String | | **timeout**optional | Maximum time to spend on the request before timing out (s). The value for this parameter is a string. Its format includes an amount and an optional unit: for example, 10ms (10 milliseconds) or 0.5s (half a second). If not specified, the default unit is s (seconds). Valid units are: ns (nanoseconds) us (microseconds) ms (milliseconds) s (seconds) m (minutes) h (hours) Specify a duration of 0 or a negative duration to disable. When disabled, no timeout is applied and the request runs for however long it takes. If tximplicit or txid is set, this parameter is ignored. The request inherits the remaining time of the transaction as timeout. The [node-level](#timeout-srv) timeout setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting. However, if the node-level setting is greater than 0, the timeout for the query is limited to the node-level setting. In addition, the [cluster-level](#queryTimeout) queryTimeout setting specifies the default for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster. **Example:** "30m" | String (duration) | | **txdata**optional | Transaction data. For internal use only. | Object | | **txid**optional | Required for statements within a transaction. Transaction ID. Specifies the transaction to which a statement belongs. For use with DML statements within a transaction, rollbacks, and commits. The transaction ID should be the same as the transaction ID generated by the BEGIN TRANSACTION statement. The transaction must be active and non-expired. **Example:** "d81d9b4a-b758-4f98-b007-87ba262d3a51" | UUID (UUID) | | **tximplicit**optional | Specifies that a DML statement is a singleton transaction. When this parameter is true, the Query Service starts a transaction and executes the statement. If execution is successful, the Query Service commits the transaction; otherwise the transaction is rolled back. The statement may not be part of an ongoing transaction. If the txid request-level parameter is set, the tximplicit parameter is ignored. **Default:** false **Example:** true | Boolean | | **txstmtnum**optional | Transaction statement number. The transaction statement number must be a positive integer, and must be higher than any previous transaction statement numbers in the transaction. If the transaction statement number is lower than the transaction statement number for any previous statement, an error is generated. **Example:** 10 | Integer (int32) | | **txtimeout**optional | Maximum time to spend on a transaction before timing out. Only applies to BEGIN TRANSACTION statements, or DML statements for which tximplicit is set. For other statements, it's ignored. Within a transaction, the request-level timeout parameter is ignored. The transaction timeout clock starts when the BEGIN WORK statement is successful. Once the transaction timeout is reached, no statement is allowed to continue in the transaction. The value for this parameter is a string. Its format includes an amount and a mandatory unit, e.g. 10ms (10 milliseconds) or 0.5s (half a second). Valid units are: ns (nanoseconds) us (microseconds) ms (milliseconds) s (seconds) m (minutes) h (hours) Specify a duration of 0 to disable. When disabled, the request-level timeout is set to the default. The default is "15s" for cbq files or scripts, "2m" for interactive cbq sessions or redirected input. The [node-level](#txtimeout-srv) txtimeout setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting. However, if the node-level setting is greater than 0, the transaction timeout for the query is limited to the node-level setting. In addition, the [cluster-level](#queryTxTimeout) queryTxTimeout setting specifies the default for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster. **Example:** "30m" | String (duration) | | **use\_cbo**optional | Specifies whether the cost-based optimizer is enabled. The [node-level](#use-cbo-srv) use-cbo setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting. In addition, the [cluster-level](#queryUseCBO) queryUseCBO setting specifies the default for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster. **Example:** true | Boolean | | **use\_fts**optional | [ENTERPRISE EDITION](https://www.couchbase.com/products/editions) Specifies that the query should use a Search index. If the query contains a USING FTS hint, that takes priority over this parameter. If the query does not contain a USING FTS hint, and this parameter is set to true, all Search indexes are considered for the query. If a qualified Search index is available, it's selected for the query. If none of the available Search indexes are qualified, the available GSI indexes are considered instead. For more information, see [Flex Indexes](../n1ql-language-reference/flex-indexes.html). **Default:** false **Example:** true | Boolean | | **use\_replica**optional | Specifies whether a query can fetch data from a replica vBucket if active vBuckets are inaccessible. The possible values are: off — read from replica is disabled for this request. on — read from replica is enabled for this request, unless it has been disabled for all requests at node level. unset — read from replica is specified by the node-level setting. If the node-level setting is also unset, read from replica is disabled for this request. 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. You cannot currently start KV range scans 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. The [node-level](#use-replica-srv) use-replica setting specifies the default for this property for a single node. The request-level parameter usually overrides the node-level setting. However, when the node-level setting is off, the request-level parameter cannot enable the property. In addition, the [cluster-level](#queryUseReplica) queryUseReplica setting specifies the default for this property for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster. **Values:** "off", "on", "unset" **Default:** "unset" **Example:** "on" | String | | **<$identifier>**additionalproperty | Supplies the value for a named parameter in the statement. Applicable if the statement or prepared statement contains 1 or more named parameters. The name of this property consists of two parts: The $ character or the @ character. An identifier that specifies the name of the parameter. This must start with an alpha character, followed by one or more alphanumeric characters. The value of the named parameter can be any JSON value. For more information, see [Named Parameters and Positional Parameters](#section%5Fsrh%5Ftlm%5Fn1b). **Nullable:** yes **Example:** LAX | Any Type | **Credentials** | Property | | Schema | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | **user**optional | An identity for authentication. Bucket names may be prefixed with local:, and admin names may be prefixed with admin:. **Example:** "local:bucket-name" | String | | **pass**optional | A password for authentication. **Example:** "password" | String (password) | **Scan Vector** | One of …​ | | Schema | | --------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | | An array of \[value, guard\] entries, giving an entry for every vBucket in the system. | [Full Scan Vector](#RequestScanVectorFull) | | or | An object providing entries for specific vBuckets, mapping a vBucket number (a string) to each \[value, guard\] entry. | [Sparse Scan Vector](#RequestScanVectorSparse) | **Full Scan Vector** | Item | | Schema | | ---- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | …​ | A nested array containing two elements, the value and the guard. **Minimum items:** 2 **Maximum items:** 2 | [Value-Guard Entry](#RequestScanVectorValueGuard) | **Sparse Scan Vector** | Property | | Schema | | ------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | ****additionalproperty | A nested array containing two elements, the value and the guard. **Minimum items:** 2 **Maximum items:** 2 | [Value-Guard Entry](#RequestScanVectorValueGuard) | **Value-Guard Entry** | Item | | Schema | | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | …​ | The first item is the value. This is a vBucket's sequence number (a JSON number). The second item is the guard. This is a vBucket's UUID (a string). **Nullable:** yes | Any Type | **Scan Vectors** | Property | | Schema | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | ****additionalproperty | Specifies the lower bound vector timestamp for a single keyspace when using at\_plus scan consistency. The scan vector may be full or sparse. A full scan vector is an array of \[value, guard\] entries, giving an entry for every vBucket in the system. A sparse scan vector is an object mapping \[value, guard\] entries to specific vBuckets. The name of each property in the object is a vBucket number (a string). | [Scan Vector](#RequestScanVector) | ##### Transactional Scan Consistency If the request contains a `BEGIN TRANSACTION` statement, or a DML statement with the [tximplicit](#tximplicit) parameter set to `true`, then the [scan\_consistency](#scan%5Fconsistency) parameter sets the transactional scan consistency. If you specify a transactional scan consistency of `request_plus`, `statement_plus`, or `at_plus`, or if you specify no transactional scan consistency, the transactional scan consistency is set to `request_plus`; otherwise, the transactional scan consistency is set as specified. __Table 9\. Transactional scan consistency__ | Scan consistency at start of transaction | Transactional scan consistency | | ---------------------------------------- | ------------------------------ | | Not set | request\_plus | | not\_bounded | not\_bounded | | request\_plus statement\_plus at\_plus | request\_plus | Any DML statements within the transaction that have no scan consistency set will inherit from the transactional scan consistency. Individual DML statements within the transaction may override the transactional scan consistency. If you specify a scan consistency of `not_bounded` for a statement within the transaction, the scan consistency for the statement is set as specified. When you specify a scan consistency of `request_plus`, `statement_plus`, or `at_plus` for a statement within the transaction, the scan consistency for the statement is set to `request_plus`. However, `request_plus` consistency is not supported for statements using a full-text index. If any statement within the transaction uses a full-text index, by means of the SEARCH function or the Flex Index feature, the scan consistency is set to `not_bounded` for the duration of the Full-Text Search. __Table 10\. Overriding the transactional scan consistency__ | Scan consistency for statement within transaction | Inherited scan consistency | | ------------------------------------------------- | ----------------------------------------------------------------- | | Not set | Transactional scan consistency(not\_bounded for Full-Text Search) | | not\_bounded | not\_bounded | | request\_plus statement\_plus at\_plus | request\_plus(not\_bounded for Full-Text Search) | ## [](#section%5Fsrh%5Ftlm%5Fn1b)Named Parameters and Positional Parameters You can add placeholder parameters to a statement, so that you can safely supply variable values when you run the statement. A placeholder parameter may be a named parameter or a positional parameter. * To add a named parameter to a query, enter a dollar sign `$` or an at sign `@` followed by the parameter name. * To add a positional parameter to a query, enter a dollar sign `$` or an at sign `@` followed by the number of the parameter, or enter a question mark `?`. To run a query containing placeholder parameters, you must supply values for the parameters. * You can use [additional](#identifier) request-level parameters to supply the values for named parameters. The name of this property is a dollar sign `$` or an at sign `@` followed by the parameter name. * The [args](#args) request-level parameter enables you to supply a list of values for positional parameters. You can supply the values for placeholder parameters using any of the methods used to specify [request-level parameters](#section%5Fnnj%5Fsjk%5Fk1b). ### [](#examples)Examples To try the examples in this section, set the query context to the `inventory` scope in the travel sample dataset. For more information, see [Query Context](../n1ql-intro/queriesandresults.md#query-context). Example 1\. Named Parameters * Web Console * Command Line * REST API The following query uses named parameter placeholders. The parameter values are supplied using the Run-Time Preferences window. __Named Parameters__ | **name** | $country | **value** | "France" | | -------- | --------- | --------- | -------- | | **name** | $altitude | **value** | 500 | ```sqlpp SELECT COUNT(*) FROM airport WHERE country = $country AND geo.alt > @altitude; ``` The named parameters and named parameter placeholders in this example use a mixture of `@` and `$` symbol prefixes. You can use either of these symbols as preferred. The following query uses named parameter placeholders. The parameter values are supplied using the cbq shell. ```sqlpp \SET -@country "France"; \SET -$altitude 500; SELECT COUNT(*) FROM airport WHERE country = $country AND geo.alt > @altitude; ``` The named parameters and named parameter placeholders in this example use a mixture of `@` and `$` symbol prefixes. You can use either of these symbols as preferred. The following query uses named parameter placeholders. The parameter values are supplied using the Query Service REST API. --- ```sh curl -v $BASE_URL/query/service \ -d 'statement=SELECT COUNT(*) FROM airport WHERE country = $country AND geo.alt > @altitude & query_context=travel-sample.inventory & $country="France" & $altitude=500' \ -u $USER:$PASSWORD ``` The named parameters and named parameter placeholders in this example use a mixture of `@` and `$` symbol prefixes. You can use either of these symbols as preferred. Example 2\. Numbered Positional Parameters * Web Console * Command Line * REST API The following query uses numbered positional parameter placeholders. The parameter values are supplied using the Run-Time Preferences window. __Positional Parameters__ | **$1** | "France" | | ------ | -------- | | **$2** | 500 | ```sqlpp SELECT COUNT(*) FROM airport WHERE country = $1 AND geo.alt > @2; ``` In this case, the first positional parameter value is used for the placeholder numbered `$1`, the second positional parameter value is used for the placeholder numbered `@2`, and so on. The numbered positional parameter placeholders in this example use a mixture of `@` and `$` symbol prefixes. You can use either of these symbols as preferred. The following query uses numbered positional parameter placeholders. The parameter values are supplied using the cbq shell. ```sqlpp \SET -args ["France", 500]; SELECT COUNT(*) FROM airport WHERE country = $1 AND geo.alt > @2; ``` In this case, the first positional parameter value is used for the placeholder numbered `$1`, the second positional parameter value is used for the placeholder numbered `@2`, and so on. The numbered positional parameter placeholders in this example use a mixture of `@` and `$` symbol prefixes. You can use either of these symbols as preferred. The following query uses numbered positional parameter placeholders. The parameter values are supplied using the Query Service REST API. --- ```sh curl -v $BASE_URL/query/service \ -d 'statement=SELECT COUNT(*) FROM airport WHERE country = $1 AND geo.alt > @2 & query_context=travel-sample.inventory & args=["France", 500]' \ -u $USER:$PASSWORD ``` In this case, the first positional parameter value is used for the placeholder numbered `$1`, the second positional parameter value is used for the placeholder numbered `@2`, and so on. The numbered positional parameter placeholders in this example use a mixture of `@` and `$` symbol prefixes. You can use either of these symbols as preferred. Example 3\. Unnumbered Positional Parameters * Web Console * Command Line * REST API The following query uses unnumbered positional parameter placeholders. The parameter values are supplied using the Run-Time Preferences window. __Positional Parameters__ | **$1** | "France" | | ------ | -------- | | **$2** | 500 | ```sqlpp SELECT COUNT(*) FROM airport WHERE country = ? AND geo.alt > ?; ``` In this case, the first positional parameter value is used for the first `?` placeholder, the second positional parameter value is used for the second `?` placeholder, and so on. The following query uses unnumbered positional parameter placeholders. The parameter values are supplied using the cbq shell. ```sqlpp \SET -args ["France", 500]; SELECT COUNT(*) FROM airport WHERE country = ? AND geo.alt > ?; ``` In this case, the first positional parameter value is used for the first `?` placeholder, the second positional parameter value is used for the second `?` placeholder, and so on. The following query uses unnumbered positional parameter placeholders. The parameter values are supplied using the Query Service REST API. --- ```sh curl -v $BASE_URL/query/service \ -d 'statement=SELECT COUNT(*) FROM airport WHERE country = ? AND geo.alt > ? & query_context=travel-sample.inventory & args=["France", 500]' \ -u $USER:$PASSWORD ``` In this case, the first positional parameter value is used for the first `?` placeholder, the second positional parameter value is used for the second `?` placeholder, and so on. For more information and examples, including examples using SDKs, see the [Prepare Statements for Reuse](../../guides/prep-statements.md) guide. ## [](#related-links)Related Links * For more information about the SQL++ REST API, see [Query Service REST API](../../n1ql-rest-query/index.md). * For more information about the Admin REST API, see [Query Admin REST API](../../n1ql-rest-admin/index.md). * For more information about the Query Settings API, see [Query Settings REST API](../../n1ql-rest-settings/index.md). * For more information about API content and settings, see [REST API reference](../../rest-api/rest-intro.md).