Settings and Parameters

You can configure the Query service using cluster-level query settings, node-level query settings, and request-level query parameters.

There are three ways of configuring the Query service. You can specify cluster-level settings for all nodes running the Query service in the cluster. You can specify node-level settings for a single node running the Query service. You can also specify parameters for individual requests. Cluster-level query settings, node-level query settings, and request-level parameters must be set and used in different ways.

Table 1. Comparison of Query Settings and Parameters
	Setting Per	Set By	Set On	Set Via
Cluster-level query settings	Cluster	The administrator at the system level	Server side	The CLI, cURL statements, or the UI
Node-level query settings	Service Node	The administrator at the system level	Server side	cURL statements
Request-level parameters	Request (statement)	Each user	Client side	`cbq` command-line parameters, cURL statements, or client programming

Cluster-level settings and node-level settings are collectively referred to as service-level settings.

Query Setting Levels and Equivalents

Some query settings are cluster-level, node-level, or request-level only, while some apply to more than one level with slightly different names.

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, you should note that the node-level setting may be overwritten by subsequent changes at the cluster-level. In particular, specifying query settings via the CLI or the UI makes changes at the cluster-level.

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.

Table 2. Single-Level Settings
Cluster-Level Only Settings	Node-Level Only Settings	Request-Level Only Parameters
queryTmpSpaceDir queryTmpSpaceSize queryCurlWhitelist	auto-prepare completed cpuprofile debug distribute functions-limit keep-alive-length max-index-api memprofile mutexprofile plus-servicers request-size-cap servicers	args auto_execute batch_args batch_named_args client_context_id compression creds durability_level encoded_plan (deprecated) encoding format kvtimeout metrics namespace prepared query_context readonly scan_consistency scan_vector scan_vectors scan_wait signature statement txid txstmtnum tximplicit txdata use_fts $<identifier>

Table 3. Settings for Cluster-Level and Node-Level
Cluster-Level Name	Node-Level Name	Request-Level Name
queryCleanupClientAttempts queryCleanupLostAttempts queryCleanupWindow queryCompletedLimit queryCompletedThreshold queryLogLevel queryN1qlFeatCtrl queryPreparedLimit	cleanupclientattempts cleanuplostattempts cleanupwindow completed-limit completed-threshold loglevel n1ql-feat-ctrl prepared-limit	N/A

Table 4. Settings for Node-Level and Request-Level
Cluster-Level Name	Node-Level Name	Request-Level Name
N/A	atrcollection controls pretty profile	atrcollection controls pretty profile

Table 5. Settings for Cluster-Level, Node-Level, and Request-Level
Cluster-Level Name	Node-Level Name	Request-Level Name
queryMaxParallelism queryMemoryQuota queryNumAtrs queryPipelineBatch queryPipelineCap queryScanCap queryTimeout queryTxTimeout queryUseCBO	max-parallelism memory-quota numatrs pipeline-batch pipeline-cap scan-cap timeout txtimeout use-cbo	max_parallelism memory_quota numatrs pipeline_batch pipeline_cap scan_cap timeout txtimeout use_cbo

Cluster-Level Query Settings

To set a cluster-level query setting, use the Query Settings REST API (/settings/querySettings endpoint) with a cURL statement, or the Advanced Query Settings in the Couchbase Web Console. You can also set all of the cluster-level query settings, except for the CURL() access list settings, using the setting-query command.

The table below contains details of all cluster-level query settings.

Name Description 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 is forced to.

The node-level 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 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 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 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.

Refer to Configure the Completed Requests for more information and examples.

The node-level 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)

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.

Refer to Configure the Completed Requests for more information and examples.

The node-level 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 — Doesn’t write anything.

The node-level 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.
Default : "INFO"
Example : "DEBUG"

enum (DEBUG, TRACE, INFO, WARN, ERROR, SEVERE, NONE)

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 Community Edition, the number of allowed cores cannot be greater than 4. In Enterprise Edition, there is no limit to the number of allowed cores.)

The node-level 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_parallelism parameter. If a request includes this parameter, it will be capped by the node-level max-parallelism setting.

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.

Refer to Max Parallelism for more information.
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.

Within a transaction, this setting enforces the memory quota for the transaction. The transaction memory quota tracks only the delta table and the transaction log (approximately).

The node-level 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_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

N1QL feature control. This setting is provided for technical support only.

The node-level 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)

queryNumAtrs
optional

Specifies the total number of active transaction records for all Query nodes in the cluster.

The node-level 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.

In addition, there is a request-level numatrs parameter. If a request includes this parameter, it will be capped by the node-level numatrs setting.
Default : 1024
Minimum value (exclusive) : 0
Example : 512

integer (int32)

queryPipelineBatch
optional

Controls the number of items execution operators can batch for Fetch from the KV.

The node-level 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_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 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_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 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 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_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 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 parameter specifies this property per request. The minimum of that and the node-level timeout setting is applied.
Default : 0
Example : 500000000

integer (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 parameter is set. For all other requests, it is 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 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 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 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_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

queryCurlWhitelist
optional

An object which determines which URLs may be accessed by the CURL() function.

Access

Access

Name Description Schema

Name	Description	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. Default : `false`	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`. Note that 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`. Note that each URL must include the port, protocol, and all other components of the URL.	< string > array

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.
Default : false

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.

Note that 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.

Note that each URL must include the port, protocol, and all other components of the URL.

< string > array

Node-Level Query Settings

To set a node-level query setting, use the Admin REST API (/admin/settings endpoint) with a cURL statement.

These settings cannot be set by cbq.

To see a list of the current Query Settings, while the Query Service is running, enter:

$ curl http://localhost:8093/admin/settings -u user:pword

This will output the entire list of node-level query settings:

{
  "atrcollection": "",
  "auto-prepare": false,
  "cleanupclientattempts": true,
  "cleanuplostattempts": true,
  "cleanupwindow": "1m0s",
  "completed": {
    "aborted": null,
    "threshold": 1000
  },
  "completed-limit": 4000,
  "completed-threshold": 1000,
  "controls": false,
  "cpuprofile": "",
  "debug": false,
  "functions-limit": 16384,
  "keep-alive-length": 16384,
  "loglevel": "INFO",
  "max-index-api": 4,
  "max-parallelism": 1,
  "memory-quota": 0,
  "memprofile": "",
  "mutexprofile": false,
  "n1ql-feat-ctrl": 76,
  "numatrs": 1024,
  "pipeline-batch": 16,
  "pipeline-cap": 512,
  "plus-servicers": 16,
  "prepared-limit": 16384,
  "pretty": false,
  "profile": "off",
  "request-size-cap": 67108864,
  "scan-cap": 512,
  "servicers": 4,
  "timeout": 0,
  "txtimeout": "0s",
  "use-cbo": true
}

To output to a file for editing multiple settings at a single time, add the -o filename option. For example:

$ curl http://localhost:8093/admin/settings -u user:pword -o ./query_settings.json

The table below contains details of all node-level query settings.

Name Description Schema

atrcollection
optional

Specifies the collection where active transaction records 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 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 N1QL request is submitted, whether the PREPARE statement is included or not.

Refer to Auto-Prepare for more information.
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 is forced to.

The cluster-level 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 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

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 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.

Refer to Configure the Completed Requests for more information and examples.
Example : { "user" : "marco", "error" : 12003 }

Logging parameters

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.

Refer to Configure the Completed Requests for more information and examples.

The cluster-level 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-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.

Refer to Configure the Completed Requests for more information and examples.

The cluster-level 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.

If the request qualifies for caching, these values will also be cached in the completed_requests system keyspace.

The request-level 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.

To stop cpuprofile, run with the empty setting of "".

If cpuprofile is left running too long, it can slow the system down as its file size increases.

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 is 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 — Doesn’t write anything.

The cluster-level 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.
Default : "INFO"
Example : "DEBUG"

enum (DEBUG, TRACE, INFO, WARN, ERROR, SEVERE, NONE)

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.

The cluster-level 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_parallelism parameter. If a request includes this parameter, it will be capped by the node-level max-parallelism setting.

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.

Refer to Max Parallelism for more information.
Default : 1
Example : 0

integer (int32)

memory-quota
optional

Specifies the maximum amount of memory a request may use on this node, in MB. Note that the overall node memory quota is this setting multiplied by the node-level servicers setting.

Specify 0 (the default value) to disable. When disabled, there is no quota.

Within a transaction, this setting enforces the memory quota for the transaction. The transaction memory quota tracks only the delta table and the transaction log (approximately).

The cluster-level 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_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.

To stop memprofile, run with the empty setting of "".

If memprofile is left running too long, it can slow the system down as its file size increases.

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

N1QL feature control. This setting is provided for technical support only.

The cluster-level 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

integer (int32)

numatrs
optional

Specifies the total number of active transaction records.

The cluster-level 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.

In addition, the request-level numatrs parameter specifies this property per request. The minimum of that and the node-level numatrs setting is applied.

string

pipeline-batch
optional

Controls the number of items execution operators can batch for Fetch from the KV.

The cluster-level 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.

integer (int32)

pipeline-cap
optional

Maximum number of items each execution operator can buffer between various operators.

The cluster-level 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.

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 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 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.

If profile is not set as one of the above values, then the profile setting does not change.

Refer to Monitoring and Profiling Details for more information and examples.

The request-level profile parameter specifies this property per request. If a request does not include this parameter, the node-level profile setting will be used.
Default : "off"
Example : "phases"

enum (off, phases, timings)

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 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_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.

Note that the overall node memory quota is this setting multiplied by the node-level memory-quota setting.
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 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.

integer (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 parameter is set. For all other requests, it is 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 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 parameter specifies this property per request. The minimum of that and the node-level txtimeout setting is applied.
Default : 0
Example : 500000000

integer (int64)

use-cbo
optional

Specifies whether the cost-based optimizer is enabled.

The cluster-level 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.

boolean

Logging parameters

Name Description Schema

Name	Description	Schema
aborted optional	If true, all requests that generate a panic are logged. 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. Refer to the request-level `client_context_id` parameter for more information.	string
error optional	An error number. If specified, all completed queries returning this error number are logged. Example : `12003`	integer (int32)
tag optional	A unique string which tags a set of qualifiers. Refer to Configure the Completed Requests for more information. 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 node-level `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

aborted
optional

If true, all requests that generate a panic are logged.
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.

Refer to the request-level client_context_id parameter for more information.

string

error
optional

An error number. If specified, all completed queries returning this error number are logged.
Example : 12003

integer (int32)

tag
optional

A unique string which tags a set of qualifiers.

Refer to Configure the Completed Requests for more information.
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 node-level 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

Request-Level Parameters

To set a request-level parameter, use the N1QL REST API (/query/service endpoint) with a cURL statement, or the cbq command, or a client program.

While cbq is a sandbox to test code on your local machine, your production query settings are set with the cURL commands on your server.

The table below contains details of all request-level parameters, along with examples.

Name Description Schema

args
Optional

If the statement has 1 or more positional parameters, this parameter needs to be in the request; this is an array of JSON values, one for each positional parameter in the statement.

Positional parameters apply to prepared also.

Refer to Named Parameters VS. Positional Parameters for details.

Example

cbq> \set -args ["LAX", 6];

array

atrcollection
Optional

Specifies the collection where the active transaction record (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 node-level atrcollection setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting.

Example

cbq> \set -atrcollection "default:`travel-sample`.transaction.test";

string

auto_execute
Optional

Specifies that prepared statements should be executed automatically as soon as they are created. This saves you from having to make two separate requests in cases where you want to prepare a statement and execute it immediately.

Refer to Auto-Execute for more information.

Default

false

Example

cbq> \set -auto_execute true;

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=prepare select * from default&auto_execute=true'

boolean

batch_args
Optional

Applies to POST requests only, containing UPDATE, INSERT, DELETE statements (DML statements) with positional parameters.

Example

INSERT INTO location (id, name) VALUES ($1, $2)

These require the values to be given in batch_args, which contains an array of arrays.

The inner arrays need to match the positional parameters in the statement.

array of arrays

batch_named_args
Optional

Applies to POST requests only, containing UPDATE, INSERT, DELETE statements (DML statements) with named parameters.

Example

INSERT INTO location (id, name) VALUES ($id, $n)

These require the values to be given in batch_named_args, which contains an array of objects.

The keys in each object need to match the named parameters in the statement.

array of objects

client_context_id
Optional

A piece of data supplied by the client that is echoed in the response, if present. N1QL is agnostic about the content of this parameter; it is 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.

Default

"NONE"

Example

cbq> \set -compression "zip";

enum (ZIP, RLE, LZMA, LZO, NONE)

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 setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting.

Example

cbq> \set -controls true;

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&controls=true'

boolean

creds
Optional

Specify the login credentials in the form of user:password.

You can specify credentials for different keyspaces by separating them with a comma.

If credentials are supplied in the request header, then creds is ignored since HTTP Basic Authentication takes precedence and overrides creds.

Example

cbq> \set -creds travel-sample user:pword, beer-sample user:pword;

array

durability_level
Optional

The level of durability 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. For all other statements it is ignored.

If not specified, the default durability level is "majority". Set the durability level to "none" or "" to specify no durability.

Default

"majority"

Example

cbq> \set -durability_level "none";

$ curl http://localhost:8093/query/service \
-u Administrator:password \
-H 'Content-Type: application/json' \
-d '{
  "statement": "START TRANSACTION",
  "durability_level": "none"
}'

enum ("", none, majority, majorityAndPersistActive, persistToMajority)

encoded_plan
Optional

In Couchbase Server 6.5 and later, this parameter is ignored and has no effect. It is 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.

Default

"JSON"

Example

cbq> \set -format "XML";

enum (JSON, XML, CSV, TSV)

max_parallelism
Optional

Specifies the maximum parallelism for the query.

The node-level 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 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.

Default

The same as the number of partitions of the index selected for the query.

Example

cbq> \set -max_parallelism 3;

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&max_parallelism=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.

Within a transaction, this parameter enforces the memory quota for the transaction. The transaction memory quota tracks only the delta table and the transaction log (approximately).

The node-level 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 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

cbq> \set -memory_quota 4;

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&memory_quota=4'

integer (int32)

kvtimeout
Optional

The maximum time to wait for a KV operation before timing out. Only applies to statements within a 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 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

cbq> \set -kvtimeout "10ms";

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&kvtimeout=10ms'

string

metrics
Optional

Specifies that metrics should be returned with query results.

Default

true

Example

cbq> \set -metrics false;

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&metrics=false'

boolean

namespace
Optional

Specifies the namespace to use.

Example

cbq> \set -namespace default;

string

numatrs
Optional

Specifies the total number of active transaction records. Must be a positive integer.

The node-level numatrs 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 queryNumAtrs 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.

Default

1024

Example

cbq> \set -numatrs 512;

integer (int32)

pipeline_batch
Optional

Controls the number of items execution operators can batch for Fetch from the KV.

The node-level 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 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

cbq> \set -pipeline_batch 64;

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&pipeline_batch=64'

integer (int32)

pipeline_cap
Optional

Maximum number of items each execution operator can buffer between various operators.

The node-level 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 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

cbq> \set -pipeline_cap 1024;

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&pipeline_cap=1024'

integer (int32)

prepared
Required if statement not provided

The prepared form of the N1QL statement to be executed.

If both prepared and statement are present and non-empty, an error is returned.

Example

Prepare the query result of the most expensive hotel:

$ curl -v http://localhost:8093/query/service -d 'statement=PREPARE pricy_hotel FROM SELECT MAX(price) FROM `travel-sample`.inventory.hotel;'

Response:

{
  "requestID": "b7f03c4e-06f6-4d23-bd14-b5c8ecfe0e2e",
  "signature": "json",
  "results": [
    {"encoded_plan":"H4sIAAAAAAAA/wEAAP//AAAAAAAAAAA=",
    "featureControls":12,
    "indexApiVersion":3,
    "name":"[127.0.0.1:8091]pricy_hotel",
...
    }
  ]
}

Execute the prepared statement:

$ curl -v http://localhost:8093/query/service -H "Content-Type: application/json" -d '{ "prepared":"[127.0.0.1:8091]pricy_hotel" }'

string

pretty
Optional

Specifies the query results returned in pretty format.

The node-level pretty setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting.

Example

cbq> \set -pretty false;

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&pretty=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 setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting.

Example

cbq> \set -profile "phases";

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&profile=phases'

enum (off, phases, timings)

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

cbq> \set -query_context "default:travel-sample.inventory";

cbq> \set -query_context "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

cbq> \set -readonly 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 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 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

cbq> \set -scan_cap 1024;

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&scan_cap=1024'

integer (int32)

scan_consistency
Optional

Specify the consistency guarantee/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. The request includes a scan_vector parameter and value, which is used as a lower bound. This can be used 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.
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.

The default behavior is RYOW within the request, however, if you want to disable RYOW within a request, add a separate request_consistency parameter that can be set to not_bounded.

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. Refer to Transactional Scan Consistency for details.

Default

"not_bounded"

Example

cbq> \set -scan_consistency "at_plus";

enum (not_bounded, at_plus, request_plus, statement_plus)

scan_vector
Required if scan_consistency is at_plus and scan_vectors not provided

Specify the lower bound vector timestamp for one keyspace when using at_plus scan consistency.

Scan vectors are built of two-element [value, guard] entries:

value: a vBucket’s sequence number (a JSON number)
guard: a vBucket’s UUID (a string)

Scan vectors have two forms:

Full scan vector: an array of [value, guard] entries, giving an entry for every vBucket in the system.
Sparse scan vectors: an object providing entries for specific vBuckets, mapping a vBucket number (a string) to each [value, guard] entry.

scan_vector can only be used if the query uses at most one keyspace; if it is used for a query referencing more than one keyspace, the query will fail with an error.

For queries referencing multiple keyspaces, use scan_vectors.

Example

scan_vector={ "5 ": [5409393,"VB5ID"], "19": [47574574, "VB19ID"] }

array, object

scan_vectors
Required if scan_consistency is at_plus and scan_vector not provided

A map from keyspace names to scan vectors. See scan_vector.

The scan vectors can be Full or Sparse.

object

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.

If an index has to catch up, and the scan_wait time is exceeded while waiting, an error is returned.

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

cbq> \set -scan_wait "30m";

string (duration)

signature
Optional

Include a header for the results schema in the response.

Default

true

Example

cbq> \set -signature false;

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&signature=false'

boolean

statement
Required if prepared not provided

Any valid N1QL statement for a POST request, or a read-only N1QL statement (SELECT, EXPLAIN) for a GET request.

If both prepared and statement are present and non-empty, an error is returned.

string

timeout
Optional

Maximum time to spend on the request before timing out.

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 request runs for however long it takes.

If txid or tximplicit is set, this parameter is ignored. The request inherits the remaining time of the transaction as timeout.

The node-level 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 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

cbq> \set -timeout "30m";

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&timeout=30m'

string (duration)

txdata
Optional

Transaction data. For internal use only.

object

txid
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

cbq> \set -txid d81d9b4a-b758-4f98-b007-87ba262d3a51;

$ curl http://localhost:8093/query/service \
-u Administrator:password \
-H 'Content-Type: application/json' \
-d '{
  "statement": "select * from default;",
  "txid": "d81d9b4a-b758-4f98-b007-87ba262d3a51"
}'

string (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

cbq> \set -tximplicit true;

$ curl http://localhost:8093/query/service \
-u Administrator:password \
-H 'Content-Type: application/json' \
-d '{
  "statement": "select * from default;",
  "tximplicit": 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

cbq> \set -txstmtnum 10;

$ curl http://localhost:8093/query/service \
-u Administrator:password \
-H 'Content-Type: application/json' \
-d '{
  "statement": "select * from default;",
  "txstmtnum": 10,
  "txid": "d81d9b4a-b758-4f98-b007-87ba262d3a51"
}'

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 is 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 node-level 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 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.

Default

"15s" for cbq files or scripts
"2m" for interactive cbq sessions or redirected input

Example

cbq> \set -txtimeout "30m";

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=BEGIN TRANSACTION&txtimeout=30m'

string (duration)

use_cbo
Optional

Specifies whether the cost-based optimizer is enabled.

The node-level 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 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

cbq> \set -use_cbo true;

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&use_cbo=true'

boolean

use_fts
Optional

ENTERPRISE EDITION

Specifies that the query should use a full-text 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 full-text indexes are considered for the query. If a qualified full-text index is available, it is selected for the query. If none of the available full-text indexes are qualified, the available GSI indexes are considered instead.

Refer to Flex Indexes for more information.

Default

false

Example

cbq> \set -use_fts true;

$ curl http://localhost:8093/query/service -u user:pword -d 'statement=select * from default&use_fts=true'

boolean

$<identifier>
Optional

If the statement has 1 or more named parameters, there should be 1 or more named parameters in the request.

A named parameter consists of two parts:

The $ character
An identifier that starts with an alpha character followed by one or more alphanumeric characters.

Named parameters apply to prepared also.

Refer to Named Parameters VS. Positional Parameters for examples.

JSON value

Transactional Scan Consistency

If the request contains a BEGIN TRANSACTION statement, or a DML statement with the tximplicit parameter set to true, then the scan_consistency 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)

Named Parameters VS. Positional Parameters

Named Parameters use a variable name to refer to each one, while Positional Parameters refer to the position each variable is used. As summarized in the below table, these two types of requests should contain the following parameters:

Table 11. Named Parameters VS. Positional Parameters
	Statement	Args
Named Parameters	`SELECT detail FROM emp WHERE name = $nval AND age > $aval`	$nval = "smith" $aval = 45
Positional Parameters	`SELECT detail FROM emp WHERE name = $1 AND age > $2` `SELECT detail FROM emp WHERE name = ? AND age > ?`	[ "smith", 45 ]

Positional Parameters can also be specified in a statement using ? as an alternative way to specify the same query.

For more details about the N1QL REST API, refer to N1QL REST API.

For more details about the Admin REST API, refer to Admin REST API.

For more details about the Query Settings API, refer to Cluster Query Settings API.

For more details about API content and settings, refer to REST API reference.

Settings and Parameters

Query Setting Levels and Equivalents

Cluster-Level Query Settings

Node-Level Query Settings

Request-Level Parameters

Transactional Scan Consistency

Named Parameters VS. Positional Parameters

Related Links