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