query-settings.yaml

swagger: '2.0'
info:
  title: Query Settings REST API
  version: '7.2'
  description: |
    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:

    * http://node:8091/
    * https://node:18091/ (for secure access)

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

produces:
  - application/json

consumes:
  - application/x-www-form-urlencoded

paths:
  /settings/querySettings:
    get:
      operationId: get_settings
      summary: Retrieve Cluster-Level Query Settings
      description: Returns all cluster-level query settings, including the CURL access settings.
      security:
        - Default: []
      responses:
        200:
          description: An object giving cluster-level query settings.
          schema:
            $ref: "#/definitions/Settings"
    post:
      operationId: post_settings
      summary: Update Cluster-Level Query Settings
      description: Updates cluster-level query settings, including the CURL access settings.
      security:
        - Default: []
      parameters:
        - in: body
          name: Settings
          description: An object specifying cluster-level query settings.
          schema:
            $ref: "#/definitions/Settings"
      responses:
        200:
          description: An object giving cluster-level query settings, including the latest changes.
          schema:
            $ref: "#/definitions/Settings"
        400:
          description: Returns an error message if a parameter or value is incorrect.
          schema:
            type: object

  /settings/querySettings/curlWhitelist:
    get:
      operationId: get_access
      summary: Retrieve CURL Access List
      description: Returns the cluster-level CURL access settings only.
      security:
        - Default: []
      responses:
        200:
          description: An object determining which URLs may be accessed by the `CURL()` function.
          schema:
            $ref: "#/definitions/Access"
    post:
      operationId: post_access
      summary: Update CURL Access List
      description: Updates the cluster-level CURL access settings only.
      security:
        - Default: []
      parameters:
        - in: body
          name: Settings
          description: An object determining which URLs may be accessed by the `CURL()` function.
          schema:
            $ref: "#/definitions/Access"
      responses:
        200:
          description: An object determining which URLs may be accessed by the `CURL()` function, including the latest changes.
          schema:
            $ref: "#/definitions/Access"
        400:
          description: Returns an error message if a parameter or value is incorrect.
          schema:
            type: object

# Use attributes for xrefs so that they can point to different locations in different contexts

definitions:
  Settings:
    type: object
    title: Settings
    properties:
      queryCleanupClientAttempts:
        type: boolean
        default: true
        example: false
        description: |
          [[queryCleanupClientAttempts]]
          When enabled, the Query service preferentially aims to clean up just transactions that it has created, leaving transactions for the distributed cleanup process only when it is forced to.

          The {cleanupclientattempts}[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.
      queryCleanupLostAttempts:
        type: boolean
        default: true
        example: false
        description: |
          [[queryCleanupLostAttempts]]
          When enabled, the Query service takes part in the distributed cleanup process, and cleans up expired transactions created by any client.

          The {cleanuplostattempts}[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.
      queryCleanupWindow:
        type: string
        format: duration
        default: 60s
        example: 30s
        description: |
          [[queryCleanupWindow]]
          Specifies how frequently the Query service checks its subset of xref:learn:data/transactions.adoc#additional-storage-use[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 {cleanupwindow}[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.
      queryCompletedLimit:
        type: integer
        format: int32
        default: 4000
        example: 7000
        description: |
          [[queryCompletedLimit]]
          Sets the number of requests to be logged in the completed requests catalog.
          As new completed requests are added, old ones are removed.

          Increase this when the completed request keyspace is not big enough to track the slow requests, such as when you want a larger sample of slow requests.

          Refer to xref:manage:monitor/monitoring-n1ql-query.adoc#sys-completed-config[Configure the Completed Requests] for more information and examples.

          The {completed-limit-srv}[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.
      queryCompletedThreshold:
        type: integer
        format: int32
        default: 1000
        example: 7000
        description: |
          [[queryCompletedThreshold]]
          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 xref:manage:monitor/monitoring-n1ql-query.adoc#sys-completed-config[Configure the Completed Requests] for more information and examples.

          The {completed-threshold-srv}[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.
      queryLogLevel:
        type: string
        default: INFO
        enum: ["DEBUG","TRACE","INFO","WARN","ERROR","SEVERE","NONE"]
        example: DEBUG
        description: |
          [[queryLogLevel]]
          Log level used in the logger.

          All values, in descending order of data:{blank}

          `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 {loglevel-srv}[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.
      queryMaxParallelism:
        type: integer
        format: int32
        default: 1
        example: 0
        description: |
          [[queryMaxParallelism]]
          Specifies the maximum parallelism for queries on all Query nodes in the cluster.

          If the value is zero or negative, the maximum parallelism is restricted to the number of allowed cores.
          Similarly, if the value is greater than the number of allowed cores, the maximum parallelism is restricted to the number of allowed cores.

          (The number of allowed cores is the same as the number of logical CPUs.
          In Community Edition, the number of allowed cores cannot be greater than 4.
          In Enterprise Edition, there is no limit to the number of allowed cores.)

          The {max-parallelism-srv}[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 {max_parallelism_req}[request-level] `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.

          Refer to xref:n1ql:n1ql-language-reference/index-partitioning.adoc#max-parallelism[Max Parallelism] for more information.
      queryMemoryQuota:
        type: integer
        format: int32
        default: 0
        example: 4
        description: |
          [[queryMemoryQuota]]
          Specifies the maximum amount of memory a request may use on any Query node in the cluster, in MB.

          This parameter enforces a ceiling on the memory used for the tracked documents required for 
          processing a request. It does not take into account any other memory that might be used to 
          process a request, such as the stack, the operators, or some intermediate values.
          
          Within a transaction, this setting enforces the memory quota for the transaction by tracking the
          delta table and the transaction log (approximately).

          The {memory-quota-srv}[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 {memory_quota_req}[request-level] `memory_quota` parameter.
          If a request includes this parameter, it will be capped by the node-level `memory-quota` setting.
      queryN1QLFeatCtrl:
        type: integer
        format: int32
        description: |
          [[queryN1QLFeatCtrl]]
          {sqlpp} feature control.
          This setting is provided for technical support only.

          The {n1ql-feat-ctrl}[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.
      queryNumAtrs:
        type: integer
        format: int32
        minimum: 0
        exclusiveMinimum: true
        default: 1024
        example: 512
        description: |
          [[queryNumAtrs]]
          Specifies the total number of xref:learn:data/transactions.adoc#additional-storage-use[active transaction records] for all Query nodes in the cluster.

          The {numatrs-srv}[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.
      queryPipelineBatch:
        type: integer
        format: int32
        default: 16
        example: 64
        description: |
          [[queryPipelineBatch]]
          Controls the number of items execution operators can batch for Fetch from the KV.

          The {pipeline-batch-srv}[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 {pipeline_batch_req}[request-level] `pipeline_batch` parameter specifies this property per request.
          The minimum of that and the node-level `pipeline-batch` setting is applied.
      queryPipelineCap:
        type: integer
        format: int32
        default: 512
        example: 1024
        description: |
          [[queryPipelineCap]]
          Maximum number of items each execution operator can buffer between various operators.

          The {pipeline-cap-srv}[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 {pipeline_cap_req}[request-level] `pipeline_cap` parameter specifies this property per request.
          The minimum of that and the node-level `pipeline-cap` setting is applied.
      queryPreparedLimit:
        type: integer
        format: int32
        default: 16384
        example: 65536
        description: |
          [[queryPreparedLimit]]
          Maximum number of prepared statements in the cache.
          When this cache reaches the limit, the least recently used prepared statements will be discarded as new prepared statements are created.

          The {prepared-limit-srv}[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.
      queryScanCap:
        type: integer
        format: int32
        default: 512
        example: 1024
        description: |
          [[queryScanCap]]
          Maximum buffered channel size between the indexer client and the query service for index scans.
          This parameter controls when to use scan backfill.

          Use `0` or a negative number to disable.
          Smaller values reduce GC, while larger values reduce indexer backfill.

          The {scan-cap-srv}[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 {scan_cap_req}[request-level] `scan_cap` parameter specifies this property per request.
          The minimum of that and the node-level `scan-cap` setting is applied.
      queryTimeout:
        type: integer
        format: int64
        default: 0
        example: 500000000
        description: |
          [[queryTimeout]]
          Maximum time to spend on the request before timing out (ns).

          The value for this setting is an integer, representing a duration in nanoseconds.
          It must not be delimited by quotes, and must not include a unit.

          Specify `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 {timeout-srv}[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 {timeout_req}[request-level] `timeout` parameter specifies this property per request.
          The minimum of that and the node-level `timeout` setting is applied.
      queryTxTimeout:
        type: string
        format: duration
        default: "0ms"
        example: "0.5s"
        description: |
          [[queryTxTimeout]]
          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 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 {txtimeout-srv}[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 {txtimeout_req}[request-level] `txtimeout` parameter.
          If a request includes this parameter, it will be capped by the node-level `txtimeout` setting.
      queryTmpSpaceDir:
        type: string
        example: "/opt/couchbase/var/lib/couchbase/tmp"
        description: |
          [[queryTmpSpaceDir]]
          The path to which the indexer writes temporary backfill files, to store any transient data during query processing.

          The specified path must already exist.
          Only absolute paths are allowed.

          The default path is [.file]`var/lib/couchbase/tmp` within the Couchbase Server installation directory.
      queryTmpSpaceSize:
        type: integer
        format: int32
        default: 5120
        example: 2048
        description: |
          [[queryTmpSpaceSize]]
          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.
      queryUseCBO:
        type: boolean
        default: true
        example: false
        description: |
          [[queryUseCBO]]
          Specifies whether the cost-based optimizer is enabled.

          The {use-cbo-srv}[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 {use_cbo_req}[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`.
      queryCurlWhitelist:
        description: |
          [[queryCurlWhitelist]]
          An object which determines which URLs may be accessed by the `CURL()` function.
        $ref: "#/definitions/Access"

  Access:
    type: object
    required:
      - all_access
    properties:
      all_access:
        type: boolean
        default: false
        description: |
          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 [.param]`allowed_urls` and [.param]`disallowed_urls` fields.

          Setting this field to `true` enables access to all endpoints.
      allowed_urls:
        type: array
        description: |
          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.
        default: []
        items:
          type: string
      disallowed_urls:
        type: array
        description: |
          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 [.param]`allowed_urls` and [.param]`disallowed_urls` fields are populated, the [.param]`disallowed_urls` field takes precedence over [.param]`allowed_urls`.

          Note that each URL must include the port, protocol, and all other components of the URL.
        default: []
        items:
          type: string


securityDefinitions:
  Default:
    type: basic
    description: |
      Users must have one of the following RBAC roles:

      * Full Admin
      * Cluster Admin