N1QL REST API

    +

    Overview

    The Query Service REST API is provided by the Query service. This API enables you to run N1QL queries and set request-level parameters.

    The API schemes and host URLs are as follows:

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

    Version information

    Version : 7.1

    Consumes

    • application/x-www-form-urlencoded

    • application/json

    Produces

    • application/json

    Paths

    This section describes the operations available with this REST API.

    Table of Contents

    Query Service

    POST /query/service

    Description

    Enables you to execute a N1QL statement. This method allows you to run queries and modifying statements, and specify query parameters.

    Parameters

    For POST requests, you can specify form data parameters using the application/x-www-form-urlencoded MIME type. Alternatively, you can specify parameters in the request body using the application/json MIME type with the Content-Type header.

    Type Name Description Schema

    Body

    Parameters
    required

    An object specifying one or more query parameters.

    Responses

    This section describes the response HTTP status codes.

    HTTP Code Description Schema

    200

    The operation was successful.

    400

    Bad Request. The request cannot be processed for one of the following reasons:

    • The statement contains a N1QL syntax error.

    • The request has a missing or unrecognized HTTP parameter.

    • The request is badly formatted (for example, the request body contains a JSON syntax error).

    No Content

    401

    Unauthorized. The credentials provided with the request are missing or invalid.

    No Content

    403

    Forbidden. There is a read-only violation. Either there was an attempt to create or update in a GET request or a POST request where readonly is set, or the client does not have the authorization to modify an object (index, keyspace or namespace) in the statement.

    No Content

    404

    Not found. The statement in the request references an invalid namespace or keyspace.

    No Content

    405

    Method not allowed. The statement in the request references an invalid namespace or keyspace.

    No Content

    409

    Conflict. There is an attempt to create an object (keyspace or index) that already exists.

    No Content

    410

    Gone. The server is shutting down gracefully. Previously made requests are being completed, but no new requests are being accepted.

    No Content

    500

    Internal server error. There was an unforeseen problem processing the request.

    No Content

    503

    Service unavailable. There is an issue (that is possibly temporary) preventing the request being processed; the request queue is full or the data store is not accessible.

    No Content

    Security

    Type Name

    basic

    basic

    Example HTTP request

    POST request with parameters as form data

    Curl request
    curl -v http://localhost:8093/query/service \
         -d 'statement=SELECT name FROM `travel-sample`.inventory.hotel LIMIT 1;' \
         -u Administrator:password

    POST request with parameters in JSON format

    Curl request
    curl http://localhost:8093/query/service \
        -H 'Content-Type: application/json' \
        -d '{ "statement": "SELECT name FROM travel-sample`.inventory.hotel LIMIT 1;" }' \
        -u Administrator:password

    For further examples, refer to Examples.

    Read-Only Query Service

    GET /query/service

    Description

    Enables you to execute a N1QL statement. This method allows you to run queries and modifying statements, and specify query parameters. It does not allow you to run modifying statements.

    This endpoint is intended for situations where use of the POST method is restricted.

    Parameters

    For GET requests, you specify the parameters in the query URL in URL-encoded format. For URL-encoded parameters, the format is consistent with the syntax for variables according to the RFC 6570.

    For a table of parameters that can be passed in a GET request to the /query/service endpoint, refer to Request Parameters.

    Responses

    This section describes the response HTTP status codes.

    HTTP Code Description Schema

    200

    The operation was successful.

    400

    Bad Request. The request cannot be processed for one of the following reasons:

    • The statement contains a N1QL syntax error.

    • The request has a missing or unrecognized HTTP parameter.

    • The request is badly formatted (for example, the request body contains a JSON syntax error).

    No Content

    401

    Unauthorized. The credentials provided with the request are missing or invalid.

    No Content

    403

    Forbidden. There is a read-only violation. Either there was an attempt to create or update in a GET request or a POST request where readonly is set, or the client does not have the authorization to modify an object (index, keyspace or namespace) in the statement.

    No Content

    404

    Not found. The statement in the request references an invalid namespace or keyspace.

    No Content

    405

    Method not allowed. The statement in the request references an invalid namespace or keyspace.

    No Content

    409

    Conflict. There is an attempt to create an object (keyspace or index) that already exists.

    No Content

    410

    Gone. The server is shutting down gracefully. Previously made requests are being completed, but no new requests are being accepted.

    No Content

    500

    Internal server error. There was an unforeseen problem processing the request.

    No Content

    503

    Service unavailable. There is an issue (that is possibly temporary) preventing the request being processed; the request queue is full or the data store is not accessible.

    No Content

    Security

    Type Name

    basic

    basic

    Example HTTP request

    GET request with query parameters

    Curl request
    curl -v http://localhost:8093/query/service?statement=SELECT%20name%20FROM%20%60travel-sample%60.inventory.hotel%20LIMIT%201%3B \
         -u Administrator:password

    For further examples, refer to Examples.

    Definitions

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

    Table of Contents

    Request Parameters

    Name Description Schema

    args
    optional

    Applicable if the statement has 1 or more positional parameters.

    An array of JSON values, one for each positional parameter in the statement.

    Note that positional parameters apply to prepared also.

    Refer to Examples for details.
    Example : [ "LAX", 6 ]

    < object > array

    atrcollection
    optional

    Specifies the collection where the active transaction record (ATR) is stored. The collection must be present. If not specified, the ATR is stored in the default collection in the default scope in the bucket containing the first mutated document within the transaction.

    The 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 node-level atrcollection setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting.
    Example : "default:`travel-sample`.transaction.test"

    string

    auto_execute
    optional

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

    Refer to Auto-Execute for more information.
    Default : false
    Example : true

    boolean

    client_context_id
    optional

    A piece of data supplied by the client that is echoed in the response, if present. N1QL is agnostic about the content of this parameter; it is just echoed in the response.

    • Maximum allowed size is 64 characters; all others will be cut.

    • If it contains an escape character / or quote ", it will be rejected as error code 1110.

    string

    compression
    optional

    Compression format to use for response data on the wire.

    Values are case-insensitive.
    Default : "NONE"
    Example : "zip"

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

    controls
    optional

    Specifies if there should be a controls section returned with the request results.

    When set to true, the query response document includes a controls section with runtime information provided along with the request, such as positional and named parameters or settings.

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

    The node-level controls setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting.
    Example : true

    boolean

    creds
    optional

    Specifies the login credentials. The Query API supports two types of identity: local (or bucket) and admin.

    The format is an identity and password. You can specify credentials for multiple identities.

    If credentials are supplied in the request header, then HTTP Basic Authentication takes precedence and creds is ignored.
    Example : [ { "user" : "local:bucket-name", "pass" : "password" }, { "user" : "admin:admin-name", "pass" : "password" } ]

    < Credentials > array

    durability_level
    optional

    The level of durability for mutations produced by the request.

    If the request contains a BEGIN TRANSACTION statement, or a DML statement with the tximplicit parameter set to true, the durability level is specified for all mutations within that transaction.

    In Couchbase Server 7.1 and later, durability is also supported for non-transactional DML statements. In this case, the kvtimeout parameter is used as the durability timeout.

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

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

    encoded_plan
    optional

    In Couchbase Server 6.5 and later, this parameter is ignored and has no effect. It is included for compatibility with previous versions of Couchbase Server.

    string

    encoding
    optional

    Desired character encoding for the query results.

    Only possible value is UTF-8 and is case-insensitive.
    Default : "UTF-8"

    string

    format
    optional

    Desired format for the query results.

    Values are case-insensitive.
    Default : "JSON"
    Example : "XML"

    enum (JSON, XML, CSV, TSV)

    kvtimeout
    optional

    The maximum time to wait for a KV operation before timing out. Only applies to statements within a transaction, or to non-transactional statements when the durability_level is set.

    The value for this parameter is a string. Its format includes an amount and a mandatory unit, e.g. 10ms (10 milliseconds) or 0.5s (half a second). Valid units are:

    • ns (nanoseconds)

    • us (microseconds)

    • ms (milliseconds)

    • s (seconds)

    • m (minutes)

    • h (hours)

    Specify a duration of 0 or a negative duration to disable. When disabled, no timeout is applied and the KV operation runs for however long it takes.
    Default : "2.5s"
    Example : "10ms"

    string

    max_parallelism
    optional

    Specifies the maximum parallelism for the query.

    The node-level max-parallelism setting specifies the ceiling for this parameter for a single node. If the request-level parameter is zero or negative, the parallelism for the query is set to the node-level setting. If the request-level parameter is greater than zero and less than the node-level setting, the request-level parameter overrides the node-level setting. If the request-level parameter is greater than the node-level setting, the parallelism for the query is set to the node-level setting.

    In addition, the cluster-level queryMaxParallelism setting specifies the ceiling for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster.

    To enable queries to run in parallel, you must specify the cluster-level queryMaxParallelism parameter, or specify the node-level max-parallelism parameter on all Query nodes.

    The default value is the same as the number of partitions of the index selected for the query.
    Example : 3

    integer (int32)

    memory_quota
    optional

    Specifies the maximum amount of memory the request may use, in MB.

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

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

    The node-level memory-quota setting specifies the ceiling for this parameter for a single node. If the node-level setting is zero (the default), the request-level parameter overrides the node-level setting. If the node-level setting is greater than zero, the request-level parameter is capped by the node-level setting.

    In addition, the cluster-level queryMemoryQuota setting specifies the ceiling for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster.
    Default : 0
    Example : 4

    integer (int32)

    metrics
    optional

    Specifies that metrics should be returned with query results.
    Default : true
    Example : false

    boolean

    namespace
    optional

    Specifies the namespace to use. Currently, only the default namespace is available.
    Example : "default"

    string

    numatrs
    optional

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

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

    In addition, the cluster-level queryNumAtrs setting specifies the default for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster.
    Default : 1024
    Example : 512

    integer (int32)

    pipeline_batch
    optional

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

    The node-level pipeline-batch setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting, but only if it is lower than the node-level setting.

    In addition, the cluster-level queryPipelineBatch setting specifies the default for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster.
    Example : 64

    integer (int32)

    pipeline_cap
    optional

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

    The node-level pipeline-cap setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting, but only if it is lower than the node-level setting.

    In addition, the cluster-level queryPipelineCap setting specifies the default for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster.
    Example : 1024

    integer (int32)

    prepared
    optional

    Required if statement not provided.

    The name of the prepared N1QL statement to be executed. Refer to EXECUTE for examples.

    If both prepared and statement are present and non-empty, an error is returned.
    Example : "[127.0.0.1:8091]pricy_hotel"

    string

    preserve_expiry
    optional

    In Couchbase Server 7.1 and later, specifies whether documents should keep their current expiration setting when modified by a DML statement.

    If true, documents will keep any existing expiration setting when modified by a DML statement. If the DML statement explicitly specifies the document expiration, the statement overrides this parameter, and the expiration is changed.

    If false, document expiration is set to 0 when modified by a DML statement, unless the DML statement explicitly specifies the document expiration.

    Not supported for statements in a transaction.
    Default : false
    Example : true

    boolean

    pretty
    optional

    Specifies the query results returned in pretty format.

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

    boolean

    profile
    optional

    Specifies if there should be a profile section returned with the request results. The valid values are:

    off

    No profiling information is added to the query response.

    phases

    The query response includes a profile section with stats and details about various phases of the query plan and execution. Three phase times will be included in the system:active_requests and system:completed_requests monitoring keyspaces.

    timings

    Besides the phase times, the profile section of the query response document will include a full query plan with timing and information about the number of processed documents at each phase. This information will be included in the system:active_requests and system:completed_requests keyspaces.

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

    The node-level profile setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting.
    Example : "phases"

    enum (off, phases, timings)

    query_context
    optional

    Specifies the namespace, bucket, and scope used to resolve partial keyspace references within the request.

    The query context may be a full path, containing namespace, bucket, and scope; or a relative path, containing just the bucket and scope. Currently, only the default namespace is available. If the namespace name is omitted, the default namespace in the current session is used.
    Default : "default:"
    Example : "default:travel-sample.inventory"

    string

    readonly
    optional

    Controls whether a query can change a resulting recordset.

    If readonly is true, then the following statements are not allowed:

    • CREATE INDEX

    • DROP INDEX

    • INSERT

    • MERGE

    • UPDATE

    • UPSERT

    When using GET requests, it’s best to set readonly to true.
    Default : false
    Example : true

    boolean

    scan_cap
    optional

    Maximum buffered channel size between the indexer client and the query service for index scans. This parameter controls when to use scan backfill.

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

    The node-level scan-cap setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting, but only if it is lower than the node-level setting.

    In addition, the cluster-level queryScanCap setting specifies the default for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster.
    Example : 1024

    integer (int32)

    scan_consistency
    optional

    Specifies the consistency guarantee or constraint for index scanning. The valid values are:

    not_bounded

    No timestamp vector is used in the index scan. This is the fastest mode, because it avoids the costs of obtaining the vector and waiting for the index to catch up to the vector.

    at_plus

    This implements bounded consistency. The request includes a scan_vector parameter and value, which is used as a lower bound. This can be used to implement read-your-own-writes (RYOW).

    request_plus

    This implements strong consistency per request. Before processing the request, a current vector is obtained. The vector is used as a lower bound for the statements in the request. If there are DML statements in the request, RYOW is also applied within the request.

    If request_plus is specified in a query that runs during a failover of an index node, the query waits until the rebalance operation completes and the index data has rebalanced before returning a result.

    statement_plus

    This implements strong consistency per statement. Before processing each statement, a current vector is obtained and used as a lower bound for that statement.

    Values are case-insensitive.

    For multi-statement requests, the default behavior is RYOW within each request. If you want to disable RYOW within a request, add a separate request_consistency parameter that can be set to not_bounded.

    If the request contains a BEGIN TRANSACTION statement, or a DML statement with the tximplicit parameter set to true, then this parameter sets the transactional scan consistency. Refer to Transactional Scan Consistency for details.
    Default : "not_bounded"
    Example : "at_plus"

    enum (not_bounded, at_plus, request_plus, statement_plus)

    scan_vector
    optional

    Required if scan_consistency is at_plus and scan_vectors not provided.

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

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

    • value: a vBucket’s sequence number (a JSON number)

    • guard: a vBucket’s UUID (a string)

    Scan vectors have two forms:

    1. Full scan vector: an array of [value, guard] entries, giving an entry for every vBucket in the system.

    2. Sparse scan vectors: an object providing entries for specific vBuckets, mapping a vBucket number (a string) to each [value, guard] entry.

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

    For queries referencing multiple keyspaces, use scan_vectors.
    Example : { "5" : [ 5409393, "VB5ID" ], "19" : [ 47574574, "VB19ID" ] }

    object

    scan_vectors
    optional

    Required if scan_consistency is at_plus and scan_vector not provided.

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

    The scan vectors can be Full or Sparse.

    object

    scan_wait
    optional

    Can be supplied with scan_consistency values of request_plus, statement_plus and at_plus.

    Specifies the maximum time the client is willing to wait for an index to catch up to the vector timestamp in the request.

    Specifies how much time the client is willing to wait for the indexer to satisfy the required scan_consistency and scan_vector criteria. After receiving the scan request, if the indexer is unable to catch up within the scan_wait time and initiate the scan, the indexer aborts with an error and the scan fails.

    Its format includes an amount and a mandatory unit, e.g. 10ms (10 milliseconds) or 0.5s (half a second). Valid units are:

    • ns (nanoseconds)

    • us (microseconds)

    • ms (milliseconds)

    • s (seconds)

    • m (minutes)

    • h (hours)

    Specify 0 or a negative integer to disable.
    Default : ""
    Example : "30m"

    string (duration)

    signature
    optional

    Include a header for the results schema in the response.
    Default : true
    Example : false

    boolean

    statement
    optional

    Required if prepared not provided.

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

    If both prepared and statement are present and non-empty, an error is returned.
    Example : "SELECT * FROM `travel-sample`.inventory.hotel LIMIT 1;"

    string

    timeout
    optional

    Maximum time to spend on the request before timing out.

    The value for this parameter is a string. Its format includes an amount and a mandatory unit, e.g. 10ms (10 milliseconds) or 0.5s (half a second). Valid units are:

    • ns (nanoseconds)

    • us (microseconds)

    • ms (milliseconds)

    • s (seconds)

    • m (minutes)

    • h (hours)

    Specify a duration of 0 or a negative duration to disable. When disabled, no timeout is applied and the request runs for however long it takes.

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

    The node-level timeout setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting. However, if the node-level setting is greater than 0, the timeout for the query is limited to the node-level setting.

    In addition, the cluster-level queryTimeout setting specifies the default for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster.
    Example : "30m"

    string (duration)

    txdata
    optional

    Transaction data. For internal use only.

    object

    txid
    optional

    Required for statements within a transaction.

    Transaction ID. Specifies the transaction to which a statement belongs. For use with DML statements within a transaction, rollbacks, and commits.

    The transaction ID should be the same as the transaction ID generated by the BEGIN TRANSACTION statement. The transaction must be active and non-expired.
    Example : "d81d9b4a-b758-4f98-b007-87ba262d3a51"

    string (UUID)

    tximplicit
    optional

    Specifies that a DML statement is a singleton transaction.

    When this parameter is true, the Query service starts a transaction and executes the statement. If execution is successful, the Query service commits the transaction; otherwise the transaction is rolled back.

    The statement may not be part of an ongoing transaction. If the txid request-level parameter is set, the tximplicit parameter is ignored.
    Default : false
    Example : true

    boolean

    txstmtnum
    optional

    Transaction statement number. The transaction statement number must be a positive integer, and must be higher than any previous transaction statement numbers in the transaction. If the transaction statement number is lower than the transaction statement number for any previous statement, an error is generated.
    Example : 10

    integer (int32)

    txtimeout
    optional

    Maximum time to spend on a transaction before timing out. Only applies to BEGIN TRANSACTION statements, or DML statements for which tximplicit is set. For other statements, it is ignored.

    Within a transaction, the request-level timeout parameter is ignored. The transaction timeout clock starts when the BEGIN WORK statement is successful. Once the transaction timeout is reached, no statement is allowed to continue in the transaction.

    The value for this parameter is a string. Its format includes an amount and a mandatory unit, e.g. 10ms (10 milliseconds) or 0.5s (half a second). Valid units are:

    • ns (nanoseconds)

    • us (microseconds)

    • ms (milliseconds)

    • s (seconds)

    • m (minutes)

    • h (hours)

    Specify a duration of 0 to disable. When disabled, the request-level timeout is set to the default.

    The node-level txtimeout setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting. However, if the node-level setting is greater than 0, the transaction timeout for the query is limited to the node-level setting.

    In addition, the cluster-level queryTxTimeout setting specifies the default for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster.

    The default is "15s" for cbq files or scripts, "2m" for interactive cbq sessions or redirected input.
    Example : "30m"

    string (duration)

    use_cbo
    optional

    Specifies whether the cost-based optimizer is enabled.

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

    In addition, the cluster-level queryUseCBO setting specifies the default for this parameter for the whole cluster. When you change the cluster-level setting, the node-level setting is overwritten for all nodes in the cluster.
    Example : true

    boolean

    use_fts
    optional

    Specifies that the query should use a full-text index.

    If the query contains a USING FTS hint, that takes priority over this parameter.

    If the query does not contain a USING FTS hint, and this parameter is set to true, all full-text indexes are considered for the query. If a qualified full-text index is available, it is selected for the query. If none of the available full-text indexes are qualified, the available GSI indexes are considered instead.

    Refer to Flex Indexes for more information.
    Default : false
    Example : true

    boolean

    $<identifier>
    optional

    Applicable if the statement has 1 or more named parameters.

    The name of a named parameter consists of two parts:

    1. The $ character

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

    The value of the named parameter is any JSON value.

    Named parameters apply to prepared also.

    Refer to Examples for details.

    string (any JSON value)

    Credentials

    Name Description Schema

    user
    optional

    An identity for authentication. Note that bucket names may be prefixed with local:, and admin names may be prefixed with admin:.

    string

    pass
    optional

    A password for authentication.

    string

    Response Body

    The response body has the following structure.

    Name Description Schema

    requestID
    optional

    A unique identifier for the response.

    string (UUID)

    clientContextID
    optional

    The client context ID of the request, if one was supplied — see client_context_id in Request Parameters.

    string

    signature
    optional

    The schema of the results. Present only when the query completes successfully.
    Example : { "id" : "json" }

    object

    results
    optional

    An array of all the objects returned by the query. An object can be any JSON value.

    < object > array

    status
    optional

    The status of the request.

    enum (success, running, errors, completed, stopped, timeout, fatal)

    errors
    optional

    An array of 0 or more error objects. If an error occurred during processing of the request, it will be represented by an error object in this list.

    < Conditions > array

    warnings
    optional

    An array of 0 or more warning objects. If a warning occurred during processing of the request, it is represented by a warning object in this list.

    < Conditions > array

    metrics
    optional

    An object containing metrics about the request.

    controls
    optional

    An object containing runtime information provided along with the request. Present only if controls was set to true in the Request Parameters.

    Conditions

    Errors and warnings have the following format.

    Name Description Schema

    code
    required

    A unique number that identifies the error or warning. The code ranges are partitioned by component. The codes can also include parts that indicate severity and transience. This property is always present in every condition returned in the Query REST API or captured in a log.

    integer

    msg
    required

    A message describing the error or warning in detail. This property is always present in every condition returned in the Query REST API or captured in a log.

    string

    name
    optional

    Unique name that has a 1:1 mapping to the code. Uniquely identifies the condition. This property is helpful for pattern matching and can have meaning, making it more memorable than the code. The name should be fully qualified.
    Example : "indexing.scan.io_failure"

    string

    sev
    optional

    One of the following N1QL severity levels, listed in order of severity:

    1. Severe

    2. Error

    3. Warn

    4. Info

    integer

    temp
    optional

    Indicates if the condition is transient — for example, the queue is full. If the value is false, it tells clients and users that a retry without modification produces the same condition.

    boolean

    Additional elements not listed here might also be present. Clients and consumers of the REST API or the logs must accommodate any additional elements.

    Metrics

    Name Description Schema

    elapsedTime
    required

    The total time taken for the request, that is the time from when the request was received until the results were returned.

    string

    executionTime
    required

    The time taken for the execution of the request, that is the time from when query execution started until the results were returned.

    string

    resultCount
    required

    The total number of objects in the results.

    integer (unsigned)

    resultSize
    required

    The total number of bytes in the results.

    integer (unsigned)

    mutationCount
    optional

    The number of mutations that were made during the request.

    integer (unsigned)

    sortCount
    optional

    The number of objects that were sorted. Present only if the request includes ORDER BY.

    If a query includes ORDER BY, LIMIT, or OFFSET clauses, an application can use the sortCount value to give the overall number of results in a message such as "page 1 of N".

    integer (unsigned)

    usedMemory
    optional

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

    integer (unsigned)

    errorCount
    optional

    The number of errors that occurred during the request.

    integer (unsigned)

    warningCount
    optional

    The number of warnings that occurred during the request.

    integer (unsigned)

    Additional elements not listed here might also be present. Clients and consumers of the REST API or the logs must accommodate any additional elements.

    Controls

    Name Description Schema

    scan_consistency
    optional

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

    string

    use_cbo
    optional

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

    boolean

    memoryQuota
    optional

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

    integer (unsigned)

    stmtType
    optional

    The type of query statement.
    Example : "SELECT"

    string

    Additional elements not listed here might also be present. Clients and consumers of the REST API or the logs must accommodate any additional elements.

    Security

    The Query Service API accepts credentials via HTTP basic authentication header, or via the creds request parameter. If a request contains both HTTP basic authentication header and a creds parameter, the creds parameter is ignored and only the HTTP basic authentication header is used for authenticating.

    Header

    Specify a user name and password via HTTP headers. This method can only be used to provide a single credential.

    Type : basic

    Parameter

    Specify user names and passwords via the creds request parameter. This is the only method that can provide multiple credentials for a request.

    Type : basic

    RBAC Role

    Users must have the relevant Administrative or Query & Index RBAC roles, depending on the types of query they intend to run. In addition, users must have permissions on the required buckets, scopes, and collections, where appropriate. Refer to Roles for more details.