The Couchbase Query Service REST API enables developers to execute SQL++ (formerly N1QL) queries against Couchbase Server and manage query service settings. It supports ad-hoc queries, prepared statements, and request-level parameter configuration. The API provides endpoints for query execution, monitoring active requests, and managing query service configuration across cluster nodes.
openapi: 3.1.0
info:
title: Couchbase Query Service REST API
description: >-
The Couchbase Query Service REST API enables developers to execute SQL++
(formerly N1QL) queries against Couchbase Server and manage query service
settings. It supports ad-hoc queries, prepared statements, and
request-level parameter configuration. The API provides endpoints for
query execution, monitoring active requests, and managing query service
configuration across cluster nodes.
version: '7.6'
contact:
name: Couchbase Support
url: https://support.couchbase.com
termsOfService: https://www.couchbase.com/terms-of-use
externalDocs:
description: Couchbase Query Service REST API Documentation
url: https://docs.couchbase.com/server/current/n1ql/n1ql-rest-api/index.html
servers:
- url: https://localhost:8093
description: Query Service (default port)
- url: https://localhost:18093
description: Query Service (SSL)
tags:
- name: Query Admin
description: >-
Endpoints for administrative operations on the Query service including
monitoring active requests, completed requests, and prepared statements.
- name: Query Execution
description: >-
Endpoints for executing SQL++ queries and managing query results.
- name: Query Settings
description: >-
Endpoints for configuring Query service settings at the node and
cluster level.
security:
- basicAuth: []
paths:
/query/service:
get:
operationId: executeQueryGet
summary: Execute a SQL++ query via GET
description: >-
Executes a SQL++ query specified as a query parameter. This endpoint
is intended for situations where use of the POST method is restricted.
tags:
- Query Execution
parameters:
- name: statement
in: query
required: true
description: The SQL++ statement to execute
schema:
type: string
- name: timeout
in: query
required: false
description: Maximum execution time for the query (e.g., 10s, 5m)
schema:
type: string
- name: readonly
in: query
required: false
description: Whether to restrict the query to read-only operations
schema:
type: boolean
- name: pretty
in: query
required: false
description: Whether to format the query results with indentation
schema:
type: boolean
responses:
'200':
description: Query executed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResult'
'400':
description: Invalid query syntax or parameters
'401':
description: Unauthorized access
post:
operationId: executeQueryPost
summary: Execute a SQL++ query via POST
description: >-
Executes a SQL++ query specified in the request body. Supports both
application/json and application/x-www-form-urlencoded content types.
This is the primary method for executing queries and supports all
query parameters including named and positional parameters.
tags:
- Query Execution
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QueryRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/QueryRequest'
responses:
'200':
description: Query executed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResult'
'400':
description: Invalid query syntax or parameters
'401':
description: Unauthorized access
/admin/active_requests:
get:
operationId: listActiveRequests
summary: List active query requests
description: >-
Returns the list of currently active query requests on the node,
including their statement text, execution time, and request ID.
tags:
- Query Admin
responses:
'200':
description: Successful retrieval of active requests
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ActiveRequest'
'401':
description: Unauthorized access
/admin/active_requests/{requestId}:
get:
operationId: getActiveRequest
summary: Get an active request
description: >-
Returns details about a specific active query request.
tags:
- Query Admin
parameters:
- $ref: '#/components/parameters/requestId'
responses:
'200':
description: Successful retrieval of active request details
content:
application/json:
schema:
$ref: '#/components/schemas/ActiveRequest'
'401':
description: Unauthorized access
'404':
description: Request not found
delete:
operationId: cancelActiveRequest
summary: Cancel an active request
description: >-
Cancels a specific active query request by its request ID.
tags:
- Query Admin
parameters:
- $ref: '#/components/parameters/requestId'
responses:
'200':
description: Request cancelled successfully
'401':
description: Unauthorized access
'404':
description: Request not found
/admin/completed_requests:
get:
operationId: listCompletedRequests
summary: List completed query requests
description: >-
Returns the list of recently completed query requests on the node,
including their statement text, execution time, and result count.
tags:
- Query Admin
responses:
'200':
description: Successful retrieval of completed requests
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CompletedRequest'
'401':
description: Unauthorized access
/admin/prepareds:
get:
operationId: listPreparedStatements
summary: List prepared statements
description: >-
Returns the list of prepared statements cached on the node.
tags:
- Query Admin
responses:
'200':
description: Successful retrieval of prepared statements
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PreparedStatement'
'401':
description: Unauthorized access
/admin/prepareds/{name}:
get:
operationId: getPreparedStatement
summary: Get a prepared statement
description: >-
Returns details about a specific prepared statement.
tags:
- Query Admin
parameters:
- name: name
in: path
required: true
description: The name of the prepared statement
schema:
type: string
responses:
'200':
description: Successful retrieval of prepared statement
content:
application/json:
schema:
$ref: '#/components/schemas/PreparedStatement'
'401':
description: Unauthorized access
'404':
description: Prepared statement not found
delete:
operationId: deletePreparedStatement
summary: Delete a prepared statement
description: >-
Removes a specific prepared statement from the cache.
tags:
- Query Admin
parameters:
- name: name
in: path
required: true
description: The name of the prepared statement
schema:
type: string
responses:
'200':
description: Prepared statement deleted successfully
'401':
description: Unauthorized access
'404':
description: Prepared statement not found
/admin/indexes/active_requests:
get:
operationId: listActiveIndexRequests
summary: List active index requests
description: >-
Returns the list of active index request operations being processed
by the Query service.
tags:
- Query Admin
responses:
'200':
description: Successful retrieval of active index requests
content:
application/json:
schema:
type: array
items:
type: object
'401':
description: Unauthorized access
/admin/settings:
get:
operationId: getQuerySettings
summary: Get query service settings
description: >-
Returns the current settings for the Query service node, including
timeout values, memory quotas, and logging configuration.
tags:
- Query Settings
responses:
'200':
description: Successful retrieval of query settings
content:
application/json:
schema:
$ref: '#/components/schemas/QuerySettings'
'401':
description: Unauthorized access
post:
operationId: updateQuerySettings
summary: Update query service settings
description: >-
Updates the configuration settings for the Query service node.
tags:
- Query Settings
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QuerySettings'
responses:
'200':
description: Query settings updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/QuerySettings'
'400':
description: Invalid settings
'401':
description: Unauthorized access
/admin/vitals:
get:
operationId: getQueryVitals
summary: Get query service vitals
description: >-
Returns vital statistics for the Query service node including
request counts, error counts, and resource utilization.
tags:
- Query Admin
responses:
'200':
description: Successful retrieval of query service vitals
content:
application/json:
schema:
$ref: '#/components/schemas/QueryVitals'
'401':
description: Unauthorized access
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic Authentication using Couchbase Server credentials.
parameters:
requestId:
name: requestId
in: path
required: true
description: The unique identifier of the query request
schema:
type: string
schemas:
QueryRequest:
type: object
description: SQL++ query execution request
required:
- statement
properties:
statement:
type: string
description: The SQL++ statement to execute
timeout:
type: string
description: Maximum execution time (e.g., 10s, 5m)
readonly:
type: boolean
description: Whether to restrict to read-only operations
pretty:
type: boolean
description: Whether to format results with indentation
scan_consistency:
type: string
description: Consistency requirement for the query
enum:
- not_bounded
- at_plus
- request_plus
- statement_plus
args:
type: array
description: Positional parameters for the query
items: {}
prepared:
type: string
description: Name of a prepared statement to execute
client_context_id:
type: string
description: Client-provided context identifier for tracking
max_parallelism:
type: string
description: Maximum parallelism for the query
metrics:
type: boolean
description: Whether to include metrics in the response
QueryResult:
type: object
description: SQL++ query execution result
properties:
requestID:
type: string
description: Unique identifier for the request
clientContextID:
type: string
description: Client-provided context identifier
signature:
type: object
description: Schema signature of the results
results:
type: array
description: Array of result documents
items: {}
status:
type: string
description: Query execution status
enum:
- success
- running
- errors
- completed
- stopped
- timeout
- fatal
metrics:
type: object
description: Query execution metrics
properties:
elapsedTime:
type: string
description: Total elapsed time
executionTime:
type: string
description: Execution time excluding fetch
resultCount:
type: integer
description: Number of results returned
resultSize:
type: integer
description: Size of results in bytes
mutationCount:
type: integer
description: Number of mutations performed
errorCount:
type: integer
description: Number of errors encountered
warningCount:
type: integer
description: Number of warnings generated
errors:
type: array
description: List of errors if any occurred
items:
type: object
properties:
code:
type: integer
description: Error code
msg:
type: string
description: Error message
warnings:
type: array
description: List of warnings if any
items:
type: object
properties:
code:
type: integer
description: Warning code
msg:
type: string
description: Warning message
ActiveRequest:
type: object
description: An active query request
properties:
requestId:
type: string
description: Unique identifier for the request
statement:
type: string
description: The SQL++ statement being executed
requestTime:
type: string
description: Time when the request was received
elapsedTime:
type: string
description: Time elapsed since the request started
executionTime:
type: string
description: Time spent executing the query
state:
type: string
description: Current state of the request
scanConsistency:
type: string
description: Consistency level of the query
clientContextID:
type: string
description: Client-provided context identifier
CompletedRequest:
type: object
description: A completed query request
properties:
requestId:
type: string
description: Unique identifier for the request
statement:
type: string
description: The SQL++ statement that was executed
requestTime:
type: string
description: Time when the request was received
elapsedTime:
type: string
description: Total elapsed time for the request
resultCount:
type: integer
description: Number of results returned
resultSize:
type: integer
description: Size of results in bytes
errorCount:
type: integer
description: Number of errors encountered
state:
type: string
description: Final state of the request
PreparedStatement:
type: object
description: A cached prepared statement
properties:
name:
type: string
description: Name of the prepared statement
statement:
type: string
description: The original SQL++ statement
uses:
type: integer
description: Number of times the prepared statement has been used
lastUse:
type: string
description: Time of last use
QuerySettings:
type: object
description: Query service configuration settings
properties:
queryTmpSpaceDir:
type: string
description: Directory for temporary query files
queryTmpSpaceSize:
type: integer
description: Maximum temporary space size in megabytes
queryPipelineBatch:
type: integer
description: Number of items in a batch for pipeline execution
queryPipelineCap:
type: integer
description: Maximum number of items in the pipeline queue
queryScanCap:
type: integer
description: Maximum buffer size for index scans
queryTimeout:
type: string
description: Default timeout for queries (e.g., 0s for unlimited)
queryPreparedLimit:
type: integer
description: Maximum number of prepared statements to cache
queryCompletedLimit:
type: integer
description: Maximum number of completed requests to keep
queryCompletedThreshold:
type: integer
description: >-
Minimum execution time in milliseconds for a request to be
added to the completed requests log
queryLogLevel:
type: string
description: Log level for the Query service
enum:
- debug
- trace
- info
- warn
- error
- severe
- none
queryMaxParallelism:
type: integer
description: Maximum parallelism for query execution
queryN1QLFeatCtrl:
type: integer
description: Feature control flags for N1QL
QueryVitals:
type: object
description: Query service vital statistics
properties:
uptime:
type: string
description: Time since the query service started
local.time:
type: string
description: Local time on the node
version:
type: string
description: Version of the query engine
total.threads:
type: integer
description: Total number of threads
cores:
type: integer
description: Number of CPU cores
gc_num:
type: integer
description: Number of garbage collections
gc_pause_time:
type: string
description: Total garbage collection pause time
gc_pause_percent:
type: string
description: Percentage of time spent in GC
memory_usage:
type: integer
description: Current memory usage in bytes
total_memory_system:
type: integer
description: Total system memory available
request.completed.count:
type: integer
description: Total number of completed requests
request.active.count:
type: integer
description: Number of currently active requests
request.per.sec.1min:
type: number
description: Requests per second over the last minute
request.per.sec.5min:
type: number
description: Requests per second over the last 5 minutes
request.per.sec.15min:
type: number
description: Requests per second over the last 15 minutes