A newer version of this documentation is available.

View Latest

Running Queries

You can run queries using the Analytics Workbench, the command line query tool cbq, or directly through the REST API. For the examples we assume that

  • you’re running a Couchbase node with the Analytics service on localhost (the DNS name in the URL could be different in a Docker or a real cluster setup) and that

  • you authenticate as a user with the "Full Administrator" role with the user name Administrator and the password password (of course you should use different credentials for your installation).

Using the Analytics Workbench

The Analytics Workbench - like the Query Workbench - provides a graphical user interface for query development.

To access the Analytics Workbench open a browser and go to http://localhost:8091, log in, and select the Analytics menu in the Couchbase Web Console.

Enter the following test query and click Execute:

SELECT "Hello, beer!" AS greeting;

The result of this query is an array that contains an single object containing a field "greeting" with the value "Hello, beer!":

workbench results
You must press the Execute button in the Analytics Workbench. Unlike Query Workbench, pressing Enter or Return will not immediately execute a statement because Analytics accepts multi-line statements.

Using the Command Line Query Tool

You can use the command line tool, cbq, to run queries. cbq is the command line shell for executing queries against the Query service as well as the Analytics service in Couchbase.

Run cbq with the following options to specify the user, password, host, and port for the Analytics service:

$ cbq -u Administrator -p password -e "http://localhost:8095"

Enter the query in cbq:

cbq> SELECT "Hello, beer!" AS greeting;
{
    "requestID": "dfb78524-0a2b-4dd3-8b99-1554d8dc0bcd",
    "signature": "*",
    "results": [ {
        "greeting" : "Hello, beer!"
    } ]
    ,
    "status": "success",
    "metrics": {
        "elapsedTime": "21.947426ms",
        "executionTime": "18.042413ms",
        "resultCount": 1,
        "resultSize": 34,
        "processedObjects": 0
    }
}

Here you can see that the result shown in the Analytics Workbench is embedded in an envelope that contains additional information about the request like the requestID, the status, and some metrics.

Using the REST API

You can use the REST API to run Analytics queries. When the cluster is up, requests can be posted to Couchbase Analytics. Access http://localhost:8095/analytics/service that implements the same HTTP interface as the Couchbase Query service. For details, see Analytics REST API.

For example, you can run the query SELECT "Hello, beer!" AS greeting through curl:

$ curl -u Administrator:password -d 'SELECT "Hello, beer!" AS greeting' http://localhost:8095/analytics/service

The request returns:

{
    "requestID": "f1b8451c-f626-46be-b1f8-e9ffc891550b",
    "signature": "*",
    "results": [ { "greeting": "Hello, beer!" }
    ]
    ,
    "status": "success",
    "metrics": {
        "elapsedTime": "28.292741ms",
        "executionTime": "24.82841ms",
        "resultCount": 1,
        "resultSize": 31,
        "processedObjects": 0
    }
}

again including the envelope that we’ve seen in the example above. In addition to submitting queries to the Analytics Service you can also use the REST API for administrative purposes. E.g. you can retrieve version information for the Analytics Service with

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

and access the cluster configuration with

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