--- title: Query Service REST API pubDate: 2026-08-17T09:53:44.266Z antora: editUrl: https://github.com/couchbaselabs/cb-swagger/edit/release/7.6/docs/modules/n1ql-rest-query/pages/index.adoc xref: xref:7.6@server:n1ql-rest-query:index.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/server/7.6/n1ql-rest-query/index.html) # Query Service REST API ## [](#overview)Overview The Query Service REST API is provided by the Query Service. This API enables you to run SQL++ queries and set request-level parameters. ### Version information **Version:** 7.6 ### Host information {scheme}://{host}:{port} The URL scheme, host, and port are as follows. | Component | Description | | ---------- | --------------------------------------------------------------------------------------- | | **scheme** | The URL scheme. Use https for secure access. **Values:** http, https | | **host** | The host name or IP address of a node running the Query Service. **Example:** localhost | | **port** | The Query Service REST port. Use 18093 for secure access. **Values:** 8093, 18093 | ### Examples on this page In the HTTP request examples: * `$BASEPATH` is the URL scheme, host, and port for a node running the Query Service. * `$USER` is the user name of an authorized user — see [Security](#security). * `$PASSWORD` is the password to connect to Couchbase Server. ## [](#resources)Resources This section describes the operations available with this REST API. [GET-Only Query Service](#get%5Fservice) [Query Service](#post%5Fservice) ### [](#get%5Fservice)GET-Only Query Service GET /query/service #### [](#get%5Fservice-description)Description Enables you to execute a SQL++ statement. This method allows you to run SELECT queries and other DML statements, and specify query parameters. This endpoint is intended for situations where use of the `POST` method is restricted. Produces * application/json #### [](#get%5Fservice-parameters)Parameters Query Parameters | Name | Description | Schema | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | **body**required | Specify the parameters in the query URL in URL-encoded format. The format for URL-encoded parameters is consistent with the syntax for variables according to RFC 6570. | [Request Parameters](#Request) | #### [](#get%5Fservice-responses)Responses This section describes the response HTTP status codes. | HTTP Code | Description | Schema | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | | 200 | The operation was successful. | [Response Body](#Response) | | 400 | Bad Request. The request cannot be processed for one of the following reasons: the statement contains a SQL++ 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. | [Response Body](#Response) | | 401 | Unauthorized. The credentials provided with the request are missing or invalid. | | | 403 | Forbidden. A read-only violation occurred. 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. | | | 404 | Not found. The statement in the request references an invalid namespace or keyspace. | [Response Body](#Response) | | 405 | Method not allowed. The statement in the request references an invalid namespace or keyspace. | | | 409 | Conflict. The request attempted to create an object (keyspace or index) that already exists. | | | 410 | Gone. The server is shutting down gracefully. Previously made requests are being completed, but no new requests are being accepted. | | | 413 | Payload too large. The query is too large for the Query Service to process. | | | 500 | Internal server error. An unforeseen problem occurred processing the request. | | | 503 | Service unavailable. An issue (that's possibly temporary) is preventing the request being processed; the request queue is full or the data store is not accessible. | [Response Body](#Response) | #### [](#get%5Fservice-security)Security | Type | Name | | ------------ | -------------------------------- | | http (basic) | [Header](#security-Header) | | apiKey | [Parameter](#security-Parameter) | #### [](#get%5Fservice-ex-curl)Example HTTP Request ```sh curl -v $BASEPATH/query/service?statement=SELECT%20name%20FROM%20%60travel-sample%60.inventory.hotel%20LIMIT%201%3B \ -u $USER:$PASSWORD ``` For more examples, see [Examples](../n1ql/n1ql-rest-api/examplesrest.md). #### [](#get%5Fservice-ex-response)Example HTTP Response Response 200 ```json { "requestID" : "615e0b26-dd61-4a1a-bda9-22333193b982", "signature" : { "name" : "json" }, "results" : [ { "name" : "Medway Youth Hostel" } ], "status" : "success", "metrics" : { "elapsedTime" : "5.232754ms", "executionTime" : "5.160022ms", "resultCount" : 1, "resultSize" : 30, "serviceLoad" : 12 } } ``` Response 400 SQL++ Error ```json { "requestID" : "27087759-07af-431d-a3d7-29080f870e56", "errors" : [ { "code" : 3000, "msg" : "syntax error - line 1, column 7, near 'SLECT', at: name" } ], "status" : "fatal", "metrics" : { "elapsedTime" : "1.478631ms", "executionTime" : "1.393274ms", "resultCount" : 0, "resultSize" : 0, "serviceLoad" : 12, "errorCount" : 1 } } ``` Request Error ```json { "requestID" : "424c0a6d-b851-4feb-892c-0d9a106f2e13", "errors" : [ { "code" : 1050, "msg" : "No statement or prepared value" } ], "status" : "fatal", "metrics" : { "elapsedTime" : "1.124637ms", "executionTime" : "1.094663ms", "resultCount" : 0, "resultSize" : 0, "serviceLoad" : 0, "errorCount" : 1 } } ``` Response 404 ```json { "requestID" : "d30b805f-6c1e-44ec-9aec-35ff711a6e88", "errors" : [ { "code" : 12003, "msg" : "Keyspace not found in CB datastore: default:travel-sample.inventory.motel" } ], "status" : "fatal", "metrics" : { "elapsedTime" : "3.096786ms", "executionTime" : "2.468282ms", "resultCount" : 0, "resultSize" : 0, "serviceLoad" : 12, "errorCount" : 1 } } ``` Response 503 ```json { "requestID" : "5c0a6a81-2fc8-4a33-a035-ed7fb1512710", "errors" : [ { "code" : "", "msg" : "Request queue full" } ], "status" : "errors", "metrics" : { "elapsedTime" : "134.7944us", "executionTime" : "130.5518us", "resultCount" : 0, "resultSize" : 0, "mutationCount" : 0, "errorCount" : 1, "warningCount" : 0 } } ``` ### [](#post%5Fservice)Query Service POST /query/service #### [](#post%5Fservice-description)Description Enables you to execute a SQL++ statement. This method allows you to run SELECT queries and other DML statements, and specify query parameters. Consumes * application/json * application/x-www-form-urlencoded Produces * application/json #### [](#post%5Fservice-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. Body Parameter | Name | Description | Schema | | ---------------- | -------------------------------------------------- | ------------------------------ | | **Body**required | An object specifying one or more query parameters. | [Request Parameters](#Request) | #### [](#post%5Fservice-responses)Responses This section describes the response HTTP status codes. | HTTP Code | Description | Schema | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | | 200 | The operation was successful. | [Response Body](#Response) | | 400 | Bad Request. The request cannot be processed for one of the following reasons: the statement contains a SQL++ 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. | [Response Body](#Response) | | 401 | Unauthorized. The credentials provided with the request are missing or invalid. | | | 403 | Forbidden. A read-only violation occurred. 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. | | | 404 | Not found. The statement in the request references an invalid namespace or keyspace. | [Response Body](#Response) | | 405 | Method not allowed. The statement in the request references an invalid namespace or keyspace. | | | 409 | Conflict. The request attempted to create an object (keyspace or index) that already exists. | | | 410 | Gone. The server is shutting down gracefully. Previously made requests are being completed, but no new requests are being accepted. | | | 413 | Payload too large. The query is too large for the Query Service to process. | | | 500 | Internal server error. An unforeseen problem occurred processing the request. | | | 503 | Service unavailable. An issue (that's possibly temporary) is preventing the request being processed; the request queue is full or the data store is not accessible. | [Response Body](#Response) | #### [](#post%5Fservice-security)Security | Type | Name | | ------------ | -------------------------------- | | http (basic) | [Header](#security-Header) | | apiKey | [Parameter](#security-Parameter) | #### [](#post%5Fservice-ex-curl)Example HTTP Request Form Data Because it's sent as form data, the statement in this example avoids using a semicolon. ```sh curl -v $BASEPATH/query/service \ -d 'statement=SELECT name FROM `travel-sample`.inventory.hotel LIMIT 1' \ -u $USER:$PASSWORD ``` JSON Because it's sent as a JSON object, the statement in this example can contain a semicolon. ```sh curl -v $BASEPATH/query/service \ -H 'Content-Type: application/json' \ -d '{ "statement": "SELECT name FROM `travel-sample`.inventory.hotel LIMIT 1;" }' \ -u $USER:$PASSWORD ``` For more examples, see [Examples](../n1ql/n1ql-rest-api/examplesrest.md). #### [](#post%5Fservice-ex-request)Example Request Body Named Parameters This request uses named parameters. ```json { "statement" : "SELECT airline FROM `travel-sample`.inventory.route WHERE sourceairport = $aval AND distance > $dval", "$aval" : "LAX", "$dval" : 13000 } ``` Numbered Positional Parameters This request uses numbered positional parameters. ```json { "statement" : "SELECT airline FROM `travel-sample`.inventory.route WHERE sourceairport = $1 AND distance > $2", "args" : [ "LAX", 13000 ] } ``` Unnumbered Positional Parameters This request uses unnumbered positional parameters. ```json { "statement" : "SELECT airline FROM `travel-sample`.inventory.route WHERE sourceairport = ? AND distance > ?", "args" : [ "LAX", 13000 ] } ``` Wildcards This request uses a wildcard. The `%` symbol is the escape character in URIs, so when using `%` as a wildcard in a query, you may need to escape it by replacing it with its corresponding ASCII code `%25`. ```json { "statement" : "SELECT meta().id FROM `travel-sample`.inventory.hotel WHERE meta().id LIKE $pattern", "$pattern" : "hotel_1002%" } ``` Authentication Parameter This request authenticates using a request parameter. You must use this method of authentication if a request requires more than one set of credentials. ```json { "statement" : "SELECT hotel.name, airport.airportname FROM `travel-sample`.inventory.hotel JOIN `travel-sample`.inventory.airport ON hotel.city = airport.city LIMIT 1", "creds" : [ { "user" : "local:User", "pass" : "password" }, { "user" : "admin:Administrator", "pass" : "password" } ] } ``` Bounded Consistency with a Scan Vector This request uses `at_plus` consistency with a sparse scan vector. ```json { "statement" : "SELECT name FROM `travel-sample`.inventory.hotel LIMIT 1;", "scan_consistency" : "at_plus", "scan_vector" : { "5" : [ 5409393, "VB5ID" ], "19" : [ 47574574, "VB19ID" ] } } ``` #### [](#post%5Fservice-ex-response)Example HTTP Response Response 200 ```json { "requestID" : "615e0b26-dd61-4a1a-bda9-22333193b982", "signature" : { "name" : "json" }, "results" : [ { "name" : "Medway Youth Hostel" } ], "status" : "success", "metrics" : { "elapsedTime" : "5.232754ms", "executionTime" : "5.160022ms", "resultCount" : 1, "resultSize" : 30, "serviceLoad" : 12 } } ``` Response 400 SQL++ Error ```json { "requestID" : "27087759-07af-431d-a3d7-29080f870e56", "errors" : [ { "code" : 3000, "msg" : "syntax error - line 1, column 7, near 'SLECT', at: name" } ], "status" : "fatal", "metrics" : { "elapsedTime" : "1.478631ms", "executionTime" : "1.393274ms", "resultCount" : 0, "resultSize" : 0, "serviceLoad" : 12, "errorCount" : 1 } } ``` Request Error ```json { "requestID" : "424c0a6d-b851-4feb-892c-0d9a106f2e13", "errors" : [ { "code" : 1050, "msg" : "No statement or prepared value" } ], "status" : "fatal", "metrics" : { "elapsedTime" : "1.124637ms", "executionTime" : "1.094663ms", "resultCount" : 0, "resultSize" : 0, "serviceLoad" : 0, "errorCount" : 1 } } ``` Response 404 ```json { "requestID" : "d30b805f-6c1e-44ec-9aec-35ff711a6e88", "errors" : [ { "code" : 12003, "msg" : "Keyspace not found in CB datastore: default:travel-sample.inventory.motel" } ], "status" : "fatal", "metrics" : { "elapsedTime" : "3.096786ms", "executionTime" : "2.468282ms", "resultCount" : 0, "resultSize" : 0, "serviceLoad" : 12, "errorCount" : 1 } } ``` Response 503 ```json { "requestID" : "5c0a6a81-2fc8-4a33-a035-ed7fb1512710", "errors" : [ { "code" : "", "msg" : "Request queue full" } ], "status" : "errors", "metrics" : { "elapsedTime" : "134.7944us", "executionTime" : "130.5518us", "resultCount" : 0, "resultSize" : 0, "mutationCount" : 0, "errorCount" : 1, "warningCount" : 0 } } ``` ## [](#models)Definitions This section describes the properties consumed and returned by this REST API. [Request Parameters](#Request) [Credentials](#RequestCredentials) [Scan Vector](#RequestScanVector) [Full Scan Vector](#RequestScanVectorFull) [Sparse Scan Vector](#RequestScanVectorSparse) [Value-Guard Entry](#RequestScanVectorValueGuard) [Scan Vectors](#RequestScanVectors) [Response Body](#Response) [Conditions](#ResponseConditions) [Controls](#ResponseControls) [Metrics](#ResponseMetrics) [Profile](#ResponseProfile) [Execution Timings](#ResponseProfileTiming) [Statistics](#ResponseProfileTimingStats) ### [](#Request)Request Parameters Object | Property | | Schema | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | **args**optional | Supplies the values for positional parameters in the statement. Applicable if the statement or prepared statement contains 1 or more positional parameters. The value is an array of JSON values, one for each positional parameter in the statement. For more information, see [Named Parameters and Positional Parameters](../n1ql/n1ql-manage/query-settings.html#section%5Fsrh%5Ftlm%5Fn1b). **Example:** \["LAX",6\] | Any Type array | | **atrcollection**optional | Specifies the collection where the [active transaction record](/server/7.6/learn/data/transactions.html#active-transaction-record-entries) (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](../n1ql-rest-admin/index.html#atrcollection-srv) 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're created. This saves you from having to make two separate requests in cases where you want to prepare a statement and execute it immediately. For more information, see [Auto-Execute](../n1ql/n1ql-language-reference/prepare.html#auto-execute). **Default:** false **Example:** true | Boolean | | **client\_context\_id**optional | A piece of data supplied by the client that's echoed in the response, if present. SQL++ is agnostic about the content of this parameter; it's 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. **Values:** "ZIP", "RLE", "LZMA", "LZO", "NONE" **Default:** "NONE" **Example:** "zip" | String | | **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](../n1ql-rest-admin/index.html#controls-srv) 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](#RequestCredentials) array | | **durability\_level**optional | The level of [durability](/server/7.6/learn/data/durability.html) 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. 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. **Values:** "", "none", "majority", "majorityAndPersistActive", "persistToMajority" **Default:** "majority" **Example:** "none" | String | | **encoded\_plan**optional | In Couchbase Server 6.5 and later, this parameter is ignored and has no effect. It's 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. **Values:** "JSON", "XML", "CSV", "TSV" **Default:** "JSON" **Example:** "XML" | String | | **kvtimeout**optional | The approximate time to wait for a KV get operation before timing out. This applies to statements within a transaction, and to non-transactional statements, whether durability\_level is set or not. If use\_replica is enabled for a query, then this parameter also specifies the approximate time to wait before fetching data from a replica vBucket when the active vBucket is inaccessible. 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 default value is the same as the number of partitions of the index selected for the query. The [node-level](../n1ql-rest-admin/index.html#max-parallelism-srv) 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](../n1ql-rest-settings/index.html#queryMaxParallelism) 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. **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. 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 [node-level](../n1ql-rest-admin/index.html#memory-quota-srv) 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](../n1ql-rest-settings/index.html#queryMemoryQuota) 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 | Reserved for future use. This parameter is ignored and has no effect. | Integer (int32) | | **pipeline\_batch**optional | Controls the number of items execution operators can batch for Fetch from the KV. The [node-level](../n1ql-rest-admin/index.html#pipeline-batch-srv) 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](../n1ql-rest-settings/index.html#queryPipelineBatch) 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](../n1ql-rest-admin/index.html#pipeline-cap-srv) 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](../n1ql-rest-settings/index.html#queryPipelineCap) 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 SQL++ statement to be executed. For examples, see [EXECUTE](../n1ql/n1ql-language-reference/execute.html). 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 | 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](../n1ql-rest-admin/index.html#pretty-srv) 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](../n1ql-rest-admin/index.html#profile-srv) profile setting specifies the default for this parameter for a single node. The request-level parameter overrides the node-level setting. **Values:** "off", "phases", "timings" **Example:** "phases" | String | | **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](../n1ql-rest-admin/index.html#scan-cap-srv) 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](../n1ql-rest-settings/index.html#queryScanCap) 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. When scan consistency is set to at\_plus, you must also specify the scan\_vector parameter for queries using a single keyspace, or the scan\_vectors parameter for queries using multiple keyspaces. This is used as a lower bound for the statements in the request. You can use this setting 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. 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. For more information, see [Transactional Scan Consistency](../n1ql/n1ql-manage/query-settings.html#transactional-scan-consistency). The default transactional scan consistency is RYOW for each statement within the transaction. If you want to disable RYOW for a statement within the transaction, set scan\_consistency for that statement to not\_bounded. **Values:** "not\_bounded", "at\_plus", "request\_plus", "statement\_plus" **Default:** "not\_bounded" **Example:** "at\_plus" | String | | **scan\_vector**optional | Specifies the lower bound vector timestamp for a single keyspace when using at\_plus scan consistency. The scan vector may be full or sparse. A full scan vector is an array of \[value, guard\] entries, giving an entry for every vBucket in the system. A sparse scan vector is an object mapping \[value, guard\] entries to specific vBuckets. The name of each property in the object is a vBucket number (a string). | [Scan Vector](#RequestScanVector) | | **scan\_vectors**optional | Specifies the lower bound vector timestamps for multiple keyspaces when using at\_plus scan consistency. An object mapping scan vectors to keyspaces. The name of each property in the object is a keyspace name. | [Scan Vectors](#RequestScanVectors) | | **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 start 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 | | **sort\_projection**optional | If true, causes statement projection terms to be sorted alphabetically. If false (the default), statement projection terms are returned in the order specified by the query. **Default:** false **Example:** true | Boolean | | **statement**optional | Required if prepared not provided. Any valid SQL++ statement for a POST request, or a read-only SQL++ statement (SELECT, EXPLAIN) for a GET request. If both prepared and statement are present and non-empty, an error is returned. When specifying the request parameters as form data, the statement may not contain an unescaped semicolon (;). If it does, the Query Service responds with error 1040\. To avoid this, either URL-encode the semicolon as %3B, or just omit the semicolon if possible. This restriction does not apply when specifying the request parameters in JSON format. **Example:** "SELECT \* FROM \`travel-sample\`.inventory.hotel LIMIT 1" | String | | **timeout**optional | Maximum time to spend on the request before timing out (s). The value for this parameter is a string. Its format includes an amount and an optional unit: for example, 10ms (10 milliseconds) or 0.5s (half a second). If not specified, the default unit is s (seconds). 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 tximplicit or txid is set, this parameter is ignored. The request inherits the remaining time of the transaction as timeout. The [node-level](../n1ql-rest-admin/index.html#timeout-srv) 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](../n1ql-rest-settings/index.html#queryTimeout) 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" | UUID (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's 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 default is "15s" for cbq files or scripts, "2m" for interactive cbq sessions or redirected input. The [node-level](../n1ql-rest-admin/index.html#txtimeout-srv) 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](../n1ql-rest-settings/index.html#queryTxTimeout) 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. **Example:** "30m" | String (duration) | | **use\_cbo**optional | Specifies whether the cost-based optimizer is enabled. The [node-level](../n1ql-rest-admin/index.html#use-cbo-srv) 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](../n1ql-rest-settings/index.html#queryUseCBO) 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 | [ENTERPRISE EDITION](https://www.couchbase.com/products/editions) Specifies that the query should use a Search 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 Search indexes are considered for the query. If a qualified Search index is available, it's selected for the query. If none of the available Search indexes are qualified, the available GSI indexes are considered instead. For more information, see [Flex Indexes](../n1ql/n1ql-language-reference/flex-indexes.html). **Default:** false **Example:** true | 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 this request. on — read from replica is enabled for this request, unless it has been disabled for all requests at node level. unset — read from replica is specified by the node-level setting. If the node-level setting is also unset, read from replica is disabled for this 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. You cannot currently start KV range scans 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. The [node-level](../n1ql-rest-admin/index.html#use-replica-srv) use-replica setting specifies the default for this property for a single node. The request-level parameter usually overrides the node-level setting. However, when the node-level setting is off, the request-level parameter cannot enable the property. In addition, the [cluster-level](../n1ql-rest-settings/index.html#queryUseReplica) 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. **Values:** "off", "on", "unset" **Default:** "unset" **Example:** "on" | String | | **<$identifier>**additionalproperty | Supplies the value for a named parameter in the statement. Applicable if the statement or prepared statement contains 1 or more named parameters. The name of this property consists of two parts: The $ character or the @ character. An identifier that specifies the name of the parameter. This must start with an alpha character, followed by one or more alphanumeric characters. The value of the named parameter can be any JSON value. For more information, see [Named Parameters and Positional Parameters](../n1ql/n1ql-manage/query-settings.html#section%5Fsrh%5Ftlm%5Fn1b). **Nullable:** yes **Example:** LAX | Any Type | #### Credentials Object | Property | | Schema | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | **user**optional | An identity for authentication. Bucket names may be prefixed with local:, and admin names may be prefixed with admin:. **Example:** "local:bucket-name" | String | | **pass**optional | A password for authentication. **Example:** "password" | String (password) | #### Scan Vector Composite Schema | One of …​ | | Schema | | --------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | | An array of \[value, guard\] entries, giving an entry for every vBucket in the system. | [Full Scan Vector](#RequestScanVectorFull) | | or | An object providing entries for specific vBuckets, mapping a vBucket number (a string) to each \[value, guard\] entry. | [Sparse Scan Vector](#RequestScanVectorSparse) | #### Full Scan Vector Array | Item | | Schema | | ---- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | …​ | A nested array containing two elements, the value and the guard. **Minimum items:** 2 **Maximum items:** 2 | [Value-Guard Entry](#RequestScanVectorValueGuard) | #### Sparse Scan Vector Object | Property | | Schema | | ------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | ****additionalproperty | A nested array containing two elements, the value and the guard. **Minimum items:** 2 **Maximum items:** 2 | [Value-Guard Entry](#RequestScanVectorValueGuard) | #### Value-Guard Entry Array | Item | | Schema | | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | …​ | The first item is the value. This is a vBucket's sequence number (a JSON number). The second item is the guard. This is a vBucket's UUID (a string). **Nullable:** yes | Any Type | #### Scan Vectors Object | Property | | Schema | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | ****additionalproperty | Specifies the lower bound vector timestamp for a single keyspace when using at\_plus scan consistency. The scan vector may be full or sparse. A full scan vector is an array of \[value, guard\] entries, giving an entry for every vBucket in the system. A sparse scan vector is an object mapping \[value, guard\] entries to specific vBuckets. The name of each property in the object is a vBucket number (a string). | [Scan Vector](#RequestScanVector) | ### [](#Response)Response Body Object | Property | | Schema | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | **requestID**optional | A unique identifier for the response. | UUID (UUID) | | **clientContextID**optional | The client context ID of the request, if one was supplied — see client\_context\_id in the 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. | Any Type array | | **status**optional | The status of the request. **Values:** "success", "running", "errors", "completed", "stopped", "timeout", "fatal" | String | | **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](#ResponseConditions) array | | **warnings**optional | An array of 0 or more warning objects. If a warning occurred during processing of the request, it's represented by a warning object in this list. | [Conditions](#ResponseConditions) array | | **metrics**optional | An object containing metrics about the request. | [Metrics](#ResponseMetrics) | | **controls**optional | An object containing runtime information provided along with the request. Present only if controls was set to true in the request parameters. | [Controls](#ResponseControls) | | **profile**optional | An object containing monitoring and profiling information about the request. Present only if profile was set to "phases" or "timings" in the request parameters. | [Profile](#ResponseProfile) | #### Conditions Object | Property | | 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 SQL++ severity levels, listed in order of severity: Severe Error Warn 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. #### Controls Object | Property | | 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. #### Metrics Object | Property | | Schema | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | **elapsedTime**required | The total time taken for the request — in other words, 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 — in other words, 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. #### Profile Object | Property | | Schema | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | **requestTime**required | Timestamp when the query was received. | Date (date-time) | | **servicingHost**required | IP address and port number of the node where the query was executed. | String | | **phaseCounts**required | Count of documents processed at selective phases involved in the query execution, such as authorize, index scan, fetch, parse, plan, run, etc. **Example:** {"fetch":16,"indexScan":187} | Object | | **phaseOperators**required | Indicates the numbers of each kind of query operator involved in different phases of the query processing. For instance, a non-covering index path might involve one index scan and one fetch operator. A join would probably involve two or more fetches, one per keyspace. A union select would have twice as many operator counts, one per each branch of the union. This is in essence the count of all the operators in the executionTimings object. **Example:** {"authorize":1,"fetch":1,"indexScan":2} | Object | | **phaseTimes**required | Cumulative execution times for various phases involved in the query execution, such as authorize, index scan, fetch, parse, plan, run, etc. **Example:** {"authorize":"823.631µs","fetch":"656.873µs","indexScan":"29.146543ms","instantiate":"236.221µs","parse":"826.382µs","plan":"11.831101ms","run":"16.892181ms"} | Object | | **executionTimings**optional | Present only if profile was set to "timings" in the request parameters. The execution details for various phases involved in the query execution, such as kernel and service execution times, number of documents processed at each query operator in each phase, and number of phase switches. | [Execution Timings](#ResponseProfileTiming) | #### Execution Timings Object | Property | | Schema | | --------------------- | ---------------------------------------------------------------- | ----------------------------------------- | | **#operator**required | Name of the operator. **Example:** "Fetch" | String | | **#stats**required | Statistics collected for the operator. | [Statistics](#ResponseProfileTimingStats) | | **\~child**optional | Further nested operators, each with their own execution timings. | Object | #### Statistics Object | Property | | Schema | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | **#itemsIn**optional | Number of input documents to the operator. **Example:** 187 | Integer (int32) | | **#itemsOut**optional | Number of output documents after the operator processing. **Example:** 16 | Integer (int32) | | **#phaseSwitches**optional | Number of switches between executing, waiting for services, or waiting for the goroutine scheduler. **Example:** 413 | Integer (int32) | | **execTime**optional | Time spent executing the operator code inside SQL++ query engine. **Example:** "128.434µs" | String (duration) | | **kernTime**optional | Time spent waiting to be scheduled for CPU time. **Example:** "15.027879ms" | String (duration) | | **servTime**optional | Time spent waiting for another service, such as index or data. For index scan, it's time spent waiting for GSI/indexer. For fetch, it's time spent waiting on the KV store. **Example:** "1.590934ms" | String (duration) | > [!TIP] > The `kernTime`, `servTime`, and `execTime` statistics can be helpful in troubleshooting query performance issues. For example: > > * A high `servTime` for a low number of items processed is an indication that the indexer or KV store is stressed. > * A high `kernTime` means there is a downstream issue in the query plan or the query server having many requests to process, so the scheduled waiting time will be more for CPU time. ## [](#security)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. ### [](#security-Header)Header Specify a user name and password via HTTP headers. This method can only be used to provide a single credential. **Type:** http ### [](#security-Parameter)Parameter Specify user names and passwords via the `creds` request parameter. This is the only method that can provide multiple credentials for a request. API Key **Key parameter:** creds **Key in:** query ### [](#rbac-role)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. For more information, see [Roles](../learn/security/roles.md). ## [](#see-also)See Also * For cluster-level settings, see the [Query Settings REST API](../n1ql-rest-settings/index.md#Settings). * For node-level settings, see the [Admin REST API](../n1ql-rest-admin/index.md#Settings).