A newer version of this documentation is available.

View Latest

Analytics REST API

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

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 and that

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

In terms of API stability, the REST APIs for Analytics are volatile in the Developer Preview. They may change significantly in the future.

GET /analytics/version

Description Displays version information.

Authentication

  • None

Parameters

  • None

Command

$ curl -v http://localhost:8095/analytics/version

Sample response

$ curl -v http://localhost:8095/analytics/version
* Connected to localhost (::1) port 8095 (#0)
> GET /analytics/version HTTP/1.1
> Host: localhost:8095
> User-Agent: curl/7.43.0
> Accept: */*
>
< HTTP/1.1 200 OK
< transfer-encoding: chunked
< connection: keep-alive
< content-type: application/json; charset=utf-8
<
{
    "build.date": "Mon Mar 27 18:45:39 PDT 2017",
    "build.number": "651",
    "build.version": "1.0.0-DP2",
    "projects": [
        {
            "name": "build",
            "revision": "452b963f17a52d1f69b04a8e88ef05999703ab9a",
            "upstream": "master"
        },
        {
            "name": "analytics-dcp-client",
            "revision": "34f234700d4a53337269c364976c8bd2ab8f43c5",
            "upstream": "master"
        },
        {
            "name": "analytics",
            "revision": "54ffece620012f068f9f492af140b032a361a039",
            "upstream": "master"
        },
        {
            "name": "asterix-opt",
            "revision": "7c9f33f0a5166f9d7cfac9cdf81e97335be5179d",
            "upstream": "master"
        }
    ]
}

GET /analytics/cluster

Description Returns the cluster information.

Authentication A user with one of the following RBAC roles:

  • Admin

  • Cluster Admin

  • Read-only Admin

Parameters

  • None

Command

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

Sample response

* Connected to localhost (::1) port 8095 (#0)
* Server auth using Basic with user 'Administrator'
> GET /analytics/cluster HTTP/1.1
> Host: localhost:8095
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.43.0
> Accept: */*
>
< HTTP/1.1 200 OK
< transfer-encoding: chunked
< content-type: application/json; charset=utf-8
< connection: close
<
{
  "cc" : {
    "configUri" : "http://localhost:8095/analytics/cluster/cc/config",
    "statsUri" : "http://localhost:8095/analytics/cluster/cc/stats",
    "threadDumpUri" : "http://localhost:8095/analytics/cluster/cc/threaddump"
  },
  "config" : {
    "active.memory.global.budget" : 67108864,
    "auth.port" : 8210,
    "compiler.framesize" : 32768,
    "compiler.groupmemory" : 33554432,
    "compiler.joinmemory" : 33554432,
    "compiler.parallelism" : 0,
    "compiler.sortmemory" : 33554432,
    "default.dir" : "/Users/couchbase/Library/Application Support/Couchbase/var/lib/couchbase/data/@analytics",
    "log.level" : "INFO",
    "max.wait.active.cluster" : 60,
    "messaging.frame.count" : 512,
    "messaging.frame.size" : 4096,
    "metadata.callback.port" : 0,
    "metadata.listen.port" : 0,
    "metadata.node" : "a17499945805ede263549198235e898f",
    "metadata.registration.timeout.secs" : 60,
    "stdin.watch" : false,
    "txn.commitprofiler.enabled" : false,
    "txn.commitprofiler.reportinterval" : 5,
    "txn.job.recovery.memorysize" : 67108864,
    "txn.lock.escalationthreshold" : 1000,
    "txn.lock.shrinktimer" : 5000,
    "txn.lock.timeout.sweepthreshold" : 10000,
    "txn.lock.timeout.waitthreshold" : 60000,
    "txn.log.buffer.numpages" : 8,
    "txn.log.buffer.pagesize" : 131072,
    "txn.log.checkpoint.history" : 0,
    "txn.log.checkpoint.lsnthreshold" : 67108864,
    "txn.log.checkpoint.pollfrequency" : 120,
    "txn.log.partitionsize" : 268435456
  },
  "diagnosticsUri" : "http://localhost:8095/analytics/diagnostics",
  "fullShutdownUri" : "http://localhost:8095/analytics/shutdown?all=true",
  "metadata_node" : "a17499945805ede263549198235e898f",
  "ncs" : [ {
    "configUri" : "http://localhost:8095/analytics/cluster/node/a17499945805ede263549198235e898f/config",
    "node_id" : "a17499945805ede263549198235e898f",
    "partitions" : [ {
      "active" : true,
      "partition_id" : "partition_0"
    }, {
      "active" : true,
      "partition_id" : "partition_1"
    } ],
    "state" : "ACTIVE",
    "statsUri" : "http://localhost:8095/analytics/cluster/node/a17499945805ede263549198235e898f/stats",
    "threadDumpUri" : "http://localhost:8095/analytics/cluster/node/a17499945805ede263549198235e898f/threaddump"
  } ],
  "shutdownUri" : "http://localhost:8095/analytics/shutdown",
  "state" : "ACTIVE",
  "versionUri" : "http://localhost:8095/analytics/version"
}

POST /analytics/service or /query/service

Description Returns result for query as JSON. The alternative /query/service is offered for tools compatibility.

Authentication A user with one of the following RBAC roles:

  • Admin

  • Cluster Admin

  • Read-only Admin

  • Analytics Manager

  • Analytics Reader

Parameters

  • statement - Specifies at least one valid SQL++ statement to run. Required.

  • pretty - If the parameter pretty is given with the value true, the result will be indented. (Optional)

  • client_context_id - Identifier passed by the client that is returned verbatim in the query response. Useful for matching a particular query to a specific caller. (Optional)

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

* Server auth using Basic with user 'Administrator'
> POST /analytics/service HTTP/1.1
> Host: localhost:8095
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 97
>
* upload completely sent off: 97 out of 97 bytes
< HTTP/1.1 200 OK
< transfer-encoding: chunked
< connection: keep-alive
< content-type: application/json; charset=utf-8
<
{
  "requestID": "f7ec4c80-d737-4f10-83cb-b2e04ceedd55",
  "clientContextID": "xyz",
  "signature": "*",
  "results": [ {
    "$1" : 1
  } ]
  ,
  "status": "success",
  "metrics": {
    "elapsedTime": "19.599099ms",
    "executionTime": "18.313067ms",
    "resultCount": 1,
    "resultSize": 15
  }
}

DELETE /analytics/admin/active_requests/

Description Cancels an active request.

Authentication A user with one of the following RBAC roles:

  • Admin

  • Cluster Admin

  • Read-only 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
<

POST /analytics/cluster/restart

Description Restarts the Analytics Service cluster.

Authentication A user with one of the following RBAC roles:

  • Admin

  • Cluster Admin

Parameters

  • None

Command

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

Sample response

* Server auth using Basic with user 'Administrator'
> POST /analytics/cluster/restart HTTP/1.1
> Host: localhost:8095
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.43.0
> Accept: */*
>
< HTTP/1.1 202 Accepted
< content-type: application/json; charset=utf-8
< content-length: 611
< connection: close
<
{
"cluster" : {
    "metadata_node" : "e0128f9812efff7de822bf8ddc6c8077",
    "ncs" : [ {
      "node_id" : "0e1ac1fa572bca9bff73e634dce57bf8",
      "partitions" : [ {
        "active" : true,
        "partition_id" : "partition_1"
      } ],
      "pid" : 55672,
      "state" : "ACTIVE"
    }, {
      "node_id" : "e0128f9812efff7de822bf8ddc6c8077",
      "partitions" : [ {
        "active" : true,
     "partition_id" : "partition_0"
    } ],
    "pid" : 55556,
    "state" : "ACTIVE"
    } ],
    "state" : "ACTIVE"
},
"date" : "Wed Aug 30 12:56:37 PDT 2017",
"status" : "SHUTTING_DOWN"

PUT /analytics/cc/config

Description Modifies the cluster controller configuration.

For the configuration changes to take effect, the Analytics cluster must be restarted using the Restart API.

Authentication A user with one of the following RBAC roles:

  • Admin

  • Cluster Admin

Parameters See Configuration Parameters section for a complete list of the cluster controller parameters.

Command

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

Sample response

* Server auth using Basic with user 'Administrator'
> PUT /analytics/cc/config HTTP/1.1
> Host: localhost:8095
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.43.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
< content-length: 0
< connection: close

PUT /analytics/node/config

Description Modifies a node’s configuration.

For the configuration changes to take effect, the Analytics cluster must be restarted using the Restart API.

Authentication A user with one of the following RBAC roles:

  • Admin

  • Cluster Admin

Parameters See Configuration Parameters section for a complete list of nodes parameters.

Command

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

Sample response

* Server auth using Basic with user 'Administrator'
> PUT /analytics/node/config HTTP/1.1
> Host: localhost:8095
> Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Length: 27
> Content-Type: application/x-www-form-urlencoded
>
* upload completely sent off: 27 out of 27 bytes
< HTTP/1.1 200 OK
< connection: keep-alive
< content-length: 0