Query Admin REST API

      +

      Overview

      The Query Admin REST API is a secondary API provided by the Query service. This API enables you to retrieve statistics about the clusters and nodes running the Query service; view or specify node-level settings; and view or delete requests.

      The API schemes and host URLs are as follows:

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

      Version information

      Version : 7.6

      Tags

      • configuration : Operations for cluster and node configuration.

      • prepared statements : Operations for prepared statements.

      • active requests : Operations for active requests.

      • completed requests : Operations for completed requests.

      • statistics : Operations for query statistics.

      • settings : Operations for query settings.

      • default : Other operations.

      Consumes

      • application/x-www-form-urlencoded

      • application/json

      Produces

      • application/json

      Resources

      This section describes the operations available with this REST API.

      Table of Contents

      Configuration

      Operations for cluster and node configuration.

      Read All Clusters

      GET /admin/clusters
      Description

      Returns information about all clusters.

      Responses
      HTTP Code Description Schema

      200

      An array of objects, each of which gives information about one cluster.

      < Clusters > array

      Security
      Type Name

      basic

      Read a Cluster

      GET /admin/clusters/{cluster}
      Description

      Returns information about the specified cluster.

      Parameters
      Type Name Description Schema

      Path

      cluster
      required

      The name of a cluster.

      string

      Responses
      HTTP Code Description Schema

      200

      An object giving information about the specified cluster.

      Security
      Type Name

      basic

      Read All Nodes

      GET /admin/clusters/{cluster}/nodes
      Description

      Returns information about all nodes in the specified cluster.

      Parameters
      Type Name Description Schema

      Path

      cluster
      required

      The name of a cluster.

      string

      Responses
      HTTP Code Description Schema

      200

      An array of objects, each of which gives information about one node.

      < Nodes > array

      Security
      Type Name

      basic

      Read a Node

      GET /admin/clusters/{cluster}/nodes/{node}
      Description

      Returns information about the specified node in the specified cluster.

      Parameters
      Type Name Description Schema

      Path

      cluster
      required

      The name of a cluster.

      string

      Path

      node
      required

      The name of a node.

      string

      Responses
      HTTP Code Description Schema

      200

      An object giving information about the specified node.

      Security
      Type Name

      basic

      Read Configuration

      GET /admin/config
      Description

      Returns the configuration of the query service on the cluster.

      Responses
      HTTP Code Description Schema

      200

      An object giving information about the specified node.

      Security
      Type Name

      basic

      Prepared Statements

      Operations for prepared statements.

      Retrieve All Prepared Statements

      GET /admin/prepareds
      Description

      Returns all prepared statements.

      Responses
      HTTP Code Description Schema

      200

      An array of objects, each of which contains information about one prepared statement.

      < Statements > array

      Security
      Type Name

      basic

      Example HTTP request

      Refer to Get Prepared Statements for examples.

      Retrieve a Prepared Statement

      GET /admin/prepareds/{name}
      Description

      Returns the specified prepared statement.

      Parameters
      Type Name Description Schema

      Path

      name
      required

      The name of a prepared statement. This may be a UUID that was assigned automatically, or a name that was user-specified when the statement was created.

      string

      Responses
      HTTP Code Description Schema

      200

      An object containing information about the specified prepared statement.

      Security
      Type Name

      basic

      Example HTTP request

      Refer to Get Prepared Statements for examples.

      Delete a Prepared Statement

      DELETE /admin/prepareds/{name}
      Description

      Deletes the specified prepared statement.

      Parameters
      Type Name Description Schema

      Path

      name
      required

      The name of a prepared statement. This may be a UUID that was assigned automatically, or a name that was user-specified when the statement was created.

      string

      Responses
      HTTP Code Description Schema

      200

      True if the prepared statement was successfully deleted.

      boolean

      500

      Returns an error message if the prepared statement could not be found.

      object

      Security
      Type Name

      basic

      Example HTTP request

      Refer to Delete Prepared Statements for examples.

      Retrieve Prepared Index Statements

      GET /admin/indexes/prepareds
      Description

      Returns all prepared index statements.

      Responses
      HTTP Code Description Schema

      200

      An array of strings, each of which is the name of a prepared index statement.

      < string > array

      Security
      Type Name

      basic

      Active Requests

      Operations for active requests.

      Retrieve All Active Requests

      GET /admin/active_requests
      Description

      Returns all active query requests.

      Responses
      HTTP Code Description Schema

      200

      An array of objects, each of which contains information about one active request.

      < Requests > array

      Security
      Type Name

      basic

      Example HTTP request

      Refer to Get Active Requests for examples.

      Retrieve an Active Request

      GET /admin/active_requests/{request}
      Description

      Returns the specified active query request.

      Parameters
      Type Name Description Schema

      Path

      request
      required

      The name of a request. This is the requestID that was assigned automatically when the statement was created.

      string

      Responses
      HTTP Code Description Schema

      200

      An object containing information about the specified active request.

      Security
      Type Name

      basic

      Example HTTP request

      Refer to Get Active Requests for examples.

      Delete an Active Request

      DELETE /admin/active_requests/{request}
      Description

      Terminates the specified active query request.

      Parameters
      Type Name Description Schema

      Path

      request
      required

      The name of a request. This is the requestID that was assigned automatically when the statement was created.

      string

      Responses
      HTTP Code Description Schema

      200

      True if the active request was successfully terminated.

      boolean

      500

      Returns an error message if the active request could not be found.

      object

      Security
      Type Name

      basic

      Example HTTP request

      Refer to Terminate an Active Request for examples.

      Retrieve Active Index Requests

      GET /admin/indexes/active_requests
      Description

      Returns all active index requests.

      Responses
      HTTP Code Description Schema

      200

      An array of strings, each of which is the requestID of an active index request.

      < string > array

      Security
      Type Name

      basic

      Completed Requests

      Operations for completed requests.

      Retrieve All Completed Requests

      GET /admin/completed_requests
      Description

      Returns all completed requests.

      Responses
      HTTP Code Description Schema

      200

      An array of objects, each of which contains information about one completed request.

      < Requests > array

      Security
      Type Name

      basic

      Example HTTP request

      Refer to Get Completed Requests for examples.

      Retrieve a Completed Request

      GET /admin/completed_requests/{request}
      Description

      Returns the specified completed request.

      Parameters
      Type Name Description Schema

      Path

      request
      required

      The name of a request. This is the requestID that was assigned automatically when the statement was created.

      string

      Responses
      HTTP Code Description Schema

      200

      An object containing information about the specified active request.

      Security
      Type Name

      basic

      Example HTTP request

      Refer to Get Completed Requests for examples.

      Delete a Completed Request

      DELETE /admin/completed_requests/{request}
      Description

      Purges the specified completed request.

      Parameters
      Type Name Description Schema

      Path

      request
      required

      The name of a request. This is the requestID that was assigned automatically when the statement was created.

      string

      Responses
      HTTP Code Description Schema

      200

      True if the completed request was successfully purged.

      boolean

      500

      Returns an error message if the completed request could not be found.

      object

      Security
      Type Name

      basic

      Example HTTP request

      Refer to Purge the Completed Requests for examples.

      Retrieve Completed Index Requests

      GET /admin/indexes/completed_requests
      Description

      Returns all completed index requests.

      Responses
      HTTP Code Description Schema

      200

      An array of strings, each of which is the requestID of a completed index request.

      < string > array

      Security
      Type Name

      basic

      Statistics

      Operations for query statistics.

      Retrieve Vitals

      GET /admin/vitals
      Description

      Returns data about the running state and health of the query engine. This information can be very useful to assess the current workload and performance characteristics of a query engine, and hence load-balance the requests being sent to various query engines.

      Responses
      HTTP Code Description Schema

      200

      An object containing all vital statistics.

      Security
      Type Name

      basic

      Example HTTP request

      Refer to Get System Vitals for examples.

      Retrieve All Statistics

      GET /admin/stats
      Description

      Returns all statistics.

      Responses
      HTTP Code Description Schema

      200

      An object containing all statistics. Each statistic consists of a top-level statistic name and a metric name. Each statistic has a different set of metrics.

      Security
      Type Name

      basic

      Retrieve a Statistic

      GET /admin/stats/{stat}
      Description

      Returns the specified statistic.

      Parameters
      Type Name Description Schema

      Path

      stat
      required

      The name of a statistic. Only top-level statistic names can be used. You cannot specify a metric.

      enum (active_requests, at_plus, audit_actions, audit_actions_failed, audit_requests_filtered, audit_requests_total, cancelled, deletes, errors, index_scans, inserts, invalid_requests, mutations, prepared, primary_scans, queued_requests, request_time, request_timer, requests, requests_1000ms, requests_250ms, requests_5000ms, requests_500ms, result_count, result_size, scan_plus, selects, service_time, unbounded, updates, warnings)

      Responses
      HTTP Code Description Schema

      200

      An object containing all metrics for the specified statistic. Each statistic has a different set of metrics.

      Security
      Type Name

      basic

      Get Debug Variables

      GET /debug/vars
      Description

      Currently unused.

      Responses
      HTTP Code Description Schema

      302

      Redirects to the Retrieve All Statistics endpoint.

      string (text/html)

      Produces
      • text/html

      Security
      Type Name

      basic

      Example HTTP response
      Response 302
      <a href="/admin/stats">Found</a>.

      Settings

      Operations for query settings.

      Retrieve Node-Level Query Settings

      GET /admin/settings
      Description

      Returns node-level query settings.

      Refer to Settings and Parameters for more information.
      Responses
      HTTP Code Description Schema

      200

      An object giving node-level query settings.

      Security
      Type Name

      basic

      Update Node-Level Query Settings

      POST /admin/settings
      Description

      Updates node-level query settings.

      Refer to Settings and Parameters for more information.
      Parameters
      Type Name Description Schema

      Body

      Settings
      optional

      An object specifying node-level query settings.

      Responses
      HTTP Code Description Schema

      200

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

      Security
      Type Name

      basic

      Default

      Other operations.

      Ping

      GET /admin/ping
      Description

      Returns a minimal response, indicating that the service is running and reachable.

      Responses
      HTTP Code Description Schema

      200

      An empty object.

      object

      Security
      Type Name

      basic

      Example HTTP response
      Response 200
      {}

      Run Garbage Collector

      GET /admin/gc
      Description

      Runs the garbage collector.

      A message is written to query.log whenever the garbage collector endpoint is invoked.

      Responses
      HTTP Code Description Schema

      200

      Indicates that the garbage collector was invoked.

      401

      Error 10000: authentication failure. The invoking user is not a valid full-admin user.

      object

      Security
      Type Name

      basic

      Example HTTP response
      Response 200
      {
        "freed": 123456,
        "status": "GC invoked"
      }

      Run Garbage Collector and Release Memory

      POST /admin/gc
      Description

      Run the garbage collector and attempts to return freed memory to the OS.

      A message is written to query.log whenever the garbage collector endpoint is invoked.

      Responses
      HTTP Code Description Schema

      200

      Indicates that the garbage collector was invoked.

      401

      Error 10000: authentication failure. The invoking user is not a valid full-admin user.

      object

      Security
      Type Name

      basic

      Example HTTP response
      Response 200
      {
        "freed": 109304,
        "released": 835584,
        "status": "GC invoked and memory released"
      }

      Definitions

      This section describes the properties consumed and returned by this REST API.

      Table of Contents

      Clusters

      Name Description Schema

      accountstore
      optional

      The URL of the accountstore.

      string

      configstore
      optional

      The URL of the configstore.

      string

      datastore
      optional

      The URL of the datastore.

      string

      name
      optional

      The name of the cluster.

      string

      version
      optional

      string

      Nodes

      Name Description Schema

      adminEndpoint
      optional

      The HTTP URL of the admin endpoint.

      string

      adminSecure
      optional

      The HTTPS URL of the admin endpoint.

      string

      cluster
      optional

      The name of the cluster.

      string

      name
      optional

      The URL of the node, including port number.

      string

      options
      optional

      string

      queryEndpoint
      optional

      The HTTP URL of the query endpoint.

      string

      querySecure
      optional

      The HTTPS URL of the query endpoint.

      string

      Requests

      Name Description Schema

      clientContextID
      optional

      The opaque ID or context provided by the client. Refer to the request-level client_context_id parameter for more information.

      string

      elapsedTime
      optional

      The time taken from when the request was acknowledged by the service to when the request was completed. It includes the time taken by the service to schedule the request.

      string (duration)

      errorCount
      optional

      Total number of errors encountered while executing the query.

      integer

      memoryQuota
      optional

      The memory quota for the request, in MB. This property is only returned if a memory quota is set for the query.

      integer

      node
      optional

      IP address and port number of the node where the query is executed.

      string

      phaseCounts
      optional

      Count of documents processed at selective phases involved in the query execution. Refer to Attribute Profile in Query Response for more details and examples.

      object

      phaseOperators
      optional

      Indicates the number of each kind of query operators involved in different phases of the query processing. Refer to Attribute Profile in Query Response for more details and examples.

      object

      phaseTimes
      optional

      Cumulative execution times for various phases involved in the query execution. Refer to Attribute Profile in Query Response for more details and examples.

      object

      remoteAddr
      optional

      IP address and port number of the client application, from where the query is received.

      string

      requestId
      optional

      Unique request ID internally generated for the query.

      string (uuid)

      requestTime
      optional

      Timestamp when the query is received.

      string (date-time)

      resultCount
      optional

      Total number of documents returned in the query result.

      integer

      resultSize
      optional

      Total number of bytes returned in the query result.

      integer

      scanConsistency
      optional

      The value of the query setting Scan Consistency used for the query.

      string

      serviceTime
      optional

      Total amount of calendar time taken to complete the query.

      string (duration)

      state
      optional

      The state of the query execution, such as completed, running, cancelled.

      Note that the completed state means that the request was started and completed by the Query service, but it does not mean that it was necessarily successful. The request could have been successful, or completed with errors.

      To find requests that were successful, use this field in conjunction with the errorCount field: search for requests whose state is completed and whose error count is 0.

      string

      statement
      optional

      The query statement being executed.

      string

      useCBO
      optional

      Whether the cost-based optimizer is enabled for the query.

      boolean

      usedMemory
      optional

      The amount of document memory used to execute the request. This property is only returned if a memory quota is set for the query.

      integer

      userAgent
      optional

      Name of the client application or program that issued the query.

      string

      users
      optional

      Username with whose privileges the query is run.

      string

      Statements

      Name Description Schema

      avgElapsedTime
      optional

      The mean time taken from when the request to execute the prepared statement was acknowledged by the service, to when the request was completed. It includes the time taken by the service to schedule the request.

      This property is only returned when the prepared statement has been executed. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements.

      string (duration)

      avgServiceTime
      optional

      The mean amount of calendar time taken to complete the execution of the prepared statement.

      This property is only returned when the prepared statement has been executed. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements.

      string (duration)

      encoded_plan
      required

      The full prepared statement in encoded format.

      string

      featureControls
      optional

      This property is provided for technical support only. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements.

      integer

      indexApiVersion
      optional

      This property is provided for technical support only. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements.

      integer

      lastUse
      optional

      Date and time of last use.

      This property is only returned when the prepared statement has been executed.

      string (date-time)

      maxElapsedTime
      optional

      The maximum time taken from when the request to execute the prepared statement was acknowledged by the service, to when the request was completed. It includes the time taken by the service to schedule the request.

      This property is only returned when the prepared statement has been executed. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements.

      string (duration)

      maxServiceTime
      optional

      The maximum amount of calendar time taken to complete the execution of the prepared statement.

      This property is only returned when the prepared statement has been executed. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements.

      string (duration)

      minElapsedTime
      optional

      The minimum time taken from when the request to execute the prepared statement was acknowledged by the service, to when the request was completed. It includes the time taken by the service to schedule the request.

      This property is only returned when the prepared statement has been executed. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements.

      string (duration)

      minServiceTime
      optional

      The minimum amount of calendar time taken to complete the execution of the prepared statement.

      This property is only returned when the prepared statement has been executed. It is only returned when retrieving a specific prepared statement, not when retrieving all prepared statements.

      string (duration)

      name
      required

      The name of the prepared statement. This may be a UUID that was assigned automatically, or a name that was user-specified when the statement was created.

      string

      statement
      required

      The text of the query.

      string

      uses
      required

      The count of times the prepared statement has been executed.

      integer

      Vitals

      Name Description Schema

      cores
      optional

      The maximum number of logical cores available to the query engine.

      integer

      cpu.sys.percent
      optional

      CPU usage. The percentage of time spent executing system code since the last time the statistics were checked.

      integer (int64)

      cpu.user.percent
      optional

      CPU usage. The percentage of time spent executing user code since the last time the statistics were checked.

      integer (int64)

      gc.num
      optional

      The target heap size of the next garbage collection cycle.

      integer (int64)

      gc.pause.percent
      optional

      The percentage of time spent pausing for garbage collection since the last time the statistics were checked.

      integer (int64)

      gc.pause.time
      optional

      The total time spent pausing for garbage collection since the query engine started (ns).

      string (duration)

      local.time
      optional

      The local time of the query engine.

      string (date-time)

      memory.system
      optional

      The total amount of memory obtained from the operating system (bytes). This measures the virtual address space reserved by the query engine for heaps, stacks, and other internal data structures.

      integer (int64)

      memory.total
      optional

      The cumulative amount of memory allocated for heap objects (bytes). This increases as heap objects are allocated, but does not decrease when objects are freed.

      integer (int64)

      memory.usage
      optional

      The amount of memory allocated for heap objects (bytes). This increases as heap objects are allocated, and decreases as objects are freed.

      integer (int64)

      request.active.count
      optional

      Total number of active requests.

      integer

      request.completed.count
      optional

      Total number of completed requests.

      integer

      request.per.sec.15min
      optional

      Number of query requests processed per second. 15-minute exponentially weighted moving average.

      number

      request.per.sec.1min
      optional

      Number of query requests processed per second. 1-minute exponentially weighted moving average.

      number

      request.per.sec.5min
      optional

      Number of query requests processed per second. 5-minute exponentially weighted moving average.

      number

      request.prepared.percent
      optional

      Percentage of requests that are prepared statements.

      integer

      request_time.80percentile
      optional

      End-to-end time to process a query. The 80th percentile.

      string (duration)

      request_time.95percentile
      optional

      End-to-end time to process a query. The 95th percentile.

      string (duration)

      request_time.99percentile
      optional

      End-to-end time to process a query. The 99th percentile.

      string (duration)

      request_time.mean
      optional

      End-to-end time to process a query. The mean value.

      string (duration)

      request_time.median
      optional

      End-to-end time to process a query. The median value.

      string (duration)

      total.threads
      optional

      The number of active threads used by the query engine.

      integer

      uptime
      optional

      The uptime of the query engine.

      string (duration)

      version
      optional

      The version of the query engine.

      string

      Statistics

      Name Description Schema

      active_requests.count
      optional

      Total number of active requests.

      integer

      at_plus.count
      optional

      Total number of query requests with at_plus index consistency.

      integer

      audit_actions.count
      optional

      The total number of audit records sent to the server. Some requests cause more than one audit record to be emitted. Records in the output queue that have not yet been sent to the server are not counted.

      integer

      audit_actions_failed.count
      optional

      The total number of audit records sent to the server that failed.

      integer

      audit_requests_filtered.count
      optional

      The number of potentially auditable requests that cause no audit action to be taken.

      integer

      audit_requests_total.count
      optional

      The total number of potentially auditable requests sent to the query engine.

      integer

      cancelled.count
      optional

      Total number of cancelled requests.

      integer

      deletes.count
      optional

      Total number of DELETE operations.

      integer

      errors.count
      optional

      The total number of query errors returned so far.

      integer

      index_scans.count
      optional

      Total number of secondary index scans.

      integer

      inserts.count
      optional

      Total number of INSERT operations.

      integer

      invalid_requests.count
      optional

      Total number of requests for unsupported endpoints.

      integer

      mutations.count
      optional

      Total number of document mutations.

      integer

      prepared.count
      optional

      Total number of prepared statements executed.

      integer

      primary_scans.count
      optional

      Total number of primary index scans.

      integer

      queued_requests.count
      optional

      Total number of queued requests.

      integer

      request_time.count
      optional

      Total end-to-end time to process all queries (ns).

      integer

      request_timer.15m.rate
      optional

      Number of query requests processed per second. 15-minute exponentially weighted moving average.

      number

      request_timer.1m.rate
      optional

      Number of query requests processed per second. 1-minute exponentially weighted moving average.

      number

      request_timer.5m.rate
      optional

      Number of query requests processed per second. 5-minute exponentially weighted moving average.

      number

      request_timer.75%
      optional

      End-to-end time to process a query (ns). The 75th percentile.

      number

      request_timer.95%
      optional

      End-to-end time to process a query (ns). The 95th percentile.

      number

      request_timer.99%
      optional

      End-to-end time to process a query (ns). The 99th percentile.

      number

      request_timer.99.9%
      optional

      End-to-end time to process a query (ns). The 99.9th percentile.

      number

      request_timer.count
      optional

      Total number of query requests.

      integer

      request_timer.max
      optional

      End-to-end time to process a query (ns). The maximum value.

      integer

      request_timer.mean
      optional

      End-to-end time to process a query (ns). The mean value.

      number

      request_timer.mean.rate
      optional

      Number of query requests processed per second. Mean rate since the query service started.

      number

      request_timer.median
      optional

      End-to-end time to process a query (ns). The median value.

      number

      request_timer.min
      optional

      End-to-end time to process a query (ns). The minimum value.

      integer

      request_timer.stddev
      optional

      End-to-end time to process a query (ns). The standard deviation.

      number

      requests.count
      optional

      Total number of query requests.

      integer

      requests_1000ms.count
      optional

      Number of queries that take longer than 1000ms.

      integer

      requests_250ms.count
      optional

      Number of queries that take longer than 250ms.

      integer

      requests_5000ms.count
      optional

      Number of queries that take longer than 5000ms.

      integer

      requests_500ms.count
      optional

      Number of queries that take longer than 500ms.

      integer

      result_count.count
      optional

      Total number of results (documents) returned by the query engine.

      integer

      result_size.count
      optional

      Total size of data returned by the query engine (bytes).

      integer

      scan_plus.count
      optional

      Total number of query requests with request_plus index consistency.

      integer

      selects.count
      optional

      Total number of SELECT requests.

      integer

      service_time.count
      optional

      Time to execute all queries (ns).

      integer

      unbounded.count
      optional

      Total number of query requests with not_bounded index consistency.

      integer

      updates.count
      optional

      Total number of UPDATE requests.

      integer

      warnings.count
      optional

      The total number of query warnings returned so far.

      integer

      Metrics

      Name Description Schema

      15m.rate
      optional

      15-minute exponentially weighted moving average.

      number

      1m.rate
      optional

      1-minute exponentially weighted moving average.

      number

      5m.rate
      optional

      5-minute exponentially weighted moving average.

      number

      75%
      optional

      The 75th percentile.

      number

      95%
      optional

      The 95th percentile.

      number

      99%
      optional

      The 99th percentile.

      number

      99.9%
      optional

      The 99.9th percentile.

      number

      count
      optional

      A single value that represents the current state.

      integer

      max
      optional

      The maximum value.

      integer

      mean
      optional

      The mean value.

      number

      mean.rate
      optional

      Mean rate since the query service started.

      number

      median
      optional

      The median value.

      number

      min
      optional

      The minimum value.

      integer

      stddev
      optional

      The standard deviation.

      number

      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 SQL++ 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

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

      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-max-plan-size
      optional

      A plan size in bytes. Limits the size of query execution plans that can be logged in the completed requests catalog. Values larger than the maximum limit are silently treated as the maximum limit. Queries with plans larger than this are not logged. You must obtain execution plans for such queries via profiling or using the EXPLAIN statement.

      Refer to Configure the Completed Requests for more information.

      The cluster-level queryCompletedMaxPlanSize setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster.
      Default : 262144
      Minimum value : 0
      Maximum value : 20840448

      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.

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

      To stop cpuprofile, run with the empty setting of "".
      Default : ""
      Example : "/tmp/info.txt"

      string

      debug
      optional

      Use debug mode.

      When set to true, extra logging is provided.
      Default : false
      Example : true

      boolean

      distribute
      optional

      This field is only available with the POST method. When specified alongside other settings, this field instructs the node that 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.

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

      This parameter enforces a ceiling on the memory used for the tracked documents required for processing a request. It does not take into account any other memory that might be used to process a request, such as the stack, the operators, or some intermediate values.

      Within a transaction, this setting enforces the memory quota for the transaction by tracking the delta table and the transaction log (approximately).

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

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

      To stop memprofile, run with the empty setting of "".
      Default : ""
      Example : "/tmp/memory-usage.log"

      string

      mutexprofile
      optional

      Mutex profile. This setting is provided for technical support only.
      Default : false

      boolean

      n1ql-feat-ctrl
      optional

      SQL++ feature control. This setting is provided for technical support only. The value may be an integer, or a string representing a hexadecimal number.

      The cluster-level queryN1qlFeatCtrl setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster.
      Default : 76
      Example : "0x1"

      integer (int32)

      node-quota
      optional

      Sets the soft memory limit for this node, in MB. The garbage collector tries to keep below this target. It is not a hard, absolute limit, and memory usage may exceed this value.

      When set to 0 (the default), there is no soft memory limit.

      The cluster-level queryNodeQuota setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster.
      Default : 0

      integer (int32)

      node-quota-val-percent
      optional

      The percentage of the node-quota that is dedicated to tracked value content memory across all active requests on this node. (The memory-quota setting specifies the maximum amount of document memory an individual request may use on this node.)

      The cluster-level queryNodeQuotaValPercent setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster.
      Default : 67
      Minimum value : 0
      Maximum value : 100

      integer (int32)

      num-cpus
      optional

      The number of CPUs the Query service can use on this node. Note that this setting requires a restart of the Query service to take effect.

      When set to 0 (the default), the Query service can use all available CPUs, up to the limits described below.

      The number of CPUs can never be greater than the number of logical CPUs. In Community Edition, the number of allowed CPUs cannot be greater than 4. In Enterprise Edition, there is no limit to the number of allowed CPUs.

      The cluster-level queryNumCpus setting specifies this property for the whole cluster. When you change the cluster-level setting, the node-level setting is over-written for all nodes in the cluster.
      Default : 0

      integer (int32)

      numatrs
      optional

      Specifies the total number of active transaction records.

      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.

      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)

      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.

      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)

      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.

      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)

      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.

      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

      use-replica
      optional

      Specifies whether a query can fetch data from a replica vBucket if active vBuckets are inaccessible. The possible values are:

      • off — read from replica is disabled for all queries and cannot be overridden at request level.

      • on — read from replica is enabled for all queries, but can be disabled at request level.

      • unset — read from replica is enabled or disabled at request level.

      The cluster-level queryUseReplica setting specifies the default for this property for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster.

      In addition, the request-level use_replica parameter specifies this property per request. If a request does not include this parameter, or if the request-level parameter is unset, the node-level setting is used. If the request-level parameter and the node-level setting are both unset, read from replica is disabled for that request.

      Do not enable read from replica when you require consistent results. Only SELECT queries that are not within a transaction can read from replica.

      Reading from replica is only possible if the cluster uses Couchbase Server 7.6.0 or later.

      Note that KV range scans cannot currently be started on a replica vBucket. If a query uses sequential scan and a data node becomes unavailable, the query might return an error, even if read from replica is enabled for the request.
      Default : "unset"
      Example : "true"

      enum (off, on, unset)

      Logging parameters

      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

      Garbage Collection

      Name Description Schema

      freed
      required

      The amount of memory freed.

      integer

      released
      optional

      Only returned by the POST method. The amount of memory released to the OS.

      integer

      status
      required

      The status of the garbage collector.

      string

      Security

      Default

      The Admin API supports admin credentials. Credentials can be passed via HTTP headers (HTTP basic authentication).

      Type : basic

      None

      No authentication is required for the Ping or Get Debug Variables endpoints.

      Type : basic

      See Also