Analytics REST API

Analytics provides REST APIs that a client application can use to invoke services using simple HTTP methods. A catalog of available REST resources and requests is provided below.

The Analytics REST APIs can be called on any node running the analytics service. By default, the Analytics REST endpoints below listen on the port 8095.

For the examples, we assume that:

  • You’re running a Couchbase node with the Analytics service using the default port on localhost.

  • You authenticate as a user with the "Full Administrator" role with the user name "Administrator" and the password "password".

Service API

Description Returns result for query as JSON.

Method POST

Endpoint /analytics/service — the alternative /query/service is offered for tools compatibility

Authentication A user with one of the following RBAC roles:

  • Full Admin

  • Cluster Admin

  • Analytics Manager

  • Analytics Reader

Parameters See Query Parameters for a complete list of query parameters.

By default, the API accepts parameters using the application/x-www-form-urlencoded MIME type. You can specify the application/json MIME type using the Content-Type header of the POST request.

Responses See Query Responses for a complete list of query responses.

Command — uses URL encoded data

$ curl -v -u Administrator:password --data-urlencode "statement=select 1;" http://localhost:8095/analytics/service

Command — posts the query statement as data of type application/json and adds a client context ID

curl -v -u Administrator:password -H "Content-Type: application/json" -d '{
    "statement":"select 1;",
    "pretty":true,
    "client_context_id":"xyz"
}' http://localhost:8095/analytics/service

Sample response

* Connected to localhost (127.0.0.1) port 8095 (#0)
* Server auth using Basic with user 'Administrator'
> POST /analytics/service HTTP/1.1
> Host: localhost:8095
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.60.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 69
>
* upload completely sent off: 69 out of 69 bytes
< HTTP/1.1 200 OK
< transfer-encoding: chunked
< connection: keep-alive
< content-type: application/json; charset=utf-8
< Access-Control-Allow-Origin: http://localhost:19006
< Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept
<
{
	"requestID": "c1984db0-f135-48ee-aea0-39dfe02d55ea",
	"clientContextID": "xyz",
	"signature": {
		"*": "*"
	},
	"results": [ {
		"$1" : 1
	} ]
	,
	"plans":{},
	"status": "success",
	"metrics": {
		"elapsedTime": "41.969099ms",
		"executionTime": "31.36645ms",
		"resultCount": 1,
		"resultSize": 15,
		"processedObjects": 0
	}
}

Request Cancellation API

Description Cancels an active request.

Method DELETE

Endpoint /analytics/admin/active_requests

Authentication A user with one of the following RBAC roles:

  • Full Admin

  • Cluster Admin

  • Analytics Manager

  • Analytics Reader

Parameters

  • client_context_id - Identifier passed by the client that is used to identify an active request to be cancelled.

Command (uses the client_context_id used in the /analytics/service example to identify the request)

$ curl -v -u Administrator:password -X DELETE http://localhost:8095/analytics/admin/active_requests -d client_context_id=xyz

Sample response

* Server auth using Basic with user 'Administrator'
> DELETE /analytics/admin/active_requests/?client_context_id=xyz HTTP/1.1
> Host: localhost:8095
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.43.0
> Accept: */*
>
< HTTP/1.1 200 OK
< content-length: 0
< connection: close
<

Cluster Restart API

Description Restarts all Analytics Service nodes in the cluster.

Method POST

Endpoint /analytics/cluster/restart

Authentication A user with one of the following RBAC roles:

  • Full Admin

  • Cluster Admin

Parameters

  • None

Command

$ curl -v -u Administrator:password -X POST http://localhost:8095/analytics/cluster/restart

Sample response

* Connected to localhost (127.0.0.1) port 8095 (#0)
* Server auth using Basic with user 'Administrator'
> POST /analytics/cluster/restart HTTP/1.1
> Host: localhost:8095
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.60.0
> Accept: */*
>
< HTTP/1.1 202 Accepted
< content-type: application/json; charset=utf-8
< content-length: 401
< connection: close
<
{
  "cluster" : {
    "metadata_node" : "edfb6de9c91d7fb36399fea3ce620c5c",
    "ncs" : [ {
      "node_id" : "edfb6de9c91d7fb36399fea3ce620c5c",
      "partitions" : [ {
        "active" : true,
        "partition_id" : "partition_0"
      } ],
      "pid" : 5763,
      "state" : "ACTIVE"
    } ],
    "state" : "ACTIVE"
  },
  "date" : "Wed Oct 10 15:35:56 BST 2018",
  "status" : "SHUTTING_DOWN"
* Closing connection 0
}

Node Restart API

Description Restarts the specified Analytics Service node.

Method POST

Endpoint /analytics/node/restart

Authentication A user with one of the following RBAC roles:

  • Full Admin

  • Cluster Admin

Parameters

  • None

Command

$ curl -v -u Administrator:password -X POST http://localhost:8095/analytics/node/restart

Sample response

* Connected to localhost (127.0.0.1) port 8095 (#0)
* Server auth using Basic with user 'Administrator'
> POST /analytics/node/restart HTTP/1.1
> Host: localhost:8095
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.60.0
> Accept: */*
>
< HTTP/1.1 202 Accepted
< content-length: 29
<
* Connection #0 to host localhost left intact
{"status": "restarting node"}

Service Configuration API

Description Views or modifies service-level parameters, which apply to all nodes running the Analytics service.

For configuration changes to take effect, you must restart the Analytics cluster using the Cluster Restart API.

Method GET, PUT

  • The GET method returns the list of configurable service-level parameters and their current values.

  • The PUT method enables you to change one or more of these parameters. If you provide an invalid parameter name or value, the whole request is rejected with HTTP response code 400.

Endpoint /analytics/config/service

Authentication A user with one of the following RBAC roles:

  • Full Admin

  • Cluster Admin

Parameters See Configuration Parameters for a complete list of service-level parameters.

By default, the API accepts parameters using the application/x-www-form-urlencoded MIME type. You can specify the application/json MIME type using the Content-Type header of the PUT request.

Command — GET

$ curl -v -u Administrator:password http://localhost:8095/analytics/config/service

Sample response

* Connected to localhost (127.0.0.1) port 8095 (#0)
* Server auth using Basic with user 'Administrator'
> GET /analytics/config/service HTTP/1.1
> Host: localhost:8095
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.60.0
> Accept: */*
>
< HTTP/1.1 200 OK
< content-length: 1048
<
{
  "activeMemoryGlobalBudget" : 67108864,
  "activeStopTimeout" : 3600,
  "activeSuspendTimeout" : 3600,
  "analyticsHttpRequestQueueSize" : 256,
  "analyticsHttpThreadCount" : 16,
  "clusterConnectRetries" : 5,
  "compilerFramesize" : 32768,
  "compilerGroupmemory" : 33554432,
  "compilerJoinmemory" : 33554432,
  "compilerParallelism" : 0,
  "compilerSortmemory" : 33554432,
  "coresMultiplier" : 3,
  "deadlockWatchdogHaltDelaySeconds" : 120,
  "deadlockWatchdogPollSeconds" : 300,
  "jobHistorySize" : 10,
  "jobQueueCapacity" : 4096,
  "jvmArgs" : null,
  "logLevel" : "DEBUG",
  "maxWebRequestSize" : 52428800,
  "netBufferCount" : 1,
  "netThreadCount" : 1,
  "resultSweepThreshold" : 60000,
  "resultTtl" : 86400000,
  "storageBuffercacheMaxopenfiles" : 2147483647,
  "storageBuffercachePagesize" : 131072,
  "storageMaxActiveWritableDatasets" : 8,
  "storageMemorycomponentNumcomponents" : 2,
  "storageMemorycomponentPagesize" : 131072,
  "threaddumpFrequencySeconds" : 300,
  "threaddumpLogLevel" : "DEBUG",
  "traceCategories" : [ ]
* Connection #0 to host localhost left intact
}

Command — PUT

$ curl -v -u Administrator:password -X PUT -d jobHistorySize=5 http://localhost:8095/analytics/config/service

Sample response

* Connected to localhost (127.0.0.1) port 8095 (#0)
* Server auth using Basic with user 'Administrator'
> PUT /analytics/config/service HTTP/1.1
> Host: localhost:8095
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.60.0
> Accept: */*
> Content-Length: 16
> Content-Type: application/x-www-form-urlencoded
>
* upload completely sent off: 16 out of 16 bytes
< HTTP/1.1 200 OK
< connection: keep-alive
< content-length: 0
<
* Connection #0 to host localhost left intact

Node Configuration API

Description Views or modifies node-specific parameters, which apply to the node receiving the request.

For configuration changes to take effect, you must restart the node using the Node Restart API, or restart the Analytics cluster using the Cluster Restart API.

Method GET, PUT

  • The GET method returns the list of configurable node-level parameters and their current values on this node.

  • The PUT method enables you to change one or more of these parameters on this node. If you provide an invalid parameter name or value, the whole request is rejected with HTTP response code 400.

Endpoint /analytics/config/node

Authentication A user with one of the following RBAC roles:

  • Full Admin

  • Cluster Admin

Parameters See Configuration Parameters for a complete list of node-specific parameters.

By default, the API accepts parameters using the application/x-www-form-urlencoded MIME type. You can specify the application/json MIME type using the Content-Type header of the PUT request.

Command — GET

$ curl -v -u Administrator:password http://localhost:8095/analytics/config/node

Sample response

* Connected to localhost (127.0.0.1) port 8095 (#0)
* Server auth using Basic with user 'Administrator'
> GET /analytics/config/node HTTP/1.1
> Host: localhost:8095
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.60.0
> Accept: */*
>
< HTTP/1.1 200 OK
< content-length: 114
<
{
  "jvmArgs" : null,
  "storageBuffercacheSize" : 325320704,
  "storageMemorycomponentGlobalbudget" : 325320704
* Connection #0 to host localhost left intact
}

Command — PUT

$ curl -v -u Administrator:password -X PUT -d storageBuffercacheSize=162660352 http://localhost:8095/analytics/config/node

Sample response

* Connected to localhost (127.0.0.1) port 8095 (#0)
* Server auth using Basic with user 'Administrator'
> PUT /analytics/config/node HTTP/1.1
> Host: localhost:8095
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.60.0
> Accept: */*
> Content-Length: 32
> Content-Type: application/x-www-form-urlencoded
>
* upload completely sent off: 32 out of 32 bytes
< HTTP/1.1 200 OK
< connection: keep-alive
< content-length: 0
<
* Connection #0 to host localhost left intact