The Couchbase Analytics Service REST API provides access to the Analytics service for running complex analytical queries on operational data without impacting performance of key-value operations. It supports SQL++ queries for analytics, management of links to external data sources, and configuration of user-defined libraries. The service enables real-time analytics on JSON data alongside transactional workloads.
openapi: 3.1.0
info:
title: Couchbase Analytics Service REST API
description: >-
The Couchbase Analytics Service REST API provides access to the Analytics
service for running complex analytical queries on operational data without
impacting performance of key-value operations. It supports SQL++ queries
for analytics, management of links to external data sources, and
configuration of user-defined libraries. The service enables real-time
analytics on JSON data alongside transactional workloads.
version: '7.6'
contact:
name: Couchbase Support
url: https://support.couchbase.com
termsOfService: https://www.couchbase.com/terms-of-use
externalDocs:
description: Couchbase Analytics Service REST API Documentation
url: https://docs.couchbase.com/server/current/analytics/rest-analytics.html
servers:
- url: https://localhost:8095
description: Analytics Service (default port)
- url: https://localhost:18095
description: Analytics Service (SSL)
tags:
- name: Analytics Admin
description: >-
Endpoints for administering and monitoring the Analytics service.
- name: Analytics Configuration
description: >-
Endpoints for configuring Analytics nodes and clusters.
- name: Analytics Library
description: >-
Endpoints for managing JavaScript libraries used for user-defined functions.
- name: Analytics Query
description: >-
Endpoints for executing SQL++ analytics queries and retrieving results.
- name: Analytics Settings
description: >-
Endpoints for configuring Analytics service settings.
security:
- basicAuth: []
paths:
/analytics/service:
post:
operationId: executeAnalyticsQuery
summary: Execute an analytics query
description: >-
Executes a SQL++ analytics query against the Analytics service. The
endpoint implements the same HTTP interface as the Couchbase Query
service but targets the Analytics engine for complex analytical workloads.
tags:
- Analytics Query
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsQueryRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/AnalyticsQueryRequest'
responses:
'200':
description: Query executed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsQueryResult'
'400':
description: Invalid query syntax or parameters
'401':
description: Unauthorized access
/analytics/node/agg/stats/remaining:
get:
operationId: getAnalyticsRemainingMutations
summary: Get remaining mutations to be synced
description: >-
Returns the number of mutations that have not yet been synced to the
Analytics service from the Data service. Useful for monitoring data
ingestion progress.
tags:
- Analytics Admin
responses:
'200':
description: Successful retrieval of remaining mutation counts
content:
application/json:
schema:
type: object
additionalProperties:
type: integer
description: Remaining mutations per dataset
'401':
description: Unauthorized access
/analytics/status/ingestion:
get:
operationId: getAnalyticsIngestionStatus
summary: Get analytics data ingestion status
description: >-
Returns the current status of data ingestion from Couchbase Server
into the Analytics service, including details about each dataset
and its synchronization state.
tags:
- Analytics Admin
responses:
'200':
description: Successful retrieval of ingestion status
content:
application/json:
schema:
type: object
'401':
description: Unauthorized access
/analytics/cluster:
get:
operationId: getAnalyticsClusterStatus
summary: Get analytics cluster status
description: >-
Returns the status of the Analytics cluster including information
about all Analytics nodes and their states.
tags:
- Analytics Admin
responses:
'200':
description: Successful retrieval of cluster status
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsClusterStatus'
'401':
description: Unauthorized access
/analytics/cluster/restart:
post:
operationId: restartAnalyticsCluster
summary: Restart analytics cluster
description: >-
Restarts the Analytics service across all nodes in the cluster.
tags:
- Analytics Admin
responses:
'202':
description: Restart initiated successfully
'401':
description: Unauthorized access
/analytics/config/service:
get:
operationId: getAnalyticsServiceConfig
summary: Get analytics service configuration
description: >-
Returns the current configuration of the Analytics service.
tags:
- Analytics Configuration
responses:
'200':
description: Successful retrieval of service configuration
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsServiceConfig'
'401':
description: Unauthorized access
put:
operationId: updateAnalyticsServiceConfig
summary: Update analytics service configuration
description: >-
Updates the configuration settings for the Analytics service.
tags:
- Analytics Configuration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsServiceConfig'
responses:
'200':
description: Configuration updated successfully
'400':
description: Invalid configuration
'401':
description: Unauthorized access
/analytics/config/node:
get:
operationId: getAnalyticsNodeConfig
summary: Get analytics node configuration
description: >-
Returns the configuration of the current Analytics node.
tags:
- Analytics Configuration
responses:
'200':
description: Successful retrieval of node configuration
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsNodeConfig'
'401':
description: Unauthorized access
put:
operationId: updateAnalyticsNodeConfig
summary: Update analytics node configuration
description: >-
Updates the configuration settings for the current Analytics node.
tags:
- Analytics Configuration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsNodeConfig'
responses:
'200':
description: Node configuration updated successfully
'400':
description: Invalid configuration
'401':
description: Unauthorized access
/settings/analytics:
get:
operationId: getAnalyticsSettings
summary: Get analytics settings
description: >-
Returns the current cluster-level Analytics service settings.
tags:
- Analytics Settings
responses:
'200':
description: Successful retrieval of analytics settings
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsSettings'
'401':
description: Unauthorized access
post:
operationId: updateAnalyticsSettings
summary: Update analytics settings
description: >-
Updates the cluster-level Analytics service settings.
tags:
- Analytics Settings
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/AnalyticsSettings'
responses:
'200':
description: Analytics settings updated successfully
'400':
description: Invalid settings
'401':
description: Unauthorized access
/analytics/library/{scope}/{name}:
put:
operationId: createOrUpdateLibrary
summary: Create or update a library
description: >-
Creates or updates a JavaScript library that can be used to define
SQL++ user-defined functions in the Analytics service.
tags:
- Analytics Library
parameters:
- name: scope
in: path
required: true
description: The scope of the library
schema:
type: string
- name: name
in: path
required: true
description: The name of the library
schema:
type: string
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
description: The JavaScript library code
responses:
'200':
description: Library created or updated successfully
'400':
description: Invalid library code
'401':
description: Unauthorized access
delete:
operationId: deleteLibrary
summary: Delete a library
description: >-
Deletes a JavaScript library from the Analytics service.
tags:
- Analytics Library
parameters:
- name: scope
in: path
required: true
description: The scope of the library
schema:
type: string
- name: name
in: path
required: true
description: The name of the library
schema:
type: string
responses:
'200':
description: Library deleted successfully
'401':
description: Unauthorized access
'404':
description: Library not found
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic Authentication using Couchbase Server credentials.
schemas:
AnalyticsQueryRequest:
type: object
description: Analytics query execution request
required:
- statement
properties:
statement:
type: string
description: The SQL++ analytics statement to execute
pretty:
type: boolean
description: Whether to format the results with indentation
readonly:
type: boolean
description: Whether to restrict to read-only operations
client_context_id:
type: string
description: Client-provided context identifier for request tracking
timeout:
type: string
description: Maximum execution time for the query (e.g., 10s, 5m)
scan_consistency:
type: string
description: Consistency requirement for the query
enum:
- not_bounded
- request_plus
args:
type: array
description: Positional parameters for the query
items: {}
AnalyticsQueryResult:
type: object
description: Analytics 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
resultCount:
type: integer
description: Number of results returned
resultSize:
type: integer
description: Size of results in bytes
processedObjects:
type: integer
description: Number of objects processed
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
AnalyticsClusterStatus:
type: object
description: Analytics cluster status information
properties:
state:
type: string
description: Overall state of the Analytics cluster
enum:
- ACTIVE
- UNUSABLE
- RECOVERING
nodes:
type: array
description: List of Analytics nodes and their states
items:
type: object
properties:
nodeId:
type: string
description: Node identifier
state:
type: string
description: State of the individual node
partitions:
type: array
description: Data partitions on the node
items:
type: object
AnalyticsServiceConfig:
type: object
description: Analytics service configuration
properties:
activeMemoryGlobalBudget:
type: integer
description: Global memory budget in bytes
activeStopTimeout:
type: integer
description: Timeout for stopping active operations in seconds
activeSuspendTimeout:
type: integer
description: Timeout for suspending active operations in seconds
analyticsBroadcastDcpStateMutationCount:
type: integer
description: DCP state mutation broadcast count
compilerFrameLimit:
type: integer
description: Maximum number of frames in a query plan
compilerGroupmemory:
type: integer
description: Memory allocated for groupby operations in bytes
compilerJoinmemory:
type: integer
description: Memory allocated for join operations in bytes
compilerSortmemory:
type: integer
description: Memory allocated for sort operations in bytes
logLevel:
type: string
description: Log level for the Analytics service
enum:
- DEBUG
- TRACE
- INFO
- WARN
- ERROR
- FATAL
AnalyticsNodeConfig:
type: object
description: Analytics node-level configuration
properties:
storageBuffercachePagesize:
type: integer
description: Buffer cache page size in bytes
storageBuffercacheSize:
type: integer
description: Buffer cache size in bytes
storageMemorycomponentNumcomponents:
type: integer
description: Number of memory components
AnalyticsSettings:
type: object
description: Cluster-level analytics settings
properties:
numReplicas:
type: integer
description: Number of Analytics replicas
minimum: 0
maximum: 3