Running Queries

Enterprise Edition

You can run queries using the Analytics Workbench, the command line query tool cbq, or directly through the REST API. You can also run Analytics queries using a software development kit (SDK), or via the ODBC or JDBC drivers. 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!":

The Analytics Workbench supports multi-line statements, just like the Query Workbench. You can press the Execute button to execute a statement at any time. You can also execute a statement by typing a semicolon ; at the end of the statement, and then pressing Enter or Return.

The insights sidebar to the right of the Analytics Workbench shows the Analytics dataverses and datasets, and the Couchbase buckets which are being shadowed. When data ingestion is in progress, an indicator to the right of each dataset shows the number of mutations that remain to be synchronized to that dataset. If the indicator is not displayed, then the dataset is up-to-date.

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 'statement=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.

Using the SDKs, ODBC, or JDBC

You can also run Analytics queries using a software development kit (SDK). For details, refer to SDKs and select the required language.

For example, to get more information about running an Analytics query using the Java SDK, refer to Analytics using the Java SDK. A similar page is available for each SDK.

You can also run Analytics queries via the ODBC or JDBC drivers. For details, refer to Couchbase ODBC and JDBC Drivers.