A newer version of this documentation is available.

View Latest

Admin REST API

    +

    Overview

    The 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 service-level settings; and view or delete requests.

    The API schemes and host URLs are as follows:

    • http://node:8093/

    • https://node:18093/ (for secure access)

    where node is the host name or IP address of a computer running the N1QL query engine.

    Version information

    Version : 6.0

    Consumes

    • application/x-www-form-urlencoded

    • application/json

    Produces

    • application/json

    Paths

    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

    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

    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

    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

    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

    GET /admin/prepareds

    Description

    Returns all prepared statements.

    Refer to Get Prepared Statements for examples.

    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

    GET /admin/prepareds/{name}

    Description

    Returns the specified prepared statement.

    Refer to Get Prepared Statements for examples.

    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

    DELETE /admin/prepareds/{name}

    Description

    Deletes the specified prepared statement.

    Refer to Delete Prepared Statements for examples.

    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

    GET /admin/active_requests

    Description

    Returns all active query requests.

    Refer to Get Active Requests for examples.

    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

    GET /admin/active_requests/{request}

    Description

    Returns the specified active query request.

    Refer to Get Active Requests for examples.

    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

    DELETE /admin/active_requests/{request}

    Description

    Terminates the specified active query request.

    Refer to Terminate an Active Request for examples.

    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

    GET /admin/completed_requests

    Description

    Returns all completed requests.

    Refer to Get Completed Requests for examples.

    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

    GET /admin/completed_requests/{request}

    Description

    Returns the specified completed request.

    Refer to Get Completed Requests for examples.

    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

    DELETE /admin/completed_requests/{request}

    Description

    Purges the specified completed request.

    Refer to Purge the Completed Requests for examples.

    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

    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

    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 (uuid) > array

    Security

    Type Name

    basic

    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 (uuid) > array

    Security

    Type Name

    basic

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

    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.

    Refer to Get System Vitals for examples.

    Responses

    HTTP Code Description Schema

    200

    An object containing all vital statistics.

    Security

    Type Name

    basic

    GET /admin/stats

    Description

    Returns all statistics.

    Responses

    HTTP Code Description Schema

    200

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

    Security

    Type Name

    basic

    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, cancelled, deletes, errors, inserts, invalid_requests, mutations, prepared, queued_requests, request_rate, 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/vars

    Description

    Currently unused.

    Responses

    HTTP Code Description Schema

    302

    Redirects to the GET /admin/stats endpoint.

    text/html

    Produces

    • text/html

    Security

    Type Name

    basic

    Example HTTP response

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

    GET /admin/settings

    Description

    Returns service-level query settings.

    Refer to Query Settings for more information and examples.

    Responses

    HTTP Code Description Schema

    200

    An object giving service-level query settings.

    Security

    Type Name

    basic

    POST /admin/settings

    Description

    Updates service-level query settings.

    Refer to Query Settings for more information and examples.

    Parameters

    Type Name Description Schema

    Body

    Settings
    optional

    An object specifying service-level query settings.

    Responses

    HTTP Code Description Schema

    200

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

    Security

    Type Name

    basic

    Definitions

    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.

    string (uuid)

    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

    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

    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.

    string

    statement
    optional

    The N1QL query statement being executed.

    string

    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 N1QL 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 N1QL requests processed per second. 15-minute exponentially weighted moving average.

    number

    request.per.sec.1min
    optional

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

    number

    request.per.sec.5min
    optional

    Number of N1QL 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 N1QL requests with at_plus index consistency.

    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 N1QL errors returned so far.

    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.15m.rate
    optional

    Prepared statements executed per second. 15-minute exponentially weighted moving average.

    number

    prepared.1m.rate
    optional

    Prepared statements executed per second. 1-minute exponentially weighted moving average.

    number

    prepared.5m.rate
    optional

    Prepared statements executed per second. 5-minute exponentially weighted moving average.

    number

    prepared.count
    optional

    Total number of prepared statements executed.

    integer

    prepared.mean.rate
    optional

    Prepared statements executed per second. Mean rate since the query service started.

    number

    queued_requests.count
    optional

    Total number of queued requests.

    integer

    request_rate.15m.rate
    optional

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

    integer

    request_rate.1m.rate
    optional

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

    integer

    request_rate.5m.rate
    optional

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

    integer

    request_rate.count
    optional

    Total number of N1QL requests.

    integer

    request_rate.mean.rate
    optional

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

    number

    request_time.count
    optional

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

    integer

    request_timer.15m.rate
    optional

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

    number

    request_timer.1m.rate
    optional

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

    number

    request_timer.5m.rate
    optional

    Number of N1QL 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 N1QL 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 N1QL 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 N1QL 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 N1QL 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 N1QL requests with not_bounded index consistency.

    integer

    updates.count
    optional

    Total number of UPDATE requests.

    integer

    warnings.count
    optional

    The total number of N1QL 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

    completed-limit
    optional

    Maximum number of completed requests. As new completed requests are added, old ones are removed. Refer to Configure the Completed Requests for more information and examples.
    Default : 4000
    Example : 7000

    integer (int32)

    completed-threshold
    optional

    A duration in milliseconds. All completed queries lasting longer than this threshold are logged in the completed requests catalog. Refer to Configure the Completed Requests for more information and examples.
    Default : 1000
    Example : 7000

    integer (int32)

    controls
    optional

    Specifies if there should be a controls section returned with the request results.
    Default : false
    Example : true

    boolean

    cpuprofile
    optional

    The absolute path and filename to write the CPU profile to a local file.
    Default : ""
    Example : "/tmp/info.txt"

    string

    debug
    optional

    Use debug mode.
    Default : false
    Example : true

    boolean

    keep-alive-length
    optional

    Maximum size of buffered result.
    Default : 16384
    Example : 7000

    integer (int32)

    loglevel
    optional

    Log level used in the logger.
    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

    Maximum number of index partitions, for computing aggregation in parallel. Refer to Max Parallelism for more information.
    Default : 1
    Example : 0

    integer (int32)

    memprofile
    optional

    Filename to write the diagnostic memory usage log.
    Default : ""
    Example : "/tmp/memory-usage.log"

    string

    n1ql-feat-ctrl
    optional

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

    integer (int32)

    pipeline-batch
    optional

    Controls the number of items execution operators can batch for Fetch from the KV.
    Default : 16
    Example : 64

    integer (int32)

    pipeline-cap
    optional

    Maximum number of items each execution operator can buffer between various operators.
    Default : 512
    Example : 1024

    integer (int32)

    prepared-limit
    optional

    Maximum number of prepared statements in the cache.
    Default : 16384
    Example : 65536

    integer (int32)

    pretty
    optional

    Specifies whether query results are returned in pretty format.
    Default : false
    Example : true

    boolean

    profile
    optional

    Specifies if there should be a profile section returned with the request results. Refer to Monitoring and Profiling Details for more information and examples.
    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.
    Default : 512
    Example : 1024

    integer (int32)

    servicers
    optional

    The number of service threads for the query.
    Default : 32
    Example : 8

    integer (int32)

    timeout
    optional

    Maximum time to spend on the request before timing out.
    Default : "0s"
    Example : "30m"

    string (duration)

    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 GET /admin/ping or GET /debug/vars endpoints.

    Type : basic