Java Analytics SDK Quickstart Guide
Install, connect, try. A quick start guide to get you up and running with Enterprise Analytics and the Java Analytics SDK.
Enterprise Analytics is a real-time analytical database (RT-OLAP) for real time apps and operational intelligence. Although maintaining some syntactic similarities with the operational SDKs, the Java Analytics SDK is developed from the ground-up for column-based analytical use cases, and supports streaming APIs to handle large datasets.
Before You Start
Install and configure an Enterprise Analytics Cluster.
Maven Project Template
The SDK’s source code repository includes an example Maven project you can copy to get started quickly.
Adding the SDK to an Existing Project
Declare a dependency on the SDK using its Maven Coordinates.
To see log messages from the SDK, include an SLF4J binding in your project.
Connecting and Executing a Query
Java Analytics SDK 1.1 adds support for JWT and client certificate authentication, as well as a new Server Asynchronous Request API that uses request handles to fetch results. Introduced in the self-managed Enterprise Analytics Server 2.2, this API eliminates the need for long-running server connections.
The examples in this first section of the page are for the standard API — async on the client side — working with Enterprise Analytics 2.0 and later (with Server Asynchronous Request API examples following in the Server Async section). You can still use this API with Enterprise Analytics 2.2 and later, in addition to the new API.
Server Synchronous Request API
import com.couchbase.analytics.client.java.Cluster;
import com.couchbase.analytics.client.java.Credential;
import com.couchbase.analytics.client.java.QueryResult;
import java.util.List;
public class Example {
public static void main(String[] args) {
var connectionString = "https://<your_hostname>:" + PORT;
var username = "...";
var password = "...";
try (Cluster cluster = Cluster.newInstance(
connectionString,
Credential.of(username, password),
// The third parameter is optional.
// This example sets the default query timeout to 2 minutes.
clusterOptions -> clusterOptions
.timeout(it -> it.queryTimeout(Duration.ofMinutes(2)))
)) {
// Execute a query and buffer all result rows in client memory.
QueryResult result = cluster.executeQuery("select 1");
result.rows().forEach(row -> System.out.println("Got row: " + row));
// Execute a query and process rows as they arrive from server.
cluster.executeStreamingQuery(
"select 1",
row -> System.out.println("Got row: " + row)
);
// Execute a streaming query with positional arguments.
cluster.executeStreamingQuery(
"select ?=1",
row -> System.out.println("Got row: " + row),
options -> options
.parameters(List.of(1))
);
// Execute a streaming query with named arguments.
cluster.executeStreamingQuery(
"select $foo=1",
row -> System.out.println("Got row: " + row),
options -> options
.parameters(Map.of("foo", 1))
);
}
}
}
Connection String
The connStr in the above example should take the form of "https://<your_hostname>:" + PORT
The default port is 443, for TLS connections.
You do not need to give a port number if you are using port 443 — hostname = "https://<your_hostname>" is effectively the same as `hostname = "https://<your_hostname>:" + "443"
If you are using a different port — for example, connecting to a cluster without a load balancer, directly to the Analytics port, 18095 — or not using TLS,
then see the Connecting to Enterprise Analytics page.
Server Asynchronous Request API
Enterprise Analytics 2.2 introduces a Server Asynchronous Request API. The SDK sends a request, polls for results, and then fetches once the result is available.
static void queryHandleExample(Queryable clusterOrScope) throws InterruptedException, TimeoutException {
String slowStatement = """
SELECT COUNT (1) AS c
FROM
ARRAY_RANGE(0,10000) AS d1,
ARRAY_RANGE(0,10000) AS d2
""";
Duration timeout = Duration.ofMinutes(15);
QueryHandle queryHandle = clusterOrScope.startQuery(
slowStatement,
opt -> opt.timeout(timeout)
);
QueryResultHandle resultHandle = waitForResult(queryHandle, timeout);
try {
// Process rows one by one as they arrive from the server.
QueryMetadata metadata = resultHandle.streamRows(row -> System.out.println("Got row: " + row));
System.out.println("Got metadata: " + metadata);
// Alternatively, if the result is known to fit in memory:
QueryResult buffered = resultHandle.bufferRows();
System.out.println("Got result: " + buffered);
} finally {
// Tell the server it can forget the result.
resultHandle.discard();
}
}
private static QueryResultHandle waitForResult(
QueryHandle queryHandle,
Duration timeout
) throws InterruptedException, TimeoutException {
final long timeoutNanos = timeout.toNanos();
final long startNanos = System.nanoTime();
while (true) {
QueryStatus status = queryHandle.fetchStatus();
if (status.resultReady()) return status.resultHandle();
System.out.println("Waiting for query to finish; current status: " + status);
long elapsedNanos = System.nanoTime() - startNanos;
if (elapsedNanos > timeoutNanos) {
throw new TimeoutException("Query result not ready after " + timeout);
}
SECONDS.sleep(1); // or use exponential backoff
}
}
Migration from Row-Based Analytics
If you are migrating a project from CBAS — our Analytics service on Capella Operational and Couchbase Server, using our operational SDKs — then information on migration can be found in the Enterprise Analytics docs.
In particular, refer to the SDK section of the Enterprise Analytics migration pages.