{"id":1866,"date":"2015-01-28T09:12:42","date_gmt":"2015-01-28T09:12:42","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=1866"},"modified":"2025-06-13T23:49:52","modified_gmt":"2025-06-14T06:49:52","slug":"n1ql-dp4-java-sdk","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/n1ql-dp4-java-sdk\/","title":{"rendered":"Preview using N1QL DP4 from the Java SDK"},"content":{"rendered":"

As some of you may know, the Query Team over at Couchbase have been working hard on a new and exciting feature, N1QL<\/a>, which brings the power of query languages (like SQL) to Couchbase.<\/p>\n

They just release Developer Preview 4 of N1QL (see the blog post here<\/a>), with a bunch of improvements, REST APIs, etc…<\/p>\n

We are happy to announce that a Developer Preview of the Java SDK compatible with N1QL DP4 is now available. Query management underwent a host of changes in this version, which better reflects the state it will be in 2.1 (at which time N1QL should also gain General Availability stability).<\/p>\n

How to Get the Code and Use the Feature<\/h2>\n

To get N1QL and activate it, please see the intro documentation<\/a><\/strong>! There are notably steps to activate N1QL indexing on your buckets.<\/p>\n

UPDATE:\u00a0<\/b>A second developer preview of the SDK is out, pom and links below have been updated accordingly. Scroll to the bottom to see changes…<\/p>\n

To grab the code for this Developer Preview, use the following snippet in your Maven pom.xml<\/code> or download the core-io<\/a> and java-client<\/a> jars directly.<\/p>\n

\n
\r\n    \r\n        com.couchbase.client\r\n        java-client\r\n        2.1.0-dp2\r\n    \r\n\r\n\r\n\r\n    \r\n        couchbase\r\n        couchbase repo\r\n        https:\/\/files.couchbase.com\/maven2\r\n        false\r\n    \r\n\r\n<\/code><\/pre>\n
\n
Since this is an experimental feature, you need to explicitly activate it in the SDK. This can be done in two ways: passing -Dcom.couchbase.queryEnabled=true<\/code> as a JVM parameter or using CoreEnvironment<\/code> when initializing the Cluster<\/code> in code:<\/p>\n
To reproduce this blog’s examples (which build one upon another, ie copy all the snippets in one Java class to get a full working example<\/em>), you can also use the code below to generate two documents that can be queried:<\/p>\n
What Changed Since 2.0.3 \/ N1QL DP3?<\/h2>\n
Most notable changes are described below.<\/p>\n
Query<\/code> interface renamed to Statement<\/code><\/h3>\n
In N1QL, a complete query is composed at a minimum of a Statement (eg. SELECT * FROM default<\/code>), but can also have positional\/named values and additional request parameters (like server-side timeouts, scan consistency, …).<\/p>\n
The Query<\/code> interface in previous versions was just representing this statement component, and thus has been renamed to Statement<\/code>.<\/p>\n
Query<\/code> class hierarchy introduced<\/h3>\n
Query<\/code> has in fact been kept, but to represent the whole N1QL query. A hierarchy of class have been introduced, representing queries from the simplest (a single statement, SimpleQuery<\/code>) to more advanced ones (ParametrizedQuery<\/code>, PreparedQuery<\/code>).<\/p>\n
Queries can be constructed via factory methods on the Query<\/code> abstract class.<\/p>\n
One can issue queries with advanced statements not covered by the DSL using the methods that take a String as statement, for example to ensure there’s a N1QL index on our target bucket:<\/p>\n
Parameters for statements and queries<\/h3>\n
DP4 introduces the concept of parametrized statements. These statements have placeholders that can be filled by the server by passing their values in the query. Placeholders are either named (with the $name<\/code> format) or positional (with the $1<\/code> format).<\/p>\n
Such queries are represented by a ParametrizedQuery<\/code>, taking values in the form of a JsonObject<\/code> of name-value pairs for named placeholders or JsonArray<\/code> of values for positional placeholders. Note:<\/strong> There’s currently a bug in N1QL DP4 that prevents named parameters to work, use positional parameters instead.<\/em><\/p>\n
Furthermore, QueryParams<\/code> describes all remaining query parameters that are supported by the SDK: client context ID, server-side timeouts, scan consistencies. They can be added to any request using the ad-hoc Query<\/code> factory method.<\/p>\n
Prepared Statements<\/h3>\n
Another big new feature of N1QL DP4 is the introduction of prepared statements. Such statements are built in two steps: – analyze the statement and produce a query plan. – execute the query plan and return the results.<\/p>\n
The preparation step, returning a query plan, can be skipped after first occurence provided the plan has been cached somewhere by the user. This allows the server to skip a step which is a gain in time.<\/p>\n
A QueryPlan<\/code> can be obtained from the server by calling Bucket.prepare(s)<\/code>, s<\/strong> being any Statement<\/code>. This object can be cached and reuse multiple times later.<\/p>\n
To execute a plan, use Bucket.query(Query.prepared(plan))<\/code>. Note that the prepared<\/code> factory method can also accept query parameters and placeholder values (as long as the original statement had the corresponding placeholders).<\/p>\n
Changes to result format<\/h3>\n
DP4 introduced several changes in the format of the server response, which have been reflected in the SDK, in AsyncQueryResult<\/code> (the synchronous version QueryResult<\/code> has similar changes):<\/p>\n