Cluster Query Settings API

    +

    Overview

    The Query Settings REST API is provided by the Query service. This API enables you to view or specify cluster-level Query settings.

    The API schemes and host URLs are as follows:

    where node is the host name or IP address of a node running the Query service.

    Version information

    Version : 6.6

    Consumes

    • application/x-www-form-urlencoded

    Produces

    • application/json

    Paths

    Table of Contents

    Retrieve Cluster-Level Query Settings

    GET /settings/querySettings

    Description

    Returns all cluster-level query settings, including the CURL access settings.

    Responses

    HTTP Code Description Schema

    200

    An object giving cluster-level query settings.

    Security

    Type Name

    basic

    Example HTTP request

    The example below gets the current cluster-level query settings.

    Curl request
    $ curl -v -u Administrator:password \
      http://localhost:8091/settings/querySettings

    Example HTTP response

    Response 200
    {
      "queryTmpSpaceDir": "/opt/couchbase/var/lib/couchbase/tmp",
      "queryTmpSpaceSize": 5120,
      "queryPipelineBatch": 16,
      "queryPipelineCap": 512,
      "queryScanCap": 512,
      "queryTimeout": 0,
      "queryPreparedLimit": 16384,
      "queryCompletedLimit": 4000,
      "queryCompletedThreshold": 1000,
      "queryLogLevel": "info",
      "queryMaxParallelism": 1,
      "queryN1QLFeatCtrl": 12,
      "queryCurlWhitelist": {
        "all_access": false
      }
    }

    Update Cluster-Level Query Settings

    POST /settings/querySettings

    Description

    Updates cluster-level query settings, including the CURL access settings.

    Parameters

    Type Name Description Schema

    Body

    Settings
    optional

    An object specifying cluster-level query settings.

    Responses

    HTTP Code Description Schema

    200

    An object giving cluster-level query settings, including the latest changes.

    400

    Returns an error message if a parameter or value is incorrect.

    object

    Security

    Type Name

    basic

    Example HTTP request

    The example below changes the temp file directory to /tmp and the temp file size to 2048 MB.

    Curl request
    $ curl -v -X POST -u Administrator:password \
      http://localhost:8091/settings/querySettings \
      -d 'queryTmpSpaceDir=/tmp' \
      -d 'queryTmpSpaceSize=2048'

    Example HTTP response

    Response 200
    {
      "queryTmpSpaceDir": "/tmp",
      "queryTmpSpaceSize": 2048,
      "queryPipelineBatch": 16,
      "queryPipelineCap": 512,
      "queryScanCap": 512,
      "queryTimeout": 0,
      "queryPreparedLimit": 16384,
      "queryCompletedLimit": 4000,
      "queryCompletedThreshold": 1000,
      "queryLogLevel": "info",
      "queryMaxParallelism": 1,
      "queryN1QLFeatCtrl": 12,
      "queryCurlWhitelist": {
        "all_access": false
      }
    }

    Retrieve CURL Access List

    GET /settings/querySettings/curlWhitelist

    Description

    Returns the cluster-level CURL access settings only.

    Responses

    HTTP Code Description Schema

    200

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

    Security

    Type Name

    basic

    Example HTTP request

    The example below gets the current cluster-level CURL access settings.

    Curl request
    $ curl -v -u Administrator:password \
      http://localhost:8091/settings/querySettings/curlWhitelist

    Example HTTP response

    Response 200
    {"all_access":false}

    Update CURL Access List

    POST /settings/querySettings/curlWhitelist

    Description

    Updates the cluster-level CURL access settings only.

    Parameters

    Type Name Description Schema

    Body

    Settings
    optional

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

    Responses

    HTTP Code Description Schema

    200

    An object determining which URLs may be accessed by the CURL() function, including the latest changes.

    400

    Returns an error message if a parameter or value is incorrect.

    object

    Security

    Type Name

    basic

    Example HTTP request

    The example below specifies that https://company1.com is allowed, and https://company2.com is disallowed.

    Curl request
    $ curl -v -X POST -u Administrator:password \
      http://localhost:8091/settings/querySettings/curlWhitelist \
      -d '{"all_access": false,
           "allowed_urls": ["https://company1.com"],
           "disallowed_urls": ["https://company2.com"]}'

    Example HTTP response

    Response 200
    {
      "all_access": false,
      "allowed_urls": [
        "https://company1.com"
      ],
      "disallowed_urls": [
        "https://company2.com"
      ]
    }

    Definitions

    Table of Contents

    Settings

    Name Description Schema

    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)

    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)

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

    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.

    The cluster-level queryTimeout setting is an integer, representing a duration in nanoseconds. It must not be delimited by quotes, and must not include a unit.
    Default : 0
    Example : 500000000

    integer (int64)

    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)

    queryCurlWhitelist
    optional

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

    Access

    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

    Security

    The Query Settings REST API supports HTTP basic authentication. Credentials can be passed via HTTP headers.

    Default

    Users must have one of the following RBAC roles:

    • Full Admin

    • Cluster Admin

    Type : basic

    Refer to Roles for more details.