Streaming the N1QL results using Java SDK

Hi Couchbase team,

I have a long running N1QL query and it could read a large number of rows. How do I stream the results from Couchbase to the client without waiting for the entire result? Meaning as soon the application receives a chunk of response(i.e. a subset of rows) in the socket (TCP) layer I would like the Java SDK to read it and hands it over to the application.

Is this possible via Java SDK?

NOTE: I tried using Async but I couldn’t really make it work the way I described above. Any pointers or sample code would be helpful.

1 Like


Is there a reason that paging doesn’t work, which is VERY popular with most developers? You can use LIMIT and OFFSET to achieve paging in SQL++ (N1QL):




1 Like

Hi Vishnu,

You could indeed use offset-based pagination as Aaron suggests. A caveat is that offset-based pagination is not stable. If the “full” result set changes while you’re issuing the queries for each page, a document that should be present in the results might get skipped, or a document might appear on more than one page, since a document’s offset could change in between queries. This might be fine, depending on your use case.

It might be worth looking into keyset-based pagination. It takes a bit more work than offset-based pagination, but it’s stable, and tends to perform better when the offset gets large.

If you’d like to stream the whole result set without pagination, the Reactive N1QL Query API is probably the best solution. (The Async API is not good for this, since it doesn’t support streaming the results.) With the Reactive API, you get the rows as a Flux, so you can process each row as it arrives from Couchbase.


1 Like

Thanks David and Biozal.

I’m trying out Reactive N1QL, but I think the program crashes while it calls the hookOnNext() function. It looks like it is not able to Decode the row value “000548c1-bbcc-4755-aefe-36374e724f8f”. My query is a simple query that fetches an array of Strings/Ids.


How do I convert a row into an Object? (So that I can add each rows in the batch into List<Object>).


reactor.core.Exceptions$ErrorCallbackNotImplemented: com.couchbase.client.core.error.DecodingFailureException: Deserialization of content into target class failed; encoded = "000548c1-bbcc-4755-aefe-36374e724f8f"
	Suppressed: com.couchbase.client.core.error.DecodingFailureException: Deserialization of content into target class failed; encoded = "000548c1-bbcc-4755-aefe-36374e724f8f"
Caused by: com.couchbase.client.core.error.DecodingFailureException: Deserialization of content into target class failed; encoded = "000548c1-bbcc-4755-aefe-36374e724f8f"
	at ~[java-client-3.2.6.jar!/:na]
	at$rowsAs$0( ~[java-client-3.2.6.jar!/:na]
	at reactor.core.publisher.FluxMap$MapSubscriber.onNext( ~[reactor-core-3.4.16.jar!/:3.4.16]
	at reactor.core.publisher.EmitterProcessor.drain( ~[reactor-core-3.4.16.jar!/:3.4.16]
	at reactor.core.publisher.EmitterProcessor.subscribe( ~[reactor-core-3.4.16.jar!/:3.4.16]
	at reactor.core.publisher.Flux.subscribe( ~[reactor-core-3.4.16.jar!/:3.4.16]
Caused by: Expected START_OBJECT but got VALUE_STRING
	at ~[java-client-3.2.6.jar!/:na]
	at$000( ~[java-client-3.2.6.jar!/:na]
	at$AbstractJsonValueDeserializer.decodeObject( ~[java-client-3.2.6.jar!/:na]
	at$JsonObjectDeserializer.deserialize( ~[java-client-3.2.6.jar!/:na]
	at$JsonObjectDeserializer.deserialize( ~[java-client-3.2.6.jar!/:na]
	at com.fasterxml.jackson.databind.deser.DefaultDeserializationContext.readRootValue( ~[jackson-databind-!/:]
	at com.fasterxml.jackson.databind.ObjectMapper._readMapAndClose( ~[jackson-databind-!/:]
	at com.fasterxml.jackson.databind.ObjectMapper.readValue( ~[jackson-databind-!/:]


Mono<ReactiveQueryResult> queryResult = cluster.reactive().query(query, queryOptions); 
queryResult.flatMapMany(ReactiveQueryResult::rowsAsObject).subscribe(new BaseSubscriber<JsonObject>() {
                // Number of outstanding requests
                final AtomicInteger oustanding = new AtomicInteger(0);

                protected void hookOnSubscribe(Subscription subscription) {
        " Subscription Done ");
                  request(10); // Batch size

                protected void hookOnNext(JsonObject value) {
                  //"hookOnNext Row value={}", value);
                  if (oustanding.decrementAndGet() == 0) {


It would be great if you could help me resolve this!


Hi Vishnu,

Since your result rows are Strings (not JSON Object nodes), this is the part to change:

Try replacing it with:

result -> result.rowsAs(String.class)

And then change the signature of the hookOnNext method to:

protected void hookOnNext(String value) {


Thanks David. That works!